GAP Packaging Guidelines
This document describes the conventions and customs surrounding the proper packaging of GAP add-on packages in Fedora. Throughout this document, we use the word add-on to substitute for GAP upstream’s use of the word package, to avoid confusion with RPM packages.
Naming
The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-devel, and gap-vim. To distinguish add-on packages from these core packages, add-ons MUST have names of the form gap-pkg-foo. For example, the FGA add-on is named gap-pkg-fga.
Add-on Location
GAP add-ons are written to be installed simply by unpacking them in an
existing GAP directory tree. For most add-ons, the only build action
necessary is building the documentation. However, since the add-on authors
assumed this would happen within the GAP tree, add-ons freely use relative
paths to access GAP files. For example, packages that use TTH to build
documentation (see below) commonly invoke ../../../convert.pl
. The RPM
spec file MUST account for this, either by altering the add-on to point to
paths under %{_gap_dir}
, or by creating symbolic links to create the
appearance that the build is taking place inside the GAP tree. If the add-on
is altered for the build, the spec file SHOULD arrange for the original
(unaltered) files to be installed, so that paths are correct after
installation.
BuildRequires
All add-ons MUST include BuildRequires: gap-devel
, as that package
contains essential tools needed for compiling binary modules and building
documentation, as well as a set of RPM macros for use in spec files. Each
add-on also MUST contain a BuildRequires
that is dependent on the
documentation style used by the GAP add-on.
TTH
Add-ons that use a buildman.pe
or convert.pl
script to build
documentation also need BuildRequires: tth
in order to build HTML
documentation pages from TeX input. Some add-ons bundle these scripts, as
well as a few auxiliary files. Add-ons containing any of the following files
should be modified to link to the version of the file contained in the gap
or gap-devel packages.
-
gapmacro.tex
→%{_gap_dir}/doc/gapmacro.tex
-
gapmacrodoc.tex
→%{_gap_dir}/doc/gapmacrodoc.tex
-
manualbib.xml
→%{_gap_dir}/doc/manualbib.xml
-
manualbib.xml.bib
→%{_gap_dir}/doc/manualbib.xml.bib
-
manualindex
→%{_gap_dir}/doc/manualindex
-
buildman.pe
→%{_gap_dir}/etc/buildman.pe
-
convert.pl
→%{_gap_dir}/etc/convert.pl
Requires, Recommends, and Suggests
All add-ons MUST include Requires: gap-core
. In addition, dependencies
on other GAP packages, as recorded in PackageInfo.g
, MUST be specified,
with the exception of GAPDoc
, as noted above. GAP has a 2-level
dependency system, specified with NeededOtherPackages
and
SuggestedOtherPackages
tags in PackageInfo.g
. How these dependencies
map onto the 3-level RPM dependency system of Requires, Recommends, and
Suggests is left to the discretion of the Fedora packager.
Unnecessary Files
GAP add-ons are intended to be unpacked in place within a GAP directory
tree. Ordinarily, the entire distribution directory is copied into
%{_gap_dir}/pkg
. This includes the documentation directories, which are
consumed by the tools contained in gap-online-help. However, some files are
not needed in the final install directory. Files that should not appear
there include:
-
Textual descriptions of the add-on, such as a README
-
License files (COPYING, COPYRIGHT, LICENSE, etc.)
-
Files for building documentation, often called
make_doc
-
Files generated by LaTeX, including files with these suffixes:
-
.aux
-
.bbl
-
.blg
-
.idx
-
.ilg
-
.ind
-
.log
-
.toc
-
Note that License files MUST still be included in the package with the %license tag, and other documentation such as README files can be included as %doc.
Documentation
Since GAP documentation must be installed under %{_gap_dir}/pkg
for the
builtin documentation browser to find it, such documentation SHOULD NOT be
duplicated with %doc
. However, the documentation SHOULD still be marked
as such so that documentation-free installs work as expected. Most add-ons
SHOULD include %docdir
declarations in the %files
section of the
spec file; e.g., %docdir %{_gap_dir}/pkg/%{pkgname}/doc
and %docdir
%{_gap_dir}/pkg/%{pkgname}/htm
.