Creación de paquetes RPM con rpmbuild: Guía completa y actualizada

Autor: Joel Barrios Dueñas
Correo electrónico: darkshram en gmail punto com
Sitio de Red: https://www.alcancelibre.org

Licencia Creative Commons
© 1999-2026 Joel Barrios Dueñas. Este manual se distribuye bajo la licencia Creative Commons Reconocimiento-NoComercial-CompartirIgual 4.0 Internacional (CC BY-NC-SA 4.0). Usted es libre de compartir y adaptar el material bajo los siguientes términos: debe dar crédito al autor, no puede utilizarlo para fines comerciales y debe compartir las obras derivadas bajo la misma licencia. La licencia completa está disponible en https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.es.

Introducción y conceptos fundamentales

Construir paquetes RPM constituye una habilidad esencial para administradores de sistemas, desarrolladores y mantenedores de distribuciones Linux. Este manual guía al lector a través del proceso moderno de creación de paquetes, desde los conceptos básicos hasta técnicas avanzadas, garantizando compatibilidad con sistemas como ALDOS —que emplea RPM 4.11.3— y distribuciones contemporáneas basadas sobre Fedora y Red Hat Enterprise Linux (RHEL) que utilizan RPM 4.14 o superior.

Un paquete RPM (RPM Package Manager) es más que un simple archivo contenedor; es un sistema robusto que gestiona metadatos, dependencias, guiones de instrucciones (scripts) de pre y post-instalación, y verificación de integridad. El corazón de este sistema es el archivo de especificación (con extensión .spec), el cual actúa como la «receta» que rpmbuild sigue para compilar el código fuente, organizar los archivos y generar los paquetes binarios y fuente finales.

Esta guía rescata el conocimiento práctico acumulado durante décadas, corrige ambigüedades de documentación antigua y se enfoca en los procedimientos actuales, incluyendo el uso de sistemas de construcción modernos como Meson y CMake. Su enfoque es didáctico: cada sección incluye ejemplos ejecutables que permiten experimentar y contrastar resultados, fomentando un aprendizaje profundo y aplicado.

Preparación del entorno de construcción

Antes de crear el primer paquete, es indispensable configurar un entorno de trabajo adecuado. Ésto implica instalar las herramientas necesarias y establecer la estructura de directorios estándar.

Instalación de las herramientas requeridas

El conjunto mínimo de paquetes para comenzar incluye rpm-build, el compilador gcc y las macros básicas del sistema. La instalación difiere ligeramente entre distribuciones:

Para una experiencia de construcción más completa, se recomiendan paquetes adicionales que proporcionan macros para sistemas de construcción específicos y herramientas de validación:

dnf -y install cmake-rpm-macros perl-srpm-macros pyproject-rpm-macros \
               python-srpm-macros cmake meson rpmlint desktop-file-utils \
               rpmdevtools

La herramienta rpmlint es particularmente valiosa, ya que permite analizar los archivos .spec y los paquetes RPM generados en busca de errores comunes, violaciones de políticas y posibles mejoras, actuando como un validador (linter) esencial para el empaquetador.

Configuración del árbol de directorios

El mandato rpmdev-setuptree ―componente que forma parte del paquete rpmdevtools― crea automáticamente la estructura de directorios estándar para rpmbuild dentro del directorio principal del usuario ($HOME/rpmbuild/). Es posible personalizar esta ubicación, pero para fines didácticos se recomienda seguir la convención establecida.

rpmdev-setuptree

Este mandato genera la siguiente jerarquía:

~/rpmbuild/
├── BUILD/          # Directorio donde se compilan y descomprimen los fuentes.
├── BUILDROOT/      # Área de instalación temporal simulando la raíz del sistema.
├── RPMS/           # Paquetes RPM binarios finales, organizados por arquitectura.
│   ├── x86_64/
│   ├── noarch/
│   └── i686/
├── SOURCES/        # Archivos fuente originales, parches y recursos.
├── SPECS/          # Archivos de especificación (.spec).
└── SRPMS/          # Paquetes RPM fuente (.src.rpm).

Como práctica recomendada, coloque siempre los archivos de código fuente (por ejemplo, archivos .tar.gz), los parches y otros recursos en el directorio SOURCES/. Los archivos .spec deben residir en SPECS/.

