From Fedora Project Wiki

(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 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/GAP/. Please update your bookmarks.

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.