PR#1211: Update GAP packaging guidelines - packaging-committee

packaging-committee

#1211 Update GAP packaging guidelines

Merged 2 years ago by tibbs. Opened 2 years ago by jjames.

jjames/packaging-committee master into master

Update GAP packaging guidelines

Jerry James • 2 years ago

ce84006

guidelines/modules/ROOT/pages/GAP.adoc

file modified

+41 -5

		`@@ -5,12 +5,19 @@`

		`== 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 @@`

		`== 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 @@`

		`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`.

jjames commented 2 years ago

I am about to update the GAP stack in Fedora due to the release of GAP 4.12.0. The builds have all been done in a COPR to work out issues in advance. The GAP guidelines need some updates to reflect the state of these new package builds.

Executive summary of the changes:
- 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

There are no EPEL packages for the GAP stack, so removal of the Testing section will not impact EPEL.

tibbs commented 2 years ago

About the only thing I can say is that it would be nice if that super-long line acquired some semantic line breaks, and that it's better if line breaks are added in a separate commit from content changes so that it's easy to see what actually changed. However, these are minor issues and the changes seem reasonable and not at all controversial.

Thanks.