Skip to content

docs: Document versions in README.md #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
limakzi wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: Document versions in README.md #130

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7c24fb4
docs: Inform on versions available
limakzi Mar 23, 2026
8674fa3
docs: Update front-most gap-versions
limakzi Mar 23, 2026
da38939
docs: Fix bullet punctuation
limakzi Mar 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 27 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@

```mermaid
graph RL
V1[gap-docker:4.13.1-bare] --> T
V2[gap-docker:4.13.1-full] --> T
V3[gap-docker:4.13.1-slim] --> T
V4[gap-docker:4.13.1-buildfull] --> T
V1[gap-docker:4.15.1-bare] --> T
V2[gap-docker:4.15.1-full] --> T
V3[gap-docker:4.15.1-slim] --> T
V4[gap-docker:4.15.1-buildfull] --> T
T --> V
V --> G

Expand All @@ -18,18 +18,36 @@
T@{ shape: processes, label: "bare/slim/buildfull/full"}
```

We have the following variants[^1]:

* **`bare`** - Core compiled from source with only the `PackageManager` package installed. Required packages are loaded via `InstallRequiredPackages()` — no optional packages are compiled. This is the _smallest image_, suitable for minimal or custom setups where you want full control over which packages to add.

* **`slim`** - Includes additional runtime libraries needed by optional packages. Suitable for users who want to _selectively compile_ only the packages they need.
Copy link
Copy Markdown
Contributor

@james-d-mitchell james-d-mitchell Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still not clear to me which packages are included with this build: this seems to imply that all deposited packages are included, if so, then this should be written explicitly. If not, then what packages are included?

Copy link
Copy Markdown
Member Author

@limakzi limakzi Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, none.

buildbare:

buildslim:

Its complied gap-system with additional packages, bare is just the core.

Copy link
Copy Markdown
Contributor

@james-d-mitchell james-d-mitchell Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we are using "package" to mean two different things :) I mean which "GAP packages" are included? Would it be possible to include which GAP packages are included in the README.md?

Copy link
Copy Markdown
Member Author

@limakzi limakzi Mar 25, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@james-d-mitchell I'm wondering if including may be a good idea.
Let me list loadable packages for gap-4.15.1.

  • slim:
gap>
[ "autpgrp", "format", "images", "aclib", "alco", "alnuth", "atlasrep", "autodoc", "automata", "automgrp", "cap", "circle", "classicpres", "congruence", "corefreesub", "corelg", "crime", "crisp", "cryst", "crystcat", "ctbllib",
  "cubefree", "design", "difsets", "edim", "example", "examplesforhomalg", "factint", "fga", "forms", "gapdoc", "gauss", "gaussforhomalg", "gbnp", "generalizedmorphismsforcap", "gradedmodules", "gradedringforhomalg", "grape",
  "groupoids", "grpconst", "guarana", "guava", "hecke", "homalg", "homalgtocas", "ibnp", "idrel", "inducereduce", "intpic", "irredsol", "laguna", "liealgdb", "liepring", "liering", "linearalgebraforcap", "lins",
  "localizeringforhomalg", "loops", "lpres", "mapclass", "matricesforhomalg", "modisom", "modulepresentationsforcap", "modules", "monoidalcategories", "nilmat", "nock", "numericalsgps", "packagemanager", "patternclass", "permut",
  "polenta", "polycyclic", "polymaking", "primgrp", "qdistrnd", "qpa", "quagroup", "radiroot", "rds", "repndecomp", "repsn", "resclasses", "ringsforhomalg", "sco", "sglppow", "sgpviz", "singular", "sl2reps", "sla",
  "smallantimagmas", "smallclassnr", "smallgrp", "smallsemi", "sonata", "sophus", "sotgrps", "spinsym", "standardff", "symbcompcc", "thelma", "tomlib", "toolsforhomalg", "toric", "transgrp", "twistedconjugacy", "typeset",
  "ugaly", "unipot", "utils", "uuid", "wedderga", "wpe", "yangbaxter" ]
  • full:
