From Fedora Project Wiki

No edit summary
(Deprecate this page.)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{OldGuidelinePage|Emacs}}
= Packaging of add-ons for GNU Emacs and XEmacs =
= Packaging of add-ons for GNU Emacs and XEmacs =


Line 12: Line 13:
There are two distinct cases where consideration of these guidelines is required:
There are two distinct cases where consideration of these guidelines is required:


# This case refers to the situation where a package's principal purpose is to provide extra functionality for (X)Emacs, and the package serves no purpose without the presence of (X)Emacs. An example of this case is the VM mail reader, as packaged in emacs-vm.
# This case refers to the situation where a package's principal purpose is to provide extra functionality for (X)Emacs, and the package serves no purpose without the presence of (X)Emacs. An example of this case is the VM mail reader, as packaged in emacs-vm. Below we refer to this as '''Case I'''.
# This case refers to the situation where a package's principal functionality does not require (X)Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in (X)Emacs.
# This case refers to the situation where a package's principal functionality does not require (X)Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in (X)Emacs. Below we refer to this as '''Case II'''.


Each of these cases is handled differently, and below you will find a section outlining the Guidelines for each case.
== Package naming and sub-package organization ==
=== Case I ===
# Where an add-on package foo is for both GNU Emacs and XEmacs, the main package should be called emacs-common-foo. This main package should contain files common to both GNU Emacs and XEmacs such as documentation etc. Files specific to each of GNU Emacs and XEmacs should be placed in sub-packages called emacs-foo and xemacs-foo.
# Where a package is primarily an add-on for one flavour of (X)Emacs, the main package should be called emacs-foo or xemacs-foo.


== Case I: Package only provides functionality for (X)Emacs ==
=== Case II ===
Where a package's principal functionality does not require (X)Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in (X)Emacs, these should be included in the main package which will need to Require the emacs-filesystem and/or xemacs-filesystem packages. More detail below.


=== Package naming and sub-package organization ===
== Package contents  ==
1. Where an add-on package foo is for both GNU Emacs and XEmacs, the main package should be called emacs-common-foo. This main package should contain files common to both GNU Emacs and XEmacs such as documentation etc. Files specific to each of GNU Emacs and XEmacs should be placed in sub-packages as detailed in points 3 and 4 below.
{{admon/tip|Why package the source elisp?|The source elisp files are useful for getting help on variables for the (X)Emacs mode, and also for providing debugging information in the event of an error}}


2. Where a package is specific only to one flavour of (X)Emacs, the main package should be called emacs-foo or xemacs-foo. In both cases, elisp source should be packaged in separate sub-packages as detailed below.
=== Case I ===
# Files specific to GNU Emacs should be placed in a sub-package called 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.
# Files specific to XEmacs should be placed in a sub-package called xemacs-foo. This should contain the elisp source, compiled elisp and any other files needed to use the add-on package or sub-package with XEmacs.