Anatomía detallada del archivo .spec

El archivo de especificación es un guion de instrucciones declarativo. Su estructura está dividida en secciones claramente definidas, que rpmbuild procesa en un orden específico. Comprender cada una es fundamental para crear paquetes correctos y mantenibles.

Cabecera: Metadatos del paquete

La cabecera define la identidad y propiedades fundamentales del paquete. Es la primera sección del archivo y utiliza etiquetas simples.

Name:           proyecto
Version:        1.2.3
Release:        1%{?dist}
Summary:        Breve descripción del proyecto en inglés.
Summary(es):    Breve descripción del proyecto en español.

Licencias, URL y fuentes

License:        GPL-3.0-or-later AND MIT
URL:            https://github.com/desarrollador/proyecto
Source0:        %{url}/archive/refs/tags/v%{version}.tar.gz#/%{name}-%{version}.tar.gz
Source1:        %{url}/raw/refs/heads/main/LICENSE

Gestión de arquitecturas

Para equipamiento lógico moderno que ya dista de ser compatible con arquitecturas de 32 bits, es posible restringir las arquitecturas de construcción.

ExclusiveArch:  x86_64 arm64

O bien, utilice lo siguiente para excluir arquitecturas específicas:

ExcludeArch:    %{ix86}

Parches (PatchX)

Los parches permiten aplicar modificaciones al código fuente de los autores originales para adaptarlo al sistema destino, corregir errores o habilitar funcionalidades.

Patch0:         correccion-seguridad.patch
Patch1:         habilitar-caracteristica.patch

Cada archivo .patch listado debe encontrarse en el directorio SOURCES/. Su aplicación se gestiona en la sección %prep.

Dependencias de construcción (BuildRequires)

Ésta es una de las secciones más importantess. Enumera todos los paquetes necesarios para compilar exitosamente el equipamiento lógico. La omisión de una dependencia provocará fallos en el proceso de construcción.

BuildRequires:  gcc
BuildRequires:  meson
BuildRequires:  pkgconfig(glib-2.0) >= 2.72
BuildRequires:  pkgconfig(gtk+-3.0) >= 3.24.0
BuildRequires:  desktop-file-utils
BuildRequires:  /usr/bin/pkg-config

Consejo para determinar dependencias: Inspeccione los archivos de configuración del sistema de construcción (meson.build, configure.ac, CMakeLists.txt) buscando directivas como dependency(), PKG_CHECK_MODULES o pkg_check_modules.

Dependencias de ejecución (Requires, Recommends, Suggests)

Estas etiquetas definen qué necesita el paquete para funcionar después de instalarse.

Requires:       hicolor-icon-theme
Requires:       libproyecto%{?_isa} = %{version}-%{release}
%if 0%{?fedora} >= 24 || 0%{?rhel}
Recommends:     gnome-shell >= 40.0
Suggests:       gnome-online-accounts >= 3.38
%else
Requires:       gnome-shell >= 40.0
# En ALDOS, a menudo se omite Suggests por ser demasiado blando.
%endif

Relaciones entre paquetes (Conflicts, Obsoletes, Provides)

Conflicts:      ejemplo2 >= 2.0-1
Obsoletes:      otro-paquete-parecido < 2.3.4.5-1
Provides:       python39dist(modulo_python) = %{version}

📓 Nota de experiencia: Añadir Conflicts junto con Obsoletes garantiza que RPM aplique una lógica robusta al gestionar el orden de instalación o actualización, particularmente cuando los cambios incluyen transiciones de arquitectura (por ejemplo, de *.x86_64.rpm a *.noarch.rpm, algo frecuente en subpaquetes de documentación), cambio de nombre de subpaquetes o cuando componentes migran del paquete principal a uno secundario.

# Conflcito con otro paquete que se reemplazará
Conflicts:      otro-paquete-parecido < 2.3.4.5-1
Obsoletes:      otro-paquete-parecido < 2.3.4.5-1
Provides:       otro-paquete-parecido = %{version}-%{release}
Provides:       otro-paquete-parecido%{?_isa} = %{version}-%{release}
# Cambio de nombre de subpaquete, reemplazando al anterior
Conflicts:      proyecto-libs < 1.2.3-1
Obsoletes:      proyecto-libs < 1.2.3-1
Provides:       proyecto-libs = %{version}-%{release}
Provides:       proyecto-libs%{?_isa} = %{version}-%{release}