[ "help", "anupq", "autpgrp", "format", "images", "orb", "recog", "4ti2interface", "ace", "aclib", "agt", "io", "alco", "alnuth", "atlasrep", "autodoc", "automata", "automgrp", "browse", "cap", "caratinterface", "cddinterface",
  "circle", "classicpres", "cohomolo", "congruence", "corefreesub", "corelg", "crime", "crisp", "crypting", "cryst", "crystcat", "ctbllib", "cubefree", "curlinterface", "cvec", "datastructures", "deepthought", "design",
  "difsets", "digraphs", "edim", "example", "examplesforhomalg", "factint", "ferret", "fga", "fining", "forms", "fplsa", "fr", "francy", "fwtree", "gapdoc", "gauss", "gaussforhomalg", "gbnp", "generalizedmorphismsforcap",
  "genss", "gradedmodules", "gradedringforhomalg", "grape", "groupoids", "grpconst", "guarana", "guava", "hap", "hapcryst", "hecke", "homalg", "homalgtocas", "ibnp", "idrel", "inducereduce", "intpic", "io_forhomalg", "irredsol",
  "json", "jupyterkernel", "jupyterviz", "kan", "kbmag", "laguna", "liealgdb", "liepring", "liering", "linearalgebraforcap", "lins", "localizeringforhomalg", "loops", "lpres", "majoranaalgebras", "mapclass", "matgrp",
  "matricesforhomalg", "modisom", "modulepresentationsforcap", "modules", "monoidalcategories", "nilmat", "nock", "nq", "numericalsgps", "openmath", "packagemanager", "patternclass", "permut", "polenta", "polycyclic",
  "polymaking", "primgrp", "profiling", "qdistrnd", "qpa", "quagroup", "radiroot", "rcwa", "rds", "repndecomp", "repsn", "resclasses", "ringsforhomalg", "sco", "scscp", "sglppow", "sgpviz", "simpcomp", "singular", "sl2reps",
  "sla", "smallantimagmas", "smallclassnr", "smallgrp", "smallsemi", "sonata", "sophus", "sotgrps", "spinsym", "standardff", "symbcompcc", "thelma", "tomlib", "toolsforhomalg", "toric", "transgrp", "twistedconjugacy", "typeset",
  "ugaly", "unipot", "unitlib", "utils", "uuid", "walrus", "wedderga", "wpe", "xmod", "xmodalg", "yangbaxter", "zeromqinterface" ]

It obviously may very between versions of GAP.

Copy link
Copy Markdown
Contributor

@james-d-mitchell james-d-mitchell Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could write for slim: "all deposited GAP packages (i.e. those distributed in the release archives) are included, but those requiring compilation have not been compiled. Some/all? system packages required to compile GAP packages are also installed in the container." Better that than listing every package which would require more maintenance than is perhaps reasonable, and would quickly get out of date.


* **`full`** - Contains _all packages compiled_ via `BuildPackages.sh --parallel`. It is the largest image and the most comprehensive variant. Recommended for most users.

* **`jupyter-gap`** - A separate image based on the `full` variant. Adds `JupyterLab` and the `gap-kernel`. Exposes port `8888` and launches notebook as the default command.

Besides that we have:

* **`buildfull`** - An _internal build stage_ used to compile all packages for the `full` image. Referenced in the build pipeline but not intended for direct use.

---

## Usage

* Run a container:

```
docker run -it ghcr.io/gap-system/gap:4.13.1-full
docker run -it ghcr.io/gap-system/gap:4.15.1-full
```

```
docker run -it ghcr.io/gap-system/gap:4.14.0-full
docker run -it ghcr.io/gap-system/gap:4.15.0-full
```

```
docker run -it ghcr.io/gap-system/gap:4.13.1-bare
docker run -it ghcr.io/gap-system/gap:4.14.0-bare
```

```
Expand All @@ -45,3 +63,5 @@ Although it was completely rewritten, this repository consists of various ideas

[1]: https://github.com/james-d-mitchell/gap-docker-minimal
[2]: https://github.com/stertooy/gda-image

[^1]: All variants are based on `Ubuntu 22.04` LTS.
Loading