3. Files specific to GNU Emacs should be placed in two sub-packages:
{{admon/warning|Updating older packages to comply with this Case I guideline|Before Fedora 16 the guidelines stated that the (X)Emacs elisp source files were to be split out into separate sub-packages (emacs-foo-el and xemacs-foo-el). If you're updating a package to bring those elisp source files files back into the (x)emacs-foo package, you will need to add appropriate Obsoletes: and Provides: directives to the (x)emacs-foo. For example, if up until version 12.6-1 of package emacs-foo, there was a subpackage called emacs-foo-el, you will now need to add <code>Obsoletes: emacs-foo-el <nowiki><=</nowiki> 12.6-1</code> and <code>Provides: emacs-foo-el <nowiki><=</nowiki> 12.6-1</code> to package emacs-foo for packages 12.6-2 and later.}}
* emacs-foo: this sub-package should contain compiled elisp and other files needed to use the add-on package with GNU Emacs only. It should not contain any source elisp files which are not required to run the package.
* emacs-foo-el: this sub-package contains the source elisp files used to build the add-on package for GNU Emacs. Files in this package should not be required to use the add-on package.


4. Files specific to XEmacs should be placed in two sub-packages:
=== Case II ===
* xemacs-foo: this sub-package should contain compiled elisp and other files needed to use the add-on package with XEmacs only. It should not contain any source elisp files which are not required to run the package.
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.
* xemacs-foo-el: this sub-package contains the source elisp files used to build the add-on package for XEmacs. Files in this package should not be required to use the add-on package.


=== File locations ===
{{admon/warning|Updating older packages to comply with this Case II guideline|Before Fedora 16 the guidelines stated that the (X)Emacs files were to be split out into separate sub-packages. If you're updating a package and bringing those (X)Emacs files back into the main package, you will need to add appropriate Obsoletes: and Provides: directives to the main package. For example, if up until version 12.6-1 of package foo, there was a subpackage called emacs-foo, you will now need to add <code>Obsoletes: emacs-foo <nowiki><=</nowiki> 12.6-1</code> and <code>Provides: emacs-foo <nowiki><=</nowiki> 12.6-1</code> to package foo for packages 12.6-2 and later.}}
1. File locations for GNU Emacs add-on 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}.


2. File locations for XEmacs add-on packages:
== File locations ==
* All elisp files for package should be installed in the directory %{_xemacs_sitelispdir}/foo (%{_xemacs_sitelispdir} translates to /usr/share/xemacs/site-packages/lisp/)
# File locations for GNU Emacs add-on (sub-)packages:
* All other files for the add-on package should be installed under the relevant sub-directories  in %{_xemacs_sitepkgdir} eg. %{_xemacs_sitepkgdir}/etc/foo (%{_xemacs_sitepkgdir} translates to /usr/share/xemacs/site-packages).
#* All elisp and related files for the package should be installed in the directory <code>%{_emacs_sitelispdir}/foo</code>.
* If the package requires a startup file this should be called foo-init.el and be placed in %{_xemacs_sitestartdir}.
#* If the package requires a startup file this should be called foo-init.el and be placed in <code>%{_emacs_sitestartdir}</code>.
# File locations for XEmacs add-on (sub-)packages:
#* All elisp files for package should be installed in the directory <code>%{_xemacs_sitelispdir}/foo</code> (<code>%{_xemacs_sitelispdir}</code> translates to <code>/usr/share/xemacs/site-packages/lisp/</code>)
#* All other files for the add-on package should be installed under the relevant sub-directories  in <code>%{_xemacs_sitepkgdir}</code> eg. <code>%{_xemacs_sitepkgdir}/etc/foo</code> (<code>%{_xemacs_sitepkgdir}</code> translates to <code>/usr/share/xemacs/site-packages</code>).
#* If the package requires a startup file this should be called <code>foo-init.el</code> and be placed in <code>%{_xemacs_sitestartdir}</code>.


=== Directory ownership ===
== Package Requires ==
1. Directory ownerships for GNU Emacs add-on packages:
=== Case I ===
* %{_emacs_sitelispdir}/foo should be owned by the package emacs-foo.
# Package Requires for GNU Emacs add-on (sub-)packages
#* Where relevant emacs-foo must have <code>Requires: emacs-common-foo = %{version}-%{release}</code>
#* emacs-foo must have <code>Requires: emacs(bin) >= %{_emacs_version}</code>
# Package Requires for XEmacs add-on (sub-)packages
#* Where relevant xemacs-foo must have <code>Requires: emacs-common-foo = %{version}-%{release}</code>
#* xemacs-foo must have <code>Requires: xemacs(bin) >= %{_xemacs_version}</code>


2. Directory ownerships for XEmacs add-on packages:
=== Case II ===
* %{_xemacs_sitelispdir}/foo should be owned by xemacs-foo.
# If the package has auxillary files for use with GNU Emacs, the package must have <code>Requires: emacs-filesystem >= %{_emacs_version}</code>
* Any %{_xemacs_sitepkgdir}/*/foo directories should be owned by xemacs-foo.
# If the package has auxillary files for use with XEmacs, the package must have <code>Requires: xemacs-filesystem >= %{_xemacs_version}</code>


=== Package Requires ===
== Package BuildRequires ==
1. Package Requires for GNU Emacs add-on packages
# Package BuildRequires for GNU Emacs add-on packages:
* emacs-foo-el must have Requires: emacs-foo = %{version}-%{release}.
#* In general it should suffice to have <code>BuildRequires: emacs</code>
* Where relevant emacs-foo must have Requires: emacs-common-foo = %{version}-%{release}
# Package BuildRequires for XEmacs add-on packages:
* emacs-foo must have Requires: emacs(bin) >= %{_emacs_version}
#* In general it should suffice to have <code>BuildRequires: xemacs</code>
#* It may be necessary to also add <code>BuildRequires: xemacs-devel</code> in rare circumstances


2. Package Requires for XEmacs add-on packages
== Manual byte compilation ==
* xemacs-foo-el must have Requires: xemacs-foo = %{version}-%{release}.
* Where relevant xemacs-foo must have Requires: emacs-common-foo = %{version}-%{release}
* xemacs-foo must have Requires: xemacs(bin) >= %{_xemacs_version}
 
=== Package BuildRequires ===
1. Package BuildRequires for GNU Emacs add-on packages:
* In general it should suffice to have BuildRequires: emacs
 
2. Package BuildRequires for XEmacs add-on packages:
* In general it should suffice to have BuildRequires: xemacs
* It may be necessary to also add BuildRequires: xemacs-devel in rare circumstances
 
=== Manual byte compilation ===
Usually package Elisp compilation is handled via a make file shipped with the package, but on some occasions it may be necessary to add commands to the %build section of the spec file to byte compile files. The following macros are provided to help with this:
Usually package Elisp compilation is handled via a make file shipped with the package, but on some occasions it may be necessary to add commands to the %build section of the spec file to byte compile files. The following macros are provided to help with this:


* For GNU Emacs byte compilation, use %{_emacs_bytecompile} file.el
* For GNU Emacs byte compilation, use <code>%{_emacs_bytecompile} file.el</code>
* For XEmacs byte compilation, use %{_xemacs_bytecompile} file.el
* For XEmacs byte compilation, use <code>%{_xemacs_bytecompile} file.el</code>


It is a requirement that all Elisp files are byte compiled and packaged, unless there is a good reason not to, in which case this should be documented with a comment in the spec file.  If you are packaging for both GNU Emacs and XEmacs, be sure to byte compile for both.
It is a requirement that all Elisp files are byte compiled and packaged, unless there is a good reason not to, in which case this should be documented with a comment in the spec file.  If you are packaging for both GNU Emacs and XEmacs, be sure to byte compile for both.


=== Use of BuildArch: noarch ===
== Use of BuildArch: noarch ==
If an add-on package requires only byte compilation of elisp then BuildArch: noarch should be used.
If an add-on package requires only byte compilation of elisp then <code>BuildArch: noarch</code> should be used. This is highly unlikely to ever apply to Case II.
 
== Case II: Package also provides auxiliary (X)Emacs files ==
 
=== Package naming and sub-package organization ===
For Case II the compiled Elisp and Elisp source reside in the main package i.e. it is not necessary to create sub-packages for the Elisp files. The package should contain both the byte compiled Elisp and the Elisp source files.
 
=== File locations ===
1. Location of files relating to GNU Emacs:
* 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}.
 
2. Location of files relating to XEmacs:
* All elisp files for package should be installed in the directory %{_xemacs_sitelispdir}/foo (%{_xemacs_sitelispdir} translates to /usr/share/xemacs/site-packages/lisp/)
* All other files for the add-on package should be installed under the relevant sub-directories  in %{_xemacs_sitepkgdir} eg. %{_xemacs_sitepkgdir}/etc/foo (%{_xemacs_sitepkgdir} translates to /usr/share/xemacs/site-packages).
* If the package requires a startup file this should be called foo-init.el and be placed in %{_xemacs_sitestartdir}.
 
=== Directory ownership ===
1. If the package installs files in %{_emacs_sitelispdir}/foo, then it should own that directory
 
2. If the package installs files in %{_xemacs_sitelispdir}/foo, then it should own that directory
 
=== Package Requires ===
1. If the package provides files for use with GNU Emacs, it must:
* have Requires: emacs-filesystem >= %{_emacs_version}
* NOT have Requires: emacs(bin) >= %{_emacs_version}
 
2. If the package provides files for use with XEmacs, it must:
* have Requires: xemacs-filesystem >= %{_xemacs_version}
* NOT have Requires: xemacs(bin) >= %{_xemacs_version}
 
=== Package BuildRequires ===
1. Package BuildRequires for GNU Emacs add-on packages:
* In general it should suffice to have BuildRequires: emacs
 
2. Package BuildRequires for XEmacs add-on packages:
* In general it should suffice to have BuildRequires: xemacs
* It may be necessary to also add BuildRequires: xemacs-devel in rare circumstances
 
=== Manual byte compilation ===
Elisp files (other than the startup file) must be byte compiled during the %build section of the spec file.
 
Often, package Elisp compilation is handled via a make file shipped with the package, but on some occasions it may be necessary to add commands to the %build section of the spec file to byte compile files. The following macros are provided to help with this:
 
# For GNU Emacs byte compilation, use %{_emacs_bytecompile} file.el
# For XEmacs byte compilation, use %{_xemacs_bytecompile} file.el
 
It is a requirement that all packaged Elisp files are byte compiled, unless there is a good reason not to, in which case this should be documented with a comment in the spec file.  If you are packaging for both GNU Emacs and XEmacs, be sure to byte compile for both.
 
=== Use of BuildArch: noarch ===
If an add-on package requires only byte compilation of elisp then BuildArch: noarch should be used.
 
== Spec file templates for (X)Emacs Case I add-on packages ==
 
=== Template for a package for both GNU Emacs and XEmacs ===
This spec-file template for the add-on package "foo" creates 5 packages:
 
1. emacs-common-foo is the main package. This should contain files which are common to both the emacs-foo and xemacs-foo subpackages below. Examples of what this file would contain are the package documentation, the COPYING file, the CHANGELOG file etc.


2. emacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package owns the director /usr/share/emacs/site-lisp/foo.
== Example spec file templates ==
=== Template for a package for both GNU Emacs and XEmacs (Case I) ===
This spec-file template for the add-on package "foo" creates 3 packages:


3. emacs-foo-el. This sub-package contains the elisp source files corresponding to the compiled elisp files in package emacs-foo. This sub-package Requires: emacs-foo, as the directory in which the elisp source files are installed to is owned by emacs-foo.
# emacs-common-foo is the main package. This should contain files which are common to both the emacs-foo and xemacs-foo subpackages below. Examples of what this file would contain are the package documentation, the COPYING file, the CHANGELOG file etc.
 
# emacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package contains both the compiled and source elisp files.
4. xemacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package owns the director /usr/share/emacs/site-packages/lisp/foo.
# xemacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package contains both the compiled and source elisp files.
 
5. xemacs-foo-el. This sub-package contains the elisp source files corresponding to the compiled elisp files in package xemacs-foo. This sub-package Requires: xemacs-foo, as the directory in which the elisp source files are installed to is owned by xemacs-foo.
 
For the Requires mentioned in 1-5 above, the exact %{version}-%{release} should be matched.


For convenience, there are two macros at the top of the file which you should customise to your package. You do not have to use the macros placed at the top of the file, but they help readability and make writing a spec file for a new package much quicker.
For convenience, there are two macros at the top of the file which you should customise to your package. You do not have to use the macros placed at the top of the file, but they help readability and make writing a spec file for a new package much quicker.
Line 183: Line 122:
This package contains the byte compiled elisp packages to run %{pkgname} with GNU
This package contains the byte compiled elisp packages to run %{pkgname} with GNU
Emacs.
Emacs.
%package -n emacs-%{pkg}-el
Summary: Elisp source files for %{pkgname} under GNU Emacs
Group:
Requires: emacs-%{pkg} = %{version}-%{release}
%description -n emacs-%{pkg}-el
This package contains the elisp source files for %{pkgname} under GNU Emacs. You
do not need to install this package to run %{pkgname}. Install the emacs-%{pkg}
package to use %{pkgname} with GNU Emacs.




Line 205: Line 133:
This package contains the byte compiled elisp packages to use %{pkgname} with
This package contains the byte compiled elisp packages to use %{pkgname} with
XEmacs.
XEmacs.
%package -n xemacs-%{pkg}-el
Summary: Elisp source files for %{pkgname} under XEmacs
Group:
Requires: xemacs-%{pkg} = %{version}-%{release}
%description -n xemacs-%{pkg}-el
This package contains the elisp source files for %{pkgname} under XEmacs. You do
not need to install this package to run %{pkgname}. Install the xemacs-%{pkg}
package to use %{pkgname} with XEmacs.




Line 238: Line 155:


%files -n emacs-%{pkg}
%files -n emacs-%{pkg}
%{_emacs_sitelispdir}/%{pkg}/*.elc
%{_emacs_sitelispdir}/%{pkg}
%{_emacs_sitestartdir/*.el
%{_emacs_sitestartdir/*.el
%dir %{_emacs_sitelispdir}/%{pkg}
%files -n emacs-%{pkg}-el
%{_emacs_sitelispdir}/%{pkg}/*.el




%files -n xemacs-%{pkg}
%files -n xemacs-%{pkg}
%{_xemacs_sitelispdir}/%{pkg}/*.elc
%{_xemacs_sitelispdir}/%{pkg}
%{_xemacs_sitestartdir}/*.el
%{_xemacs_sitestartdir}/*.el
%dir %{_xemacs_sitelispdir}/%{pkg}


%files -n xemacs-%{pkg}-el
%{_xemacs_sitelispdir}/%{pkg}/*.el




Line 260: Line 168:
</pre>
</pre>


=== Template for a add-on package for GNU Emacs only ===
=== Template for a add-on package for GNU Emacs only (Case I) ===
This is a template for a package for GNU Emacs only. The main package is called emacs-foo and contains all files needed to run package foo with GNU Emacs. There is a subpackage called emacs-foo-el which installs the elisp source files. emacs-foo owns the directory into which it is installed (/usr/share/emacs/site-lisp/foo), and so emacs-foo-el Requires emacs-foo with the matching version and release tag.
This is a template for a package for GNU Emacs only. The main package is called emacs-foo and contains all files needed to run package foo with GNU Emacs. This includes both compiled and source elisp files.


<pre>
<pre>
Line 284: Line 192:
%{pkgname} is an add-on package for GNU Emacs. It does wonderful things...
%{pkgname} is an add-on package for GNU Emacs. It does wonderful things...


%package -n %{name}-el
 
Summary:        Elisp source files for %{pkgname} under GNU Emacs
%prep
%setup -q -n %{pkg}-%{version}
 
%build
 
 
%install
 
 
%post
 
 
%preun
 
 
%files
%doc
%{_emacs_sitelispdir}/%{pkg}
%{_emacs_sitestartdir}/*.el
 
 
%changelog
</pre>
 
=== Template for a package which contains auxilliary GNU Emacs and XEmacs files (Case II) ===
This is a skeleton of a package which also includes support files for both GNU Emacs and XEmacs
<pre>
Name:          foo
Version:
Release:        1%{?dist}
Summary:
 
Group:
Group:
Requires:      %{name} = %{version}-%{release}
License:
URL:
Source0:
 
BuildRequires:  emacs
Requires:      emacs-filesystem >= %{_emacs_version}
 
BuildRequires:  xemacs
Requires:      xemacs-filesystem >= %{_xemacs_version}
 
 
%description
Foo is a package wghich contains auxilliary Emacs and XEmacs support files


%description -n %{name}-el
This package contains the elisp source files for %{pkgname} under GNU Emacs. You
do not need to install this package to run %{pkgname}. Install the %{name}
package to use %{pkgname} with GNU Emacs.


%prep
%prep
%setup -q -n %{pkg}-%{version}
%setup -q  


%build
%build
Line 311: Line 258:
%files
%files
%doc
%doc
%{_emacs_sitelispdir}/%{pkg}/*.elc
%{_emacs_sitelispdir}/foo
%{_emacs_sitestartdir}/*.el
%{_emacs_sitestartdir}/*.el
%dir %{_emacs_sitelispdir}/%{pkg}


%files -n %{name}-el
%{_xemacs_sitelispdir}/foo
%{_emacs_sitelispdir}/%{pkg}/*.el
%{_xemacs_sitestartdir}/*.el


%changelog
%changelog
Line 352: Line 298:


=== Packaging of source elisp files ===
=== 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 and xemacs-foo packages. However, these packages SHOULD NOT contain uncompiled elisp source files which are not required for the program to run. Rather, following the precedent set by GNU Emacs packaging, the elisp source files should be placed in their own sub-packages, named emacs-foo-el and xemacs-foo-el.
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 and xemacs-foo packages. It is important to also include the source elisp files for several reasons. For example when debugging a problem with an (X)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.
 
The (x)emacs-foo-el packages are similar in many ways to the -devel subpackages for system libraries. It is often the case that byte compiling the elisp source for one add-on will require the presence of the elisp source for another add-on package at build time for example.
 
Note however, that having the Elisp source files available may be very useful to the user. For example when debugging a problem with an (X)Emacs package, the Elisp debugger can look up the relevant code or symbol definition in the source lisp file if present.
 
Presently, for Case II, we do not consider it necessary to split off the Elisp source files into their own sub-package. While this is inconsistent with Case I, the disk space cost is minimal. In the future we may no longer require splitting out the source Elisp files in Case I.


=== BuildArch for (X)Emacs add-on packages ===
=== BuildArch for (X)Emacs add-on packages ===
Line 397: Line 337:
=== Other packages containing Emacsen add-ons (Case II) ===
=== Other packages containing Emacsen add-ons (Case II) ===
It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for (X)Emacs. For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs. In this case, we want to enable the (X)Emacs support IF (X)Emacs is installed, but we don't want to mandate the installation of (X)Emacs on installation of this package since (X)Emacs is not required for providing the core functionality of the package. To enable this, the emacs-filesystem and xemacs-filesystem sub-packages were created which own the /usr/share/emacs/site-lisp and /usr/share/xmeacs/site-packages directories respectively. A package can then Require these (x)emacsfilesystem packages in order to install their Elisp files without pulling in (X)Emacs and their dependency chain.
It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for (X)Emacs. For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs. In this case, we want to enable the (X)Emacs support IF (X)Emacs is installed, but we don't want to mandate the installation of (X)Emacs on installation of this package since (X)Emacs is not required for providing the core functionality of the package. To enable this, the emacs-filesystem and xemacs-filesystem sub-packages were created which own the /usr/share/emacs/site-lisp and /usr/share/xmeacs/site-packages directories respectively. A package can then Require these (x)emacsfilesystem packages in order to install their Elisp files without pulling in (X)Emacs and their dependency chain.
[[Category:Packaging guidelines]]

Latest revision as of 20:00, 21 December 2018

This is an old copy of a packaging guideline, preserved here in the wiki while we complete the transition to the Fedora documentation system. The current version is located at https://docs.fedoraproject.org/en-US/packaging-guidelines/Emacs/. Please update your bookmarks.

Packaging of add-ons for GNU Emacs and XEmacs

Purpose

The purpose of this document is to promote good practice in packaging add-ons for GNU Emacs and XEmacs, and to encourage the submission of more Emacs add-on packages to the package collection by providing easy to use spec file templates.

This document refers to packaging for Fedora 12 onwards. If you are packaging for an older release of Fedora, please see: Packaging:Emacs_Old

Important notes on these Guidelines

The guidelines in the following sections make extensive use of the macros defined in /etc/rpm/macros.emacs and /etc/rpm/macros.xemacs which are installed with the emacs-common and xemacs-common packages.

There are two distinct cases where consideration of these guidelines is required:

  1. This case refers to the situation where a package's principal purpose is to provide extra functionality for (X)Emacs, and the package serves no purpose without the presence of (X)Emacs. An example of this case is the VM mail reader, as packaged in emacs-vm. Below we refer to this as Case I.
  2. This case refers to the situation where a package's principal functionality does not require (X)Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in (X)Emacs. Below we refer to this as Case II.

Package naming and sub-package organization

Case I

  1. Where an add-on package foo is for both GNU Emacs and XEmacs, the main package should be called emacs-common-foo. This main package should contain files common to both GNU Emacs and XEmacs such as documentation etc. Files specific to each of GNU Emacs and XEmacs should be placed in sub-packages called emacs-foo and xemacs-foo.
  2. Where a package is primarily an add-on for one flavour of (X)Emacs, the main package should be called emacs-foo or xemacs-foo.

Case II

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

Package contents

Why package the source elisp?
The source elisp files are useful for getting help on variables for the (X)Emacs mode, and also for providing debugging information in the event of an error

Case I

  1. Files specific to GNU Emacs should be placed in a sub-package called 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.
  2. Files specific to XEmacs should be placed in a sub-package called xemacs-foo. This should contain the elisp source, compiled elisp and any other files needed to use the add-on package or sub-package with XEmacs.
Updating older packages to comply with this Case I guideline
Before Fedora 16 the guidelines stated that the (X)Emacs elisp source files were to be split out into separate sub-packages (emacs-foo-el and xemacs-foo-el). If you're updating a package to bring those elisp source files files back into the (x)emacs-foo package, you will need to add appropriate Obsoletes: and Provides: directives to the (x)emacs-foo. For example, if up until version 12.6-1 of package emacs-foo, there was a subpackage called emacs-foo-el, you will now need to add Obsoletes: emacs-foo-el <= 12.6-1 and Provides: emacs-foo-el <= 12.6-1 to package emacs-foo for packages 12.6-2 and later.

Case 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.

Updating older packages to comply with this Case II guideline
Before Fedora 16 the guidelines stated that the (X)Emacs files were to be split out into separate sub-packages. If you're updating a package and bringing those (X)Emacs files back into the main package, you will need to add appropriate Obsoletes: and Provides: directives to the main package. For example, if up until version 12.6-1 of package foo, there was a subpackage called emacs-foo, you will now need to add Obsoletes: emacs-foo <= 12.6-1 and Provides: emacs-foo <= 12.6-1 to package foo for packages 12.6-2 and later.

File locations

  1. 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}.
  2. File locations for XEmacs add-on (sub-)packages:
    • All elisp files for package should be installed in the directory %{_xemacs_sitelispdir}/foo (%{_xemacs_sitelispdir} translates to /usr/share/xemacs/site-packages/lisp/)
    • All other files for the add-on package should be installed under the relevant sub-directories in %{_xemacs_sitepkgdir} eg. %{_xemacs_sitepkgdir}/etc/foo (%{_xemacs_sitepkgdir} translates to /usr/share/xemacs/site-packages).
    • If the package requires a startup file this should be called foo-init.el and be placed in %{_xemacs_sitestartdir}.

Package Requires

Case I

  1. Package Requires for GNU Emacs add-on (sub-)packages
    • Where relevant emacs-foo must have Requires: emacs-common-foo = %{version}-%{release}
    • emacs-foo must have Requires: emacs(bin) >= %{_emacs_version}
  2. Package Requires for XEmacs add-on (sub-)packages
    • Where relevant xemacs-foo must have Requires: emacs-common-foo = %{version}-%{release}
    • xemacs-foo must have Requires: xemacs(bin) >= %{_xemacs_version}

Case II

  1. If the package has auxillary files for use with GNU Emacs, the package must have Requires: emacs-filesystem >= %{_emacs_version}
  2. If the package has auxillary files for use with XEmacs, the package must have Requires: xemacs-filesystem >= %{_xemacs_version}

Package BuildRequires

  1. Package BuildRequires for GNU Emacs add-on packages:
    • In general it should suffice to have BuildRequires: emacs
  2. Package BuildRequires for XEmacs add-on packages:
    • In general it should suffice to have BuildRequires: xemacs
    • It may be necessary to also add BuildRequires: xemacs-devel in rare circumstances

Manual byte compilation

Usually package Elisp compilation is handled via a make file shipped with the package, but on some occasions it may be necessary to add commands to the %build section of the spec file to byte compile files. The following macros are provided to help with this:

  • For GNU Emacs byte compilation, use %{_emacs_bytecompile} file.el
  • For XEmacs byte compilation, use %{_xemacs_bytecompile} file.el

It is a requirement that all Elisp files are byte compiled and packaged, unless there is a good reason not to, in which case this should be documented with a comment in the spec file. If you are packaging for both GNU Emacs and XEmacs, be sure to byte compile for both.

Use of BuildArch: noarch

If an add-on package requires only byte compilation of elisp then BuildArch: noarch should be used. This is highly unlikely to ever apply to Case II.

Example spec file templates

Template for a package for both GNU Emacs and XEmacs (Case I)

This spec-file template for the add-on package "foo" creates 3 packages:

  1. emacs-common-foo is the main package. This should contain files which are common to both the emacs-foo and xemacs-foo subpackages below. Examples of what this file would contain are the package documentation, the COPYING file, the CHANGELOG file etc.
  2. emacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package contains both the compiled and source elisp files.
  3. xemacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package contains both the compiled and source elisp files.

For convenience, there are two macros at the top of the file which you should customise to your package. You do not have to use the macros placed at the top of the file, but they help readability and make writing a spec file for a new package much quicker.

%global pkg foo
%global pkgname Foo

Name:           emacs-common-%{pkg}
Version:
Release:        1%{?dist}
Summary:

Group:
License:
URL:
Source0:

BuildArch:	noarch
BuildRequires:  emacs
BuildRequires:  xemacs
Requires:

%description
%{pkgname} is an add-on package for GNU Emacs and XEmacs. It does wonderful things...

This package contains the files common to both the GNU Emacs and XEmacs %{pkgname}
packages.

%package -n emacs-%{pkg}
Summary:	Compiled elisp files to run %{pkgname} under GNU Emacs
Group:
Requires:	emacs(bin) >= %{_emacs_version}
Requires:       emacs-common-%{pkg} = %{version}-%{release}

%description -n emacs-%{pkg}
This package contains the byte compiled elisp packages to run %{pkgname} with GNU
Emacs.


%package -n xemacs-%{pkg}
Summary:	Compiled elisp files to run %{pkgname} under XEmacs
Group:
Requires:	xemacs(bin) >= %{_xemacs_version}
Requires:       emacs-common-%{pkg} = %{version}-%{release}

%description -n xemacs-%{pkg}
This package contains the byte compiled elisp packages to use %{pkgname} with
XEmacs.


%prep
%setup -q -n %{pkg}-%{version}

%build


%install


%post


%preun


%files
%doc


%files -n emacs-%{pkg}
%{_emacs_sitelispdir}/%{pkg}
%{_emacs_sitestartdir/*.el


%files -n xemacs-%{pkg}
%{_xemacs_sitelispdir}/%{pkg}
%{_xemacs_sitestartdir}/*.el



%changelog

Template for a add-on package for GNU Emacs only (Case I)

This is a template for a package for GNU Emacs only. The main package is called emacs-foo and contains all files needed to run package foo with GNU Emacs. This includes both compiled and source elisp files.

%global pkg foo
%global pkgname Foo

Name:           emacs-%{pkg}
Version:
Release:        1%{?dist}
Summary:

Group:
License:
URL:
Source0:

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

%description
%{pkgname} is an add-on package for GNU Emacs. It does wonderful things...


%prep
%setup -q -n %{pkg}-%{version}

%build


%install


%post


%preun


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


%changelog

Template for a package which contains auxilliary GNU Emacs and XEmacs files (Case II)

This is a skeleton of a package which also includes support files for both GNU Emacs and XEmacs

Name:           foo
Version:
Release:        1%{?dist}
Summary:

Group:
License:
URL:
Source0:

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

BuildRequires:  xemacs
Requires:       xemacs-filesystem >= %{_xemacs_version}


%description
Foo is a package wghich contains auxilliary Emacs and XEmacs support files


%prep
%setup -q 

%build


%install


%post


%preun


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

%{_xemacs_sitelispdir}/foo
%{_xemacs_sitestartdir}/*.el

%changelog

Principles behind the guidelines

The existence of the GNU Emacs and XEmacs variants makes packaging Emacs add-on packaging slightly complex. GNU Emacs and XEmacs have different philosophies regarding add-on packages.

XEmacs has its own packaging system and maintains and distributes its own library of third party add-on modules. These are distributed in Fedora in the xemacs-packages-base and xemacs-packages-extra packages. GNU Emacs doesn't have any equivalent system, and third party add-ons are left for the user or distribution to install.

The packaging naming guidelines state that:

Packages of emacs add-on components (code that adds additional functionality to emacs compatible editors) have their own naming scheme. It is often the case that a component will add functionality to several different compatible editors, such as GNU Emacs and XEmacs (and possibly development versions of these editors). The package name should take into account the upstream name of the emacs component.

Where a component adds functionality to more than one emacs compatible editor, the package name should be of the form emacs-common-$NAME. In this case, the main package should contain only files common to all emacs compatible editors, and the code specific to each should be placed in a subpackage reflecting the specific editor $EDITOR-$NAME eg. xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An example of this scheme can be found in the package emacs-common-muse.

Where a component is designed to add functionality to only a single emacs compatible editor, the main package name should reflect this by being called $EDITOR-$NAME. An example of this situation can be found in the package emacs-auctex, which is built only for GNU Emacs.

Wherever possible, we encourage making an add-on package available for both GNU Emacs and XEmacs. One common case where that is not desireable is when an add-on package is already available for XEmacs in either xemacs-packages-base or xemacs-packages-extra. For example VM (a mail reader for Emacs) is provided for XEmacs in the xemacs-packages-extra package, but is not included in the emacs or emacs-common packages. Therefore it is sensible to create a package called emacs-vm which is the VM package for GNU Emacs only. Another such example is AUCTeX.

Location of installed files

GNU Emacs

For GNU Emacs, files for add-on package foo should be placed in %{_emacs_sitelispdir}/foo which evaluates to /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/.

XEmacs

XEmacs expects add-on packages to be installed under %{_xemacs_sitepkgdir} which evaluates to /usr/share/xemacs/site-packages.

Lisp files for add-on package foo should be placed in %{_xemacs_sitelispdir}/foo which evaluates to %{_xemacs_sitepkgdir}/lisp/foo.

Other files for the add-on which are not elisp files should be placed in package specific sub-directories under %{_xemacs_sitepkgdir} eg. %{_xemacs_sitepkgdir}/etc/foo.

Usually an add-on package will require a startup file, and this should be called foo-init.el and be placed in %{_xemacs_sitestartdir} which evaluates to /usr/share/xemacs/site-packages/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 and xemacs-foo packages. It is important to also include the source elisp files for several reasons. For example when debugging a problem with an (X)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 (X)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.

Requires for GNU Emacs and XEmacs

Add-on packages should have appropriate Requires entries for the flavour of (X)Emacs they are targeted at. Both GNU Emacs and XEmacs are available in two different packages - some details of these packages follow.

1. GNU Emacs is packaged as two variants. The emacs package is built with Xorg support to allow the user to run Emacs in a windowed environment. The emacs-nox package is built without Xorg support and hence allows Emacs to be run only in a console. Note:

  • Both the emacs and emacs-nox packages have Requires: emacs-common.
  • Both emacs and emacs-nox have a virtual Provides: emacs(bin)

2. XEmacs is packaged as two variants. The xemacs package is built with Xorg support to allow the user to run Emacs in a windowed environment. The xemacs-nox package is built without Xorg support and hence allows Emacs to be run only in a console. Note:

  • Both the xemacs and xemacs-nox packages have Requires: xemacs-common.
  • Both xemacs and xemacs-nox have a virtual Provides: xemacs(bin)

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

If the package ONLY works with Xorg support built into (X)Emacs, then the packages should have Requires: emacs or Requires: xemacs. This is very uncommon.

Why we need versioned Requires

Many elisp packages aim for backwards source level compatibility by checking whether some features exist in the (X)Emacs in use when the package is being run or byte-compiled. If yes, they use what's available. If no, they provide their own versions of missing functions, macros etc. This propagates into *.elc during byte compilation, and quite a few functions do get added between upstream (X)Emacs releases.

So let's say I byte-compile a package into *.elc with XEmacs 21.5.28. Elisp package quux checks if the foo-bar function is available in the XEmacs 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 XEmacs 21.5.28 and didn't exist in 21.5.27 and we're trying to run the *.elc with 21.5.27 -> 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 (X)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.

The main package and subpackages will need to have appropriately version Requires to ensure that a recent enough version of (X)Emacs is installed. (X)Emacs byte compiled lisp is usually forward compatible with later (X)Emacs versions, but is frequently not compatible with earlier versions of (X)Emacs.

Determining the Required (X)Emacs version at package build time

It is recommended to derive greater-than-or-equal-to valued versioned dependencies from the version of (X)Emacs used to byte-compile the package at package build time. The emacs-common and xemacs-common packages both place files in /etc/rpm which define macros containing the version of (X)Emacs installed. The relevant macros are:

%{_emacs_version}
%{_xemacs_version}

Other packages containing Emacsen add-ons (Case II)

It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for (X)Emacs. For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs. In this case, we want to enable the (X)Emacs support IF (X)Emacs is installed, but we don't want to mandate the installation of (X)Emacs on installation of this package since (X)Emacs is not required for providing the core functionality of the package. To enable this, the emacs-filesystem and xemacs-filesystem sub-packages were created which own the /usr/share/emacs/site-lisp and /usr/share/xmeacs/site-packages directories respectively. A package can then Require these (x)emacsfilesystem packages in order to install their Elisp files without pulling in (X)Emacs and their dependency chain.