From 8d9f98c9aa490e0572048f532b4f951142917139 Mon Sep 17 00:00:00 2001 From: Jerry James Date: Feb 14 2023 22:20:26 +0000 Subject: Update GAP packaging guidelines - Instead of the entire GAP distribution being installed in /usr/lib/gap (%{_gap_dir}), it is now split between a noarch part in %{_datadir}/gap (%{gap_libdir}) and an architecture-specific part in %{_libdir}/gap (%{gap_archdir}). - Remove bad advice about having multiple ExclusiveArch tags in a single spec file. - Various minor clarifications and presentation improvements. --- diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index a135953..7d48af4 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -1,6 +1,6 @@ = GAP Packaging Guidelines -This document describes the conventions and customs surrounding the proper packaging of https://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. +This document describes the conventions and customs surrounding the proper packaging of https://www.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 @@ -8,7 +8,9 @@ The main GAP package and its attendant libraries and help system are in packages == 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. +Architecture-independent (noarch) packages MUST be installed in `+%{gap_libdir}/pkg/%{pkgname}+`, and architecture-specific packages in `+%{gap_archdir}/pkg/%{pkgname}+`, where `+%{pkgname}+` expands to the GAP name for the add-on. + +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_libdir}+`, 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. GAP add-ons are frequently distributed in tarballs with a top-level directory of the form `addon-version`. The add-on SHOULD be installed without the version number. @@ -25,13 +27,13 @@ All add-ons MUST include `+BuildRequires: gap-devel+`, as that package contains 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+` +* `+gapmacro.tex+` → `+%{gap_libdir}/doc/gapmacro.tex+` +* `+gapmacrodoc.tex+` → `+%{gap_libdir}/doc/gapmacrodoc.tex+` +* `+manualbib.xml+` → `+%{gap_libdir}/doc/manualbib.xml+` +* `+manualbib.xml.bib+` → `+%{gap_libdir}/doc/manualbib.xml.bib+` +* `+manualindex+` → `+%{gap_libdir}/doc/manualindex+` +* `+buildman.pe+` → `+%{gap_libdir}/etc/buildman.pe+` +* `+convert.pl+` → `+%{gap_libdir}/etc/convert.pl+` === GAPDoc @@ -50,12 +52,12 @@ How these dependencies map onto the 3-level RPM dependency system of Requires, R == 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: +GAP add-ons are intended to be unpacked in place within a GAP directory tree. Ordinarily, the entire distribution directory is copied into `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/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: +* Files generated by LaTeX and associated tools, including files with these suffixes: ** .aux ** .bbl ** .blg @@ -70,33 +72,32 @@ Note that License files MUST still be included in the package with the %license The `+%gap_copy_docs+` macro is intended to make installation of documentation files easier. For most packages, ensure that the `doc` subdirectory exists in the buildroot, then invoke the macro without arguments in `+%install+`. For special cases, two optional arguments can be given: + * `+-d directory+`: for cases where the documentation directory is not named `doc`, or there are multiple documentation directories * `+-n package+`: the installed add-on directory name is assumed to be available from a macro `+%pkgname+`. If that is not the case, use this macro to give the main add-on directory name. == 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+`. +Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/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_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`. == Architecture Fedora now encourages packagers to https://fedoraproject.org/wiki/Changes/EncourageI686LeafRemoval[not build packages for i686]. -For that reason, noarch GAP add-ons must include these tags: +For that reason, noarch GAP add-ons MUST include these tags: .... BuildArch: noarch ExclusiveArch: %{gap_arches} noarch .... -Architecture-specific GAP add-ons must instead include this tag: +Architecture-specific GAP add-ons MUST instead include this tag: .... ExclusiveArch: %{gap_arches} .... -However, any noarch subpackages, such as a documentation subpackage, must include this tag: -.... -ExclusiveArch: %{gap_arches} noarch -.... == Other RPM macros Other RPM macros that may be useful for GAP add-on spec files include the following: + * `+%gap_version+`: the version of the main GAP package; e.g., 4.12.0. -* `+%gap_dir+`: the root directory of the GAP installation, currently `/usr/lib/gap`. +* `+%gap_archdir+`: parent directory for arch-specific GAP add-ons, currently `+%{_libdir}/gap+`. +* `+%gap_libdir+`: the root directory of the GAP installation, currently `+%{_datadir}/gap+`. * `+%gap_arch+`: the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`.