(New page; writeup of https://fedorahosted.org/fpc/ticket/625.) |
(Deprecate this page.) |
||
Line 1: | Line 1: | ||
{{OldGuidelinePage|GAP}} | |||
{{DISPLAYTITLE:Fedora Packaging Guidelines for GAP}} | {{DISPLAYTITLE:Fedora Packaging Guidelines for GAP}} | ||
<div style="float: right;" class="toclimit-2">__TOC__</div> | <div style="float: right;" class="toclimit-2">__TOC__</div> |
Latest revision as of 20:04, 21 December 2018
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
🔗 GAPDoc
Add-ons that use GAPDoc to build documentation MUST include BuildRequires: GAPDoc-latex
to pull in the necessary LaTeX packages. These packages do not need Requires: GAPDoc
, since gap-core
depends on GAPDoc.
🔗 Autodoc
Add-ons that use Autodoc to build documentation MUST include BuildRequires: gap-pkg-autodoc
. Such packages do not need to include BuildRequires: GAPDoc-latex
, as the Autodoc package Requires: GAPDoc-latex
.
🔗 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
.
🔗 Testing
Some add-ons have not yet updated their test suites for GAP 4.8. If a GAP add-on's test suite invokes ReadTest(foo)
, modify it to invoke Test(foo, rec( compareFunction := "uptowhitespace" ) )
instead for Fedora 24 and later.