Towards v3

.github/workflows/CI.yml

@@ -1,53 +1,65 @@
 name: CI
 
-# Trigger the workflow on push or pull request
 on:
   push:
-    branches:
-      - master
-      - cygwin*
   pull_request:
-
-env:
-  CHERE_INVOKING: 1
+  workflow_call:
+  workflow_dispatch:
 
 jobs:
   test:
-    name: ${{ matrix.gap-branch }} ${{ matrix.ABI }} - Packages ${{ matrix.GAP_PKGS_TO_BUILD }} - HPCGAP ${{ matrix.HPCGAP }} - ${{ matrix.os }}
+    name: ${{ matrix.gap-version }} on ${{ matrix.os }} with ${{ matrix.configflags }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest]
-        gap-branch:
-          - master
-        ABI: ['']
-        GAP_PKGS_TO_BUILD:
-          - ''
-          - 'default'
-        HPCGAP: ['no']
-        include:
-          - os: ubuntu-latest
-            gap-branch: master
-            GAP_PKGS_TO_BUILD: ''
-            HPCGAP: yes
-          - os: ubuntu-latest
-            gap-branch: master
-            ABI: 32
-            GAP_PKGS_TO_BUILD: 'default'
-            HPCGAP: no
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        gap-version:
+          - v4.10
+          - v4.11.1
+          - stable-4.12
+          - v4.13.0-alpha2
+          - 4.15.0-beta1
+          - 4
+          - latest
+          - default
+          - v4.16dev
+        configflags: ['', '--with-gmp=builtin']
+        exclude:
+          - os: windows-latest
+            configflags: '--with-gmp=builtin'
+          - os: macos-latest
+            gap-version: stable-4.12
+          - os: macos-latest
+            gap-version: v4.10
           - os: macos-latest
-            gap-branch: master
-            GAP_PKGS_TO_BUILD: ''
-            HPCGAP: no
+            gap-version: v4.11.1
+            configflags: '--with-gmp=builtin'
 
     steps:
-      - uses: actions/checkout@v5
-      - if: ${{ matrix.os == 'windows-latest' }}
-        uses: gap-actions/setup-cygwin@v1
-      - uses: ./
+      - name: "Checkout"
+        uses: actions/checkout@v5
+
+      - name: "Setup Cygwin"
+        if: ${{ matrix.os == 'windows-latest' }}
+        uses: gap-actions/setup-cygwin@v2
+
+      - name: "Setup GAP"
+        uses: ./
         with:
-          GAPBRANCH: ${{ matrix.gap-branch }}
-          ABI: ${{ matrix.ABI }}
-          GAP_PKGS_TO_BUILD: ${{ matrix.GAP_PKGS_TO_BUILD }}
-          HPCGAP: ${{ matrix.HPCGAP }}
+          gap-version: ${{ matrix.gap-version }}
+          configflags: ${{ matrix.configflags }}
+
+      - name: "Check if GAP can run"
+        shell: bash
+        run: |
+          gap -A <<GAPINPUT
+            quit;
+          GAPINPUT
+
+      - name: "Check ENV for GAPROOT and GAP variables"
+        shell: bash
+        run: |
+          if [[ -z "$GAPROOT" || -z "$GAP" ]] ; then
+            exit 1
+          fi

README.md

@@ -1,49 +1,138 @@
-# setup-gap V2
+# setup-gap v3
 
 This GitHub action downloads and prepares an instance of GAP.
 It is intended to be used by the Continuous Integration (CI) action of a GAP
 package, that is by an action which runs a package's test suite.
 
 ## Supported OSes
 
-This action can be run on macOS and Ubuntu.
+This action can be run on macOS, Ubuntu and Windows (when preceded by the `setup-cygwin` action).
 
 
 ## Usage
 
 The action `setup-gap` has to be called by the workflow of a GAP
 package.
 By default it
-- downloads and compiles the master branch of GAP,
-- downloads the packages distributed with GAP, and
-- compiles the packages `io` and `profiling`
+- downloads and compiles the latest release of GAP, and
+- compiles the packages `io`, `json` and `profiling`
 
 Its behaviour can be customized via the inputs below.
 
 ### Inputs
 
 All of the following inputs are optional.
 
-- `GAP_PKGS_TO_CLONE`:
-   - A space-separated list of the GAP packages to clone.
+- `gap-version`:
+   - The gap version or branch to build. You may specify "latest" for the latest release, or "default" for the default branch.
+     see "Changes to inputs" under "What's new in v3" for more details.
+   - default: `latest`
+- `repository`
+   - The GitHub repository from which to clone GAP.
+   - default: `'gap-system/gap'`
+- `configflags`:
+   - Arguments to pass to the GAP configure script.
    - default: `''`
