From ce84006d5fb91bc9e017b89a77c361b75f2a09ab Mon Sep 17 00:00:00 2001 From: Jerry James Date: Sep 20 2022 20:59:31 +0000 Subject: Update GAP packaging guidelines - Add libgap to the list of core GAP packages - New SHOULD: do not install into versioned directories - Allow transitive dependency on gap-core - Document %gap_copy_docs for installing documentation - Remove obsolete Testing section - Add Architecture section describing %gap_arches - Add Other RPM macros section describing %gap_version, %gap_dir, and %gap_arch --- diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index cffe51e..90feeed 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -5,12 +5,19 @@ This document describes the conventions and customs surrounding the proper packa == 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. +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, gap-vim, and libgap. 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. +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. +Documentation for one package often crosslinks into documentation for other packages. +If the directories involved contain version numbers, then the crosslinks can be broken by a package upgrade. +Avoid this situation by omitting the version numbers. +GAP itself can retrieve the version number from the add-on's `+PackageInfo.g+` file, so no information is lost. + == 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. @@ -37,7 +44,10 @@ Add-ons that use Autodoc to build documentation MUST include `+BuildRequires: ga == 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. +All add-ons MUST include `+Requires: gap-core+`, either directly or transitively. +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 @@ -58,10 +68,36 @@ GAP add-ons are intended to be unpacked in place within a GAP directory tree. Or 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. +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+`. -== 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. +== 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: +.... +BuildArch: noarch +ExclusiveArch: %{gap_arches} noarch +.... +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_arch+`: the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`.