Sección %description

Aquí se coloca una descripción larga y detallada del paquete. Se permite formateo básico y es posible proporcionar descripciones localizadas.

%description
Descripción detallada en inglés. Se recomienda limitar las líneas
a un máximo de 70 caracteres para una correcta visualización en
terminales de 80 columnas. Evite el uso de caracteres como
`&` que pueden complicar herramientas como `repoview`; prefiera
`and` en su lugar.

%description -l es
Descripción detallada en español.

Sistemas de construcción soportados

Una de las fortalezas de rpmbuild es su capacidad para integrarse con los sistemas de construcción más populares. Las macros especializadas simplifican enormemente las secciones %build, %install y %check.

Meson (Recomendado para proyectos modernos)

Meson se ha convertido en el sistema de construcción predominante para nuevos proyectos debido a su velocidad y legibilidad.

%build
%meson \
    -Dopcion_booleana=true \
    -Dopcion_cadena="valor" \
    -Ddocs=%{?with_docs:enabled}%{!?with_docs:disabled} \
    %{nil}
%meson_build

%install
%meson_install

%check
%meson_test

La macro %{nil} al final de las listas de opciones es una buena práctica, ya que permite ordenar las opciones alfabéticamente sin riesgo de omitir una barra invertida final.

Autotools (Automake/Autoconf - Tradicional)

Aún ampliamente utilizado por proyectos consolidados, aunque actualmente muchos de éstos están migrando a otras alternativas como Meson y Cmake.

%build
%configure \
    --prefix=%{_prefix} \
    --sysconfdir=%{_sysconfdir} \
    %{nil}
%make_build

%install
%make_install

CMake

Muy común en proyectos de C++, Qt, KDE, aplicaciones gráficas y equipamiento lógico científico.

%build
%cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=ON \
    -Wno-dev \
    %{nil}
%cmake_build

%install
%cmake_install

Gestión de subpaquetes y metapaquetes

Los paquetes RPM complejos a menudo se dividen en componentes lógicos (bibliotecas, utilidades de desarrollo, documentación) para ofrecer mayor flexibilidad al usuario final. Ésto se logra con la directiva %package.

Creación de un subpaquete

%package -n libproyecto
Summary:        Biblioteca compartida para el proyecto.
Requires:       %{name}%{?_isa} = %{version}-%{release}

%description -n libproyecto
Esta biblioteca proporciona la funcionalidad central del proyecto.

Especificación de archivos por subpaquete (%files)

La sección %files lista exhaustivamente cada archivo que pertenece al paquete. Los archivos ausentes en la lista se excluyen.

%files -n libproyecto
%license LICENSE-LGPL.txt
%{_libdir}/libproyecto.so.1*
%files -n libproyecto-devel
%doc API.md
%{_includedir}/proyecto/
%{_libdir}/libproyecto.so
%{_libdir}/pkgconfig/libproyecto.pc

Macros especiales en la lista de archivos

%files
%license GPL-3.0.txt
%doc README.md AUTHORS
%config(noreplace) %{_sysconfdir}/%{name}/config.ini
%dir %attr(0755, root, root) %{_localstatedir}/lib/%{name}
%ghost %attr(0644, root, root) %{_localstatedir}/lib/%{name}/data.db

Proceso completo de construcción y validación

Con el archivo .spec listo y las fuentes en SOURCES/, se inicia el ciclo de construcción.

Mandatos básicos de rpmbuild

Estos mandatos permiten ejecutar y depurar partes específicas del proceso.

Los paquetes generados se encontrarán en:

Construcción aislada con mock

Para garantizar que el paquete diste de depender de bibliotecas o herramientas instaladas sólo en el sistema del desarrollador, se utiliza mock. Crea un entorno de construcción limpio y reproducible.

# Instalar mock (en Fedora/RHEL/ALDOS)
dnf -y install mock

# Agregar su usuario al grupo 'mock' (requiere cerrar y abrir sesión)
usermod -a -G mock $USER

# Construir un paquete fuente en un entorno aislado (ej: para ALDOS)
mock -r aldos-14-x86_64 ~/rpmbuild/SRPMS/proyecto-1.2.3-1.aldos.src.rpm

Los paquetes resultantes de mock se ubican en /var/lib/mock/<perfil>/result/. Recuerde mover todos los paquetes resultantes a una ubicación permanente antes de volver a utilizar mock, de otro modo éstos serán borrados en la siguiente ejecución. El uso de mock es indispensable para empaquetado profesional y garantizar la portabilidad del paquete.

Flujo de trabajo automatizado con un guion de instrucciones

Para evitar la pérdida de paquetes generados y mantener un repositorio local ordenado, resulta útil automatizar el proceso completo. El siguiente guion de instrucciones (script) ilustra una metodología probada en producción para ALDOS, que construye para múltiples arquitecturas, gestiona los resultados y actualiza un repositorio local.

Objetivos del flujo:

  1. Optimizar recursos: Cambia temporalmente el perfil de energía del sistema a balanced para un rendimiento de compilación óptimo sin afectar la capacidad de respuesta del escritorio.
  2. Garantizar limpieza: Limpia la caché de mock antes de cada construcción para evitar contaminación entre ejecuciones.
  3. Preservar resultados: Mueve los paquetes generados (*.rpm y *.src.rpm) inmediatamente a directorios de repositorio designados, protegiéndolos de ser sobrescritos en la próxima ejecución de mock.
  4. Mantener el repositorio: Elimina versiones antiguas de paquetes y regenera los metadatos del repositorio automáticamente.

Advertencia: Jamás deje los paquetes RPM dentro del directorio de resultados predeterminado de mock (/var/lib/mock/*/result). Este directorio se limpia en construcciones posteriores. Mover los resultados a un destino final seguro inmediatamente después de la construcción es un hábito indispensable.

A continuación, el guion de referencia con comentarios explicativos:

#!/bin/bash

# Función para reconstruir los metadatos del repositorio sólo si es
# necesario
function RebuildRepo {
    if [ ! -d /var/www/updates/i686/.repodata ]; then
        sudo createrepo_c --excludes=*.src.rpm --changelog-limit=5 -d -p \
            --unique-md-filenames --update --xz \
            /var/www/updates/i686/
    fi
    if [ ! -d /var/www/updates/x86_64/.repodata ]; then
        sudo createrepo_c --excludes=*.src.rpm --changelog-limit=5 -d -p \
            --unique-md-filenames --update --xz \
            /var/www/updates/x86_64/
    fi
    if [ ! -d /var/www/updates/source/.repodata ]; then
        sudo createrepo_c --changelog-limit=5 -d -p \
            --unique-md-filenames --update --xz \
            /var/www/updates/source/
    fi
    sudo chown -R jbarrios:jbarrios /var/www/updates
}

# 1. Guardar y optimizar el perfil de energía del sistema
CURRENT_PROFILE=$(tuned-adm active | grep -oP 'Current active profile: \K.*')
sudo tuned-adm profile balanced

# 2. Construir para arquitectura i686 (32 bits)
mock -r aldos-14-i386-tmpfs --scrub=yum-cache && \
mock -r aldos-14-i386-tmpfs --rebuild --no-clean \
    --resultdir=/var/lib/mock/aldos-14-i386-tmpfs/result/ $1 \
&& \
sudo rm -f /var/lib/mock/aldos-14-i386-tmpfs/result/*debuginfo*.rpm \
&& \
sudo mv /var/lib/mock/aldos-14-i386-tmpfs/result/*.src.rpm \
    /var/www/updates/source/ \
&& \
sudo mv /var/lib/mock/aldos-14-i386-tmpfs/result/*.rpm \
    /var/www/updates/i686/

# 3. Construir para arquitectura x86_64 (64 bits)
mock -r aldos-14-x86_64-tmpfs --scrub=yum-cache && \
mock -r aldos-14-x86_64-tmpfs --rebuild --no-clean \
    --resultdir=/var/lib/mock/aldos-14-x86_64-tmpfs/result/ $1 \
&& \
sudo rm -f /var/lib/mock/aldos-14-x86_64-tmpfs/result/*debuginfo*.rpm \
    /var/lib/mock/aldos-14-x86_64-tmpfs/result/*.src.rpm \
&& \
sudo mv /var/lib/mock/aldos-14-x86_64-tmpfs/result/*.rpm \
    /var/www/updates/x86_64/

# 4. Limpieza final y mantenimiento del repositorio
rm -fv $1 \
&& \
sudo repomanage -k1 --old /var/www/updates/i686/ | xargs sudo rm -fv && \
sudo repomanage -k1 --old /var/www/updates/x86_64/ | xargs sudo rm -fv && \
sudo repomanage -k1 --old /var/www/updates/source/ | xargs sudo rm -fv && \
RebuildRepo

# 5. Restaurar el perfil de energía original del sistema
sudo tuned-adm profile "$CURRENT_PROFILE"

Modo de uso: Ejecute el guion pasándole la ruta a un paquete fuente (.src.rpm) como argumento: ./paquete-mock-tmpfs.sh mi-paquete-1.0.0-1.aldos.src.rpm.

Este flujo automatizado constituye la base de un sistema de construcción confiable, asegurando que cada paquete tenga un destino final conocido y que el repositorio local permanezca consistente y listo para su distribución.

Firma de paquetes con GnuPG

Firmar los paquetes garantiza su autenticidad e integridad. Primero, necesita una clave GPG configurada.

# Firmar todos los paquetes RPM generados
rpm --addsign ~/rpmbuild/RPMS/*/*.rpm ~/rpmbuild/SRPMS/*.rpm

# Verificar la firma de los paquetes RPM
rpm -K ~/rpmbuild/RPMS/x86_64/proyecto-*.rpm

Consejos avanzados y mejores prácticas

La claridad y el orden en el archivo .spec son tan cruciales como su corrección técnica. Procure organizar las dependencias de manera lógica, utilice comentarios para explicar decisiones complejas y valide cada cambio con rpmlint. Un archivo bien estructurado y documentado facilita el mantenimiento a largo plazo y sirve como referencia invaluable para otros empaquetadores.

Macro %autosetup para gestión automática de parches

En lugar de aplicar parches manualmente con %patch, el macro %autosetup automatiza el proceso de descompresión y aplicación de todos los parches listados.

%prep
%autosetup -p1

Condicionales para funcionalidades opcionales (%bcond_with)

Para habilitar o deshabilitar la construcción de componentes opcionales (como documentación) de manera flexible:

# Definir una condición (por defecto, sin documentación)
%bcond_with docs

# En la sección %build, usarla condicionalmente
%if %{with docs}
%meson -Ddocs=enabled
%endif

Luego, al construir, puede activar la opción: rpmbuild -ba --with docs proyecto.spec.

Manejo de iconos y cachés (%post, %postun)

Para paquetes que instalan iconos en temas como hicolor, es necesario actualizar la caché de iconos. En ALDOS ésto debe hacerse explícitamente, mientras que en Fedora/RHEL suele ser automático.

%if !0%{?fedora} >= 24 || !0%{?rhel}
%post
/bin/touch --no-create %{_datadir}/icons/hicolor &>/dev/null || :

%postun
if [ $1 -eq 0 ] ; then
    /bin/touch --no-create %{_datadir}/icons/hicolor &>/dev/null || :
    /usr/bin/gtk-update-icon-cache %{_datadir}/icons/hicolor &>/dev/null || :
fi

%posttrans
/usr/bin/gtk-update-icon-cache %{_datadir}/icons/hicolor &>/dev/null || :
%endif

Compatibilidad de bibliotecas (%post -p /sbin/ldconfig)

Para paquetes que instalan bibliotecas compartidas, es crucial ejecutar ldconfig tras la instalación o desinstalación. Nuevamente, ésto sólo es necesario ALDOS, mientras que en Fedora/RHEL suele ser automático.

%if !0%{?fedora} >= 24 || !0%{?rhel}
%post -n libproyecto -p /sbin/ldconfig
%postun -n libproyecto -p /sbin/ldconfig
%endif

Plantillas de referencia

Las siguientes plantillas sirven como punto de partida sólido para sus propios paquetes. Sin embargo, recuerde que cada proyecto es único: adapte los nombres, versiones, dependencias y opciones de construcción a sus necesidades específicas. Utilice estas plantillas como un esqueleto que deberá completar con la lógica particular de su equipamiento lógico (software).

Plantilla completa (proyecto.spec)

A continuación se presenta una plantilla consolidada que incorpora las técnicas y mejores prácticas discutidas en este manual. Los comentarios se han reducido para mayor claridad.

Name:           proyecto
Version:        1.2.3
Release:        1%{?dist}
Summary:        A comprehensive software suite
Summary(es):    Una suite de equipamiento lógico integral

License:        GPL-3.0-or-later AND MIT
URL:            https://github.com/desarrollador/proyecto
Source0:        %{url}/archive/refs/tags/v%{version}.tar.gz#/%{name}-%{version}.tar.gz

ExclusiveArch:  x86_64 arm64

Patch0:         security-fix.patch

BuildRequires:  gcc
BuildRequires:  meson
BuildRequires:  pkgconfig(glib-2.0) >= 2.72
BuildRequires:  desktop-file-utils

%if 0%{?fedora} >= 24 || 0%{?rhel}
Recommends:     gnome-shell >= 40.0
%else
Requires:       gnome-shell >= 40.0
%endif

Requires:       hicolor-icon-theme

%description
This is a detailed description of the main package in English.

%description -l es
Ésta es una descripción detallada del paquete principal en español.

%package -n libproyecto
Summary:        Shared library for the project
Summary(es):    Biblioteca compartida para el proyecto
License:        LGPL-3.0-or-later

%description -n libproyecto
This library provides the core functionality.

%description -l es -n libproyecto
Ésta biblioteca provee la funcionalidad principal.

%prep
%autosetup -p1

%build
%meson \
    -Ddocs=disabled \
    %{nil}
%meson_build

%install
%meson_install
%find_lang %{name}

%check
%meson_test

%if !0%{?fedora} >= 24 || !0%{?rhel}
%post -n libproyecto -p /sbin/ldconfig
%postun -n libproyecto -p /sbin/ldconfig
%endif

%files -f %{name}.lang
%license LICENSE-GPL.txt
%doc README.md AUTHORS
%{_bindir}/%{name}
%{_datadir}/applications/%{name}.desktop

%files -n libproyecto
%license LICENSE-LGPL.txt
%{_libdir}/libproyecto.so.1

%changelog
* Tue Dec 30 2025 Developer Name <developer@example.com> - 1.2.3-1
- Initial package for version 1.2.3.
- Validated spec file with rpmlint.

Plantilla mínima (proyecto2.spec)

Ideal para proyectos simples que utilizan Meson.

Name:           proyecto2
Version:        2.3.4
Release:        1%{?dist}
Summary:        A simple example package.

License:        GPL-3.0-or-later
URL:            https://github.com/desarrollador/proyecto2
Source0:        %{url}/archive/refs/tags/v%{version}.tar.gz#/%{name}-%{version}.tar.gz

BuildRequires:  gcc
BuildRequires:  meson
BuildRequires:  /usr/bin/pkg-config

Requires:       proyecto >= 1.2.3

%description
A simple second project packaged as an RPM.

%prep
%autosetup -p1

%build
%meson
%meson_build

%install
%meson_install

%check
%meson_test

%files
%license LICENSE
%doc README.md
%{_bindir}/%{name}
%{_mandir}/man1/%{name}.1.gz

%changelog
* Wed Dec 31 2025 Developer Name <developer@example.com> - 2.3.4-1
- Initial package.

Conclusión

Construir paquetes RPM de calidad es un proceso meticuloso que combina precisión técnica con atención al detalle. Esta guía ha cubierto el flujo de trabajo completo: desde la configuración del entorno y la redacción de un archivo .spec robusto, hasta la construcción aislada y la firma de paquetes.

La clave del éxito reside en:

  1. Validar constantemente con rpmlint.
  2. Construir en entornos aislados con mock para garantizar la reproducibilidad.
  3. Documentar claramente los cambios en %changelog.
  4. Mantener la compatibilidad mediante condicionales cuando se apunta a múltiples versiones de RPM (como ALDOS vs. Fedora/RHEL).

Con estos conocimientos y las plantillas proporcionadas, está preparado para empaquetar sus propios proyectos y contribuir paquetes a la comunidad de equipamiento lógico libre. El esfuerzo invertido en aprender rpmbuild se traduce en un control total sobre la distribución e instalación de equipamiento lógico en los sistemas Linux empresariales y personales.