GAP-PKG.ECLASS

Section: eclass-manpages (5)
Updated: Oct 2024
Index Return to Main Contents

NAME

gap-pkg.eclass - Simplify the installation of GAP packages.

DESCRIPTION

The main purpose of this eclass is to build and install GAP packages that typically occupy the dev-gap category. Most GAP packages do not support an install target out of the box, so the default installation is "by hand," with attention paid to those directories that are part of the recommended layout. The prepare, configure, and compile phases do however try to support packages having a real build system.

GAP itself has four "required" packages that are packaged separately, making dependencies between them somewhat weird. The four required packages are,

  * dev-gap/gapdoc
  * dev-gap/primgrp
  * dev-gap/smallgrp
  * dev-gap/transgrp

Those four packages will have only sci-mathematics/gap added to RDEPEND. All other packages will have the four required packages above added to RDEPEND in addition to sci-mathematics/gap. In theory it would be better to list all dependencies explicitly rather than grouping together the "required" four, but this is how upstream GAP works, and is what all GAP packages expect; for example, most test suites fail without the required packages but make no attempt to load them.

If you need a version constraint on sci-mathematics/gap, you'll have to specify it yourself. Compiled packages will likely need sci-mathematics/gap in DEPEND as well, and may also want a subslot dependency.

SUPPORTED EAPIS

FUNCTIONS

gap-pkg_dir

The directory into which the gap package should be installed. The accepted current location is /usr/$(get_libdir)/gap/pkg, but technically this depends on the econf call in sci-mathematics/gap.

gap-pkg_econf [extra econf args]

Call econf, passing the value of _gap-pkg_gaproot to --with-gaproot. All arguments to gap-pkg_econf are passed through to econf.

gap-pkg_src_configure

Handle both autoconf configure scripts and the hand-written ones used by many GAP packages. We determine which one we're dealing with by running ./configure --help; an autoconf configure script will mention "PREFIX" in the output, the others will not.

Autoconf configure scripts are configured using gap-pkg_econf, while hand-written ones are executed directly with _gap-pkg_gaproot as their sole positional argument.

gap-pkg_src_compile

The default src_compile with the addition of V=1 to emake. The Makefile.gappkg used to build most C packages defaults to a quiet build without this.

gap-pkg_enable_tests

Amend IUSE, RESTRICT, and BDEPEND for a package with a test suite. This is modeled on similar functions in the distutils-r1 and elisp-common eclasses, except here only a single default testing strategy is supported. All runtime and post-merge dependencies are added as build dependencies if USE=test is set.

gap-pkg_src_test

Run this package's test suite if it has one. The GAP TestPackage function is the standard way to do this, but it does rely on the package itself to get a few things right, like running the tests verbosely and exiting with the appropriate code. The alternative would be run TestDirectory ourselves on "tst", but that has its own issues; in particular many packages have set-up code that is run only with TestPackage. YMMV.

gap-pkg_src_install

Install a GAP package that follows the suggested layout,

https://docs.gap-system.org/doc/ref/chap76.html

In particular:

1. All GAP source files (*.g) in $S are installed.

2. If a library directory named "gap" or "lib" exists,
it is installed.

3. If a binary directory "bin" exists, it is installed.

4. If a "doc" directory exists, we assume GAPDoc conventions
   (https://docs.gap-system.org/pkg/gapdoc/doc/chap5.html) and install
   what we find there. Unfortunately for us, each package's
   PackageInfo.g contains a "PackageDoc" section that points to this
   documentation, and we can't break the paths it references. Instead,
   we try to dosym the human-readable parts of the documentation (PDF
   manuals) into appropriate Gentoo locations.

5. We consult GAP_PKG_HTML_DOCDIR for the HTML documentation and repeat
the process above.

A few GAP packages have autotools build systems with working "make install" routines, but most don't. So for the time being we omit that step. It's harder to work around the packages that don't support it than the other way around.

ECLASS VARIABLES

GAP_PKG_EXTRA_INSTALL

A bash array of extra files and directories to install recursively at the root of this package's directory tree. For example, if you have a package that mostly follows the suggested layout (described in the gap-pkg_src_install documentation) but also includes a "data" directory, you should set

GAP_PKG_EXTRA_INSTALL=( data )

to install the data directory without having to override the entire src_install phase.

GAP_PKG_HTML_DOCDIR ?= doc

The directory inside the tarball where the HTML documentation is located. This is _usually_ "doc", which conforms to the suggested GAPDoc layout and is the default value of this variable. Many packages however use a top-level "htm" directory instead. The named directory will be installed to gap-pkg_dir and symlinked to the usual location under /usr/share/doc. As a result, you should only use this for directories referenced by PackageInfo.g or by some other part of the package. HTML documentation whose location doesn't need to be known to the package at runtime should instead be installed with HTML_DOCS or a similar mechanism.

AUTHORS

François Bissey <frp.bissey@gmail.com>
Michael Orlitzky <mjo@gentoo.org>

MAINTAINERS

François Bissey <frp.bissey@gmail.com>
Michael Orlitzky <mjo@gentoo.org>
Gentoo Mathematics Project <sci-mathematics@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

gap-pkg.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:02 GMT, October 07, 2024