(Initial version of the proposed GAP guidelines) |
(Describe relative directory handling) |
||
| Line 1: | Line 1: | ||
This document describes the conventions and customs surrounding the proper packaging of [http://gap-system.org/ 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'', | This document describes the conventions and customs surrounding the proper packaging of [http://gap-system.org/ 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 == | == 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 have names of the form gap-pkg-foo. For example, the FGA add-on is named gap-pkg-fga. | 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 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 <code>../../../convert.pl</code>. The RPM spec file must account for this, either by altering the add-on to point to paths under <code>%{_gap_dir}</code>, 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 == | == BuildRequires == | ||
| Line 18: | Line 21: | ||
=== GAPDoc === | === GAPDoc === | ||
Add-ons that use GAPDoc to build documentation must include <code>BuildRequires: GAPDoc-latex</code> to pull in the necessary LaTeX packages. These packages do | Add-ons that use GAPDoc to build documentation must include <code>BuildRequires: GAPDoc-latex</code> to pull in the necessary LaTeX packages. These packages do not need <code>Requires: GAPDoc</code>, since <code>gap-core</code> depends on GAPDoc. | ||
=== Autodoc === | === Autodoc === | ||
Add-ons that use Autodoc to build documentation must include <code>BuildRequires: gap-pkg-autodoc</code>. Such packages do not need to include <code>BuildRequires: GAPDoc-latex</code>, as the Autodoc package | Add-ons that use Autodoc to build documentation must include <code>BuildRequires: gap-pkg-autodoc</code>. Such packages do not need to include <code>BuildRequires: GAPDoc-latex</code>, as the Autodoc package <code>Requires: GAPDoc-latex</code>. | ||
== Requires, Recommends, and Suggests == | == Requires, Recommends, and Suggests == | ||
| Line 42: | Line 45: | ||
== Documentation == | == Documentation == | ||
Since GAP documentation must be installed under <code>%{_gap_dir}/pkg</code> for the builtin documentation browser to find it, such documentation should not be duplicated with <code>%doc</code>. However, the documentation should still be marked as such so that documentation-free installs work. Most add-ons should include <code>%docdir</code> declarations in the <code>%files</code> section of the spec file; e.g., <code>%docdir %{_gap_dir}/pkg/%{pkgname}/doc</code> and <code>%docdir %{_gap_dir}/pkg/%{pkgname}/htm</code>. | Since GAP documentation must be installed under <code>%{_gap_dir}/pkg</code> for the builtin documentation browser to find it, such documentation should not be duplicated with <code>%doc</code>. However, the documentation should still be marked as such so that documentation-free installs work as expected. Most add-ons should include <code>%docdir</code> declarations in the <code>%files</code> section of the spec file; e.g., <code>%docdir %{_gap_dir}/pkg/%{pkgname}/doc</code> and <code>%docdir %{_gap_dir}/pkg/%{pkgname}/htm</code>. | ||
== Testing == | == Testing == | ||
Some add-ons have not yet updated their test suites for GAP 4.8. If a GAP add-on's test suite invokes <code>ReadTest(foo)</code>, modify it to invoke <code>Test(foo, rec( compareFunction := "uptowhitespace" ) )</code> instead. | Some add-ons have not yet updated their test suites for GAP 4.8. If a GAP add-on's test suite invokes <code>ReadTest(foo)</code>, modify it to invoke <code>Test(foo, rec( compareFunction := "uptowhitespace" ) )</code> instead for Fedora 24 and later. | ||
Revision as of 15:38, 16 May 2016
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 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.texgapmacrodoc.tex→%{_gap_dir}/doc/gapmacrodoc.texmanualbib.xml→%{_gap_dir}/doc/manualbib.xmlmanualbib.xml.bib→%{_gap_dir}/doc/manualbib.xml.bibmanualindex→%{_gap_dir}/doc/manualindexbuildman.pe→%{_gap_dir}/etc/buildman.peconvert.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 in the binary RPM 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
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.