-   - example: `'io autodoc'`
-- `GAP_PKGS_TO_BUILD`:
-   - A space-separated list of the GAP packages to build. Must include
-     `io` and `profiling`.
-   - default: `'io profiling'`
-- `GAPBRANCH`:
-   - The gap branch to clone.
-   - default: `master`
-- `HPCGAP`:
-   - Build HPC-GAP if set to `yes`.
-   - default: `no`
-- `ABI`:
-   - Set to `32` to use 32bit build flags for the package
-   - default: `''`
-- `GAP_BOOTSTRAP`
-   - Which packages to build GAP with (options: full or minimal)
-   - default: `'full'`
+
+### What's new in v3
+Version v3 contains many changes compared to version v2. When replacing `setup-gap@v2` by `setup-gap@v3` in an existing workflow,
+you will have to change the inputs accordingly. We also recommend replacing branches by releases, e.g. `stable-4.14` by `4.14`.
+
+#### Changes to inputs:
+ - The `GAPBRANCH` input has been replaced by `gap-version`, which accepts the following input types:
+   - `latest`: this will use the latest release of GAP. This will **not** point to the latest pre-release if it is more recent
+     than the latest release.
+   - version numbers: e.g. `v4.14.0`, `v4.15.0-beta1`, etc. The leading `v` is optional, the oldest available release is `v4.10.0`.
+   - incomplete version numbers: e.g. `v4`, `v4.10`, etc. These will be expanded to the most recent release starting with the incomplete
+     version number, e.g. `v4.10` is equivalent to `v4.10.2`. This will **not** expand to pre-releases, and again the leading `v` is
+     optional.
+   - branch and tag names: e.g. `master`, `stable-v4.14`, etc. This will use the GAP version built from the corresponding branch or tag.
+     NB: the inputs `master`, `main` and `default` will always point at the "default branch" of the repository, i.e. the branch you are
+     presented with when navigating to `github.com/<owner>/<repo>`.
+ - The inputs `GAP_PKGS_TO_CLONE` and `GAP_PKGS_TO_BUILD` have been removed. This should now be done by the user in a separate step in
+   the workflow, e.g. by using `git clone` or the [PackageManager](https://gap-packages.github.io/PackageManager/) package. See the
+   Examples section below.
+ - The input `GAP_PKGS_TO_BUILD` has been renamed to `gap-pkgs-to-build`. It can only be used to build packages distributed with GAP.
+   In addition to `IO` and `profiling`, the package `json` is now also built by default.
+ - The inputs `HPCGAP` and `ABI` have been removed, and support for both HPC-GAP and 32-bit builds has been removed.
+ - The (previously undocumented) input `CONFIGFLAGS` has been renamed to `configflags`.
+ - The input `GAP_BOOTSTRAP` has been removed. GAP will always come with all distributed packages.
+ - An input `repository` has been added, which allows building a version of GAP hosted on a repository different from `gap-system/gap`.
+
+#### Changes to functionality:
+ - There is no longer a separate branch for running this action on Windows. This action should work on Windows, assuming it is
+   preceded by version v2 or later of [setup-cygwin](https://github.com/gap-actions/setup-gap).
+ - The installation location of GAP is stored in the environment variable `GAPROOT`, which can be used in subsequent steps in the workflow.
+ - The GAP executable is added to `PATH`, thus GAP can now always be started by calling `gap`.
+
+### Examples
+
+The following is a minimal example to run this action.
+
+```yaml
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  # The CI test job
+  test:
+    name: CI test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+      - uses: gap-actions/setup-gap@v3
+      # ... additional steps using GAP will usually follow here
+```
+
+A more extensive example:
+
+```yaml
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  # The CI test job
+  test:
+    name: CI test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        gap-version:
+          - latest
+          - v4.15.0-beta1
+          - master
+
+    steps:
+      - uses: gap-actions/setup-cygwin@v2
+        if: ${{ matrix.os == 'windows-latest' }}
+      - uses: actions/checkout@v5
+      - uses: gap-actions/setup-gap@v3
+        with:
+          gap-version: ${{ matrix.gap-version }}
+      - shell: bash
+        run: |
+          # Install package via 'git clone'
+          cd $HOME/.gap/pkg
+          git clone https://github.com/gap-packages/io
+          cd io
+          sh autogen.sh
+          ./configure --with-gaproot=$GAPROOT
+          make -j4
+      - shell: bash
+        run: |
+          # Install packages via PackageManager
+          gap -c 'LoadPackage("PackageManager"); InstallPackage("https://github.com/gap-packages/orb"); QUIT;'
+          gap -c 'LoadPackage("PackageManager"); InstallPackage("cvec"); QUIT;'
+```
 
 ## Contact
 Please submit bug reports, suggestions for improvements and patches via