Start GAP with prescribed package versions

[ThomasBreuer]

In order to reproduce computations from a GAP session, it is desirable to start GAP with a given set of GAP packages whose exact version numbers are prescribed.

The idea is as follows.

• In a GAP session, use the new function PackagesLoaded for collecting the names and version numbers of the currently loaded GAP packages.

• Write this description to a file.

• Set the new user preference PrescribedPackageVersions, with value the name of that file.

• Start a new GAP session. The user preference will modify the autoload process such that exactly the GAP packages listed in the file will be loaded, with exactly the listed versions.

This is just a first proposal. There are things to discuss for example:

• It is not clear that a user preference is the right way to trigger the changed behaviour, but adding a user preference was easier than adding a command line option.
• Would it be reasonable to prescribe not only the package version but also its path?
• What else would we like to get from this new feature?

(One motivation is a remark in oscar-system/GAP.jl/issues/1189.)

[ChrisJefferson]

I like the idea.

I wonder if at least a warning (and honestly, I'd be tempted to abort GAP, if the point is to ensure reproducability), if one of the package versions we expect to find is missing? Otherwise if someone loads a list of required packages and are missing one of the correct versions, that package just won't exist -- but that might not stop their calculation, just slow it down, if that package was optional.

[ThomasBreuer]

@ChrisJefferson The proposed code turns the prescribed packages (in the prescribed versions, since all other versions lying around get ignored) into needed packages of GAP. Thus one gets an error as soon as the first such package turns out to be not loadable. This is the error which one gets already now if for example the primgrp package cannot be loaded.

[ChrisJefferson]

Ah, thanks. I think I didn't read carefully, I thought the packages still got loaded later when requested.

[ThomasBreuer]

I thought the packages still got loaded later when requested

It is not clear what we really want in this respect.

The currently proposed code removes all information about packages that are not in the list of prescribed package versions. It is still possible to add a new package directory later in the GAP session, and then to load packages which can be found there. Shall we forbid this? Or shall we argue that adding a package directory does not happen silently, and users who do this can add other packages on top of the prescribed ones?

[ChrisJefferson]

A few years ago I would have said don't bother, but now I do have quite a bit of code that tries using PackageManager to install packages, and people have and maintain multiple package directories, and it might be nice to catch that.

However, I don't think that's required from day one, and we can't stop people doing bad things if they really want to in GAP.

[ThomasBreuer]

@james-d-mitchell You had mentioned in a discussion during the recent GAP Days that you would like to get a better control of the loaded GAP packages. Is the current pull request helpful in this respect, and what else would you like to get?

[james-d-mitchell]

I think this is a really useful feature to add, thanks @ThomasBreuer

I've tried playing around with this locally, and perhaps I am doing something wrong, but I see the following behaviour. I did:

gap> FileString("~/gap-requirements.txt", PackagesLoaded());
282
gap> Print(PackagesLoaded());
AutoDoc = "2025.05.09"
Digraphs = "1.14.0"
GAPDoc = "1.6.7"
GRAPE = "4.9.2"
IO = "4.9.1"
PackageManager = "1.6.3"
PrimGrp = "3.4.4"
Semigroups = "5.6.1"
SmallGrp = "1.5.4"
Smallsemi = "0.7.2"
TransGrp = "3.6.5"
datastructures = "0.4.0"
genss = "1.6.9"
images = "1.3.3"
orb = "5.0.0"

Added the line:

SetUserPreference("PrescribedPackageVersions", "~/gap-requirements.txt");

Restarting GAP:

 ┌───────┐   GAP 4.15dev-167-g348aa1e built on 2026-04-03 09:54:12+0100
 │  GAP  │   https://www.gap-system.org
 └───────┘   Architecture: aarch64-apple-darwin25-default64-kv10
 Configuration:  gmp 6.3.0, GASMAN, readline
 Loading the library and packages ...
#W BIND_GLOBAL: variable `IsGraph' already has a value
#I  equal requirements in multiple declarations for operation `Vertices'

#W BIND_GLOBAL: variable `Adjacency' already has a value
Syntax warning: Unbound global variable in /Users/jdm3/gap/pkg/semigroups/gap/semigroups/semirms.gi:35
    i := Random(1, NumberSmallGroups(order));
                   ^^^^^^^^^^^^^^^^^
 Packages:   AutoDoc 2025.05.09, datastructures 0.4.0, Digraphs 1.14.0, GAPDoc 1.6.7, genss 1.6.9, GRAPE 4.9.2,
             images 1.3.3, IO 4.9.1, orb 5.0.0, PackageManager 1.6.3, PrimGrp 3.4.4, Semigroups 5.6.1, SmallGrp 1.5.4,
             Smallsemi 0.7.2, TransGrp 3.6.5
 Try '??help' for help. See also '?copyright', '?cite' and '?authors'
gap>

It seems that maybe the order the packages are loaded is getting messed up? Not sure.

It is not clear that a user preference is the right way to trigger the changed behaviour, but adding a user preference was easier than adding a command line option.

I think this is a good compromise.

Would it be reasonable to prescribe not only the package version but also its path?

Yes, this would be really useful. We've had numerous instances where students had multiple versions of package installed and this cased issues. If we could specify which copy of a package to use, this would simplify things enormously.

What else would we like to get from this new feature?

I think the only thing it would be good to see (other than fixing whatever is going wrong in the example above) would be to document how to use the feature:

1. In GAP do: FileString("path/to/some/file", PackagesLoaded());
2. Add the line SetUserPreference("PrescribedPackageVersions", "path/to/some/file"); to your gap.ini file. Call WriteGapIniFile if you don't have one already.
3. Restart GAP.

[ThomasBreuer]

@james-d-mitchell Thanks for your comments.

• Concerning the warnings you observed:
  Yes, the reason is a different ordering of LoadPackage calls.
  From the viewpoint of reproducibility, this ordering is relevant, thus we have to make sure that PackagesLoaded lists the packages in the order in which they have been loaded in the current session.
  Currently this information seems to be missing, I will change the pull request accordingly.
  (It is good that we noticed this fact, but the warnings indicate missing dependencies.
  For example, if NumberSmallGroups occurs in a file of the Semigroups package then the SmallGrp package is needed by Semigroups. Up to now, this was not a problem because SmallGrp is listed as a needed package of GAP and therefore gets loaded before Semigroups.
  With the proposed mechanism, all packages from the PrescribedPackageVersions list become needed packages of GAP, and currently the order in which they get loaded is different.)

• Concerning information about package paths:
  On the one hand, this can be useful, perhaps it helps already to tell the user about some surprising package installation paths.
  On the other hand, prescribed paths are not helpful if one tries to repeat a computation on a different computer, and in theory, two installations of a packages with the same version number should behave equally.
  We can provide two variants of PackagesLoaded, one that lists version numbers and paths, one that lists only version numbers.

• Concerning the documentation:
  Yes, the feature must be documented once we know what exactly it offers.