Empaquetado de adjuntos para GNU Emacs

Propósito

El propósito de este documento es promover las buenas prácticas en el empaquetado de complementos para GNU Emacs y fomentar el envío de más paquetes de complementos de Emacs a la colección de paquetes, proporcionando plantillas de archivos spec fáciles de usar.

Notas importantes en estas Directrices

Las pautas en las siguientes secciones hacen un uso extensivo de las macros definidas en /usr/lib/rpm/macros.d/macros.emacs lo cal es instalado con el paquete emacs-common.

Hay dos casos distintos en los que es necesario tener en cuenta estas directrices:

  1. Este caso se refiere a la situación en la que el propósito principal de un paquete es proporcionar funcionalidad adicional para Emacs, y dicho paquete no cumple ninguna función sin la presencia de Emacs. Un ejemplo de este caso es el lector de correo de VM, tal como se incluye en emacs-vm. En adelante, lo denominaremos Caso I.

  2. Este caso se refiere a la situación en la que la funcionalidad principal de un paquete no requiere Emacs, pero el paquete también incluye archivos Elisp auxiliares para proporcionar soporte en Emacs. En adelante, lo denominaremos Caso II.

Nombre de paquetes y organización de subpaquetes

Caso I

Cuando un paquete es principalmente un complemento para Emacs, el paquete principal debería invocarse emacs-foo.

Caso II

Where a package’s principal functionality does not require Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in Emacs, these should be included in the main package which will need to Require the emacs-filesystem package. More detail below.

Package contents

Caso I

Files specific to GNU Emacs should be placed in the main package, emacs-foo. This should contain the elisp source, compiled elisp and any other files needed to use the package or sub-package with GNU Emacs.

Caso II

The compiled elisp source and the elisp source files should be packaged as part of the main package, and not split out into separate packages.

File locations

File locations for GNU Emacs add-on (sub-)packages:

  • All elisp and related files for the package should be installed in the directory %{_emacs_sitelispdir}/foo.

  • If the package requires a startup file this should be called foo-init.el and be placed in %{_emacs_sitestartdir}.

Requisitos de Paquete

Caso I

Los Requisitos del Paquete para los (sub-)paquetes adjuntos de GNU Emacs:

  • Donde sea relevante emacs-foo debe tener Requires: emacs-common-tal= %{version}-%{release}

  • emacs-foo debe tener Requires: emacs(bin)%{?_emacs_version: >= %{_emacs_version}}

Caso II

Si el paquete tiene archivos auxiliares para utilizar con GNU Emacs, el paquete debe tener Requires: emacs-filesystem >= %{_emacs_version}

Paquete BuildRequires

Paquete BuildRequires para paquetes adjuntos de GNU Emacs:

  • En general sería suficiente tener BuildRequires: emacs-nw

Compilación manual de byte

Normalmente, la compilación de paquetes Elisp se realiza mediante un archivo make incluido en el paquete, pero en ocasiones puede ser necesario añadir comandos a la sección %build del archivo de especificaciones para compilar archivos. En ese caso, utilice %{_emacs_bytecompile} file.el

Es un requisito que todos los archivos Elisp estén compilados y empaquetados en bytes, a menos que exista una buena razón para no hacerlo, en cuyo caso esto debe documentarse con un comentario en el archivo de especificaciones.

Uso de BuildArch: noarch

Si un paquete adjunto requiere solo compilación de byte de elisp entonces BuildArch: noarch sería utilizado. Esto es altamente improbable para incluso aplicar a Caso II.

Ejemplo específico de plantillas de archivo

Plantilla para un paquete adjunto para GNU Emacs (Caso I)

Esta es una plantilla para un paquete de GNU Emacs. El paquete principal se llama emacs-foo y contiene todos los archivos necesarios para ejecutar el paquete foo con GNU Emacs. Esto incluye los archivos compilados y los archivos origen de elisp.

%global pkg foo
%global pkgname Foo

Nombre:           emacs-%{pkg}
Versión:
Liberación:        %autorelease
Resumen:

Grupo:
Licencia:
URL:
Origen0:

BuildArch:      noarch
BuildRequires:  emacs-nw
Requires:       emacs(bin)%{?_emacs_version: >= %{_emacs_version}}

%description
%{pkgname} es un paquete adjunto para GNU Emacs. Hace cosas maravillosas…


%prep
%autosetup -n %{pkg}-%{version}

%build


%install


%post


%preun


%files
%doc
%{_emacs_sitelispdir}/%{pkg}
%{_emacs_sitestartdir}/*.el


%changelog
%autochangelog

Plantilla para un paquete el cual contenga archivos auxiliares de GNU Emacs (Caso II)

Esto es un esqueleto de un paquete el cual además incluye archivos de mantenimiento para GNU Emacs

Nombre:           foo
Versión:
Lanzamiento:        %autorelease
Sumario:

Grupo:
Licencia:
URL:
Origen0:

BuildRequires:  emacs-nw
Requires:       emacs-filesystem%{?_emacs_version: >= %{_emacs_version}}

%description
Foo es un paquete el cual contiene archivos de soporte Emacs auxiliares.


%prep
%autosetup

%build


%install


%post


%preun


%files
%doc
%{_emacs_sitelispdir}/foo
%{_emacs_sitestartdir}/*.el

%changelog
%autochangelog

Principios detrás de las directrices

Lugar de los archivos instalados

Los archivos del paquete complementario foo deben colocarse en %{_emacs_sitelispdir}/foo lo cual evalúa a /usr/share/emacs/site-lisp/foo.

Usually an add-on package will require a startup file, and this should be called foo-init.el and be placed in %{_emacs_sitestartdir} which evaluates to /usr/share/emacs/site-lisp/site-start.d/.

Packaging of source elisp files

Typically, an Emacs add-on package will be compiled from source elisp files. The resulting compiled elisp files will then be included in the relevant emacs-foo package. It is important to also include the source elisp files for several reasons. For example when debugging a problem with an Emacs package, the Elisp debugger can look up the relevant code or symbol definition in the source lisp file if present. Also, it’s sometimes helpful to jump to a variable description string from the Emacs help system.

BuildArch for Emacs add-on packages

You should set BuildArch: noarch for add-on packages which only compile elisp files during building.

If the package building process also compiles programs in other languages, you may need to not set BuildArch.

Requieren para GNU Emacs

Paquetes adjuntados tendrían apuntes Requieres apropiados para el la versión de Emacs destinados. GNU Emacs está disponible en múltiples paquetes – algunos detalles de estos paquetes a continuación.

  1. El paquete emacs es compilado con asistencia GTK pura para conceder al usuario ejecutar Emacs en un entorno con ventana.

  2. El paquete emacs-gtk+x11 está compilado con asistencia X11 a través del toolkit de GTK para conceder al usuario ejecutar Emacs dentro de un entorno con ventana.

  3. El paquete emacs-lucid es compilado con asistencia X11 a través del toolkit Lucid para conceder al usuario ejecutar Emacs en un entorno con ventana.

  4. El paquete emacs-nw es compilado sin asistencia de IGU. Es apropiado para ejecutar en un terminal.

Nota:

  • Todos los paquetes emacs, emacs-gtk+x11, emacs-lucid, y emacs-nw tienen Requisitos: emacs-common.

  • Todos los paquetes emacs, emacs-gtk+x11, emacs-lucid, y emacs-nw tienen un Provides: emacs(bin) virtual.

Assuming your add-on package will work in both a windowed and a console Emacs session, it is wrong to have Requires: emacs as that would pull in a dependency on GTK even if the console variant of Emacs is installed. Rather you should use Requires: emacs(bin) for GNU Emacs add-on packages.

Si el paquete SOLO funciona con mantenimiento GTK compilado en Emacs, entonces el paquete tendía Requires: emacs. Esto es muy poco común.

Por qué necesitamos Requires con versiones

Muchos paquetes elisp buscan la compatibilidad con versiones anteriores del código fuente comprobando si existen ciertas características en el Emacs en uso durante la ejecución o la compilación. En caso afirmativo, utilizan lo disponible. En caso negativo, proporcionan sus propias versiones de funciones, macros, etc., que faltan. Esto se propaga a *.elc durante la compilación, y se añaden bastantes funciones entre versiones originales de Emacs.

So let’s say I byte-compile a package into *.elc with Emacs 29.3. Elisp package quux checks if the foo-bar function is available in the Emacs being used to byte-compile it. Yes, it is, so the internal backwards compat version of foo-bar included in quux does not end up in the *.elc. Now, let’s assume foo-bar was added in Emacs 29.3 and didn’t exist in 29.2 and we’re trying to run the *.elc with 29.2 → boom, foo-bar is not available. Note: this wouldn’t happen if only *.el were shipped - *.elc are the potential and likely problem. Requiring >= version of the Emacs used to byte-compile the *.elc is not the only solution (nor enough for all corner cases), but is the best one we currently have available.

El paquete principal y los subpaquetes deberán tener la versión Requires correctamente versionada para garantizar que se instale una versión reciente de Emacs. El paquete Lisp compilado por bytes de Emacs suele ser compatible con versiones posteriores de Emacs, pero con frecuencia no es compatible con versiones anteriores.

Determinación de la versión de Emacs Required en tiempo de compilación del paquete

It is recommended to derive greater-than-or-equal-to valued versioned dependencies from the version of Emacs used to byte-compile the package at package build time. The emacs-common package includes /usr/lib/rpm/macros.d/macros.emacs which defines a %{_emacs_version} macro containing the version of Emacs installed.

Otros paquetes conteniendo adjuntos Emacs en adjuntos (Caso II)

Es frecuente que un paquete de software, aunque no sea principalmente un complemento de Emacs, contenga componentes para Emacs. Por ejemplo, el programa Gnuplot contiene archivos elisp para editar archivos de entrada de Gnuplot en GNU Emacs y ejecutar Gnuplot desde GNU Emacs. En este caso, queremos habilitar la compatibilidad con Emacs si Emacs está instalado, pero no queremos obligar a su instalación al instalar este paquete, ya que Emacs no es necesario para proporcionar la funcionalidad principal del paquete. Para ello, se creó el subpaquete emacs-filesystem, que contiene el directorio /usr/share/emacs/site-lisp. Un paquete puede entonces requerir el paquete emacs-filesystem para instalar sus archivos Elisp sin tener que instalar Emacs ni su cadena de dependencias.

Want to help? Learn how to contribute to Fedora Docs ›