Installing GAP and the `Semigroups` package

In this section we detail the installation of GAP and Semigroups on various platforms. We present two options for doing so:

Option 1: Standard install: The standard install path. It is slightly more involved than Option 2, but has been well tested over the years.
Option 2: Experimental install: A recent installation path using the Julia programming language. It is slightly quicker than Option 1, but may not work on all systems.

Either installation option will make use of the terminal and Unix shell. You should be able to follow the steps even without much familiarity with these, but we recommend the Unix shell software carpentries lesson to those interested in learning more.

Warning

Please do not install GAP using your systems package manager e.g. do not install it via apt-get install gap or brew install gap. The version of GAP packaged by your operating system and installed by these tools can be several years out of date and will likely cause issues further down the line.

You can remove a system installed version of GAP on an Ubuntu distribution of Linux by running

sudo apt-get remove gap

and on Mac by running

brew remove gap

Option 1: Standard install

This section outlines the standard installation process for GAP and Semigroups. It is split into two parts: the System based prerequisites section where we outline steps required to set up your operating system for installing GAP and Semigroups, and Common installation steps where we outline a method for installing GAP and Semigroups that should work on all systems, provided the prerequisites are installed.

System based prerequisites

Please select the appropriate tab for your operating system below and follow the steps therein:

WindowsMacLinux

GAP is primarily developed for Linux-based operating systems. In order to make it run on Windows, it is generally easier to install a Linux subsystem which provides a Linux shell than to try and make it run on Windows directly. Windows provides such a feature via the Windows subsystem for Linux (WSL).

We will follows a the guide available on the microsoft docs page to install WSL 2.

Open Powershell as administrator, this can be done by typing "powershell" in the search bar and then right-clicking the application icon and selecting "Run as administrator".
Within Powershell, run the following command:
```
wsl --install
```
Note that using Ctrl+V to paste in the terminal might not work, instead you should simply right-click in the window to paste. This step enables the feature that will allow us to run Linux as a subsystem of Windows. By default it will install the Ubuntu operating system. You may need to restart your computer after this step.
Once this is all done, open a terminal. This can be either powershell or windows-terminal or cmd (type either one in the search bar).
Within the terminal run the command ubuntu.
If all went well, you should be prompted to create a username and password for the default Linux user.
Once this is done, the terminal prompt should read something like user@computer-name:~$.

In the ubuntu terminal, update the package index and install some necessary prerequisite packages:

sudo apt-get update
sudo apt-get install curl build-essential autoconf libtool pkg-config graphviz libgmp-dev libreadline-dev zlib1g-dev

If all went well, you now have an Ubuntu Linux subsystem available via the ubuntu command. To install GAP and Semigroups, execute the ubuntu command in your terminal and then proceed as described in the Common installation steps section, following the instructions for a Linux system.

Troubleshooting

If the wsl --install command has been running for a long time and produces no output, kill it by pressing Ctrl+C in the terminal.

Check if wsl is enabled by running the

Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

command in powershell.

If the output of the above command indicates that wsl is disabled, then run
```
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux`
```
and re-attempt the wsl --install step.

For a Mac we need to install some prerequisite packages which we do via the Homebrew package manager. In order to do this we first install Homebrew following the steps outlined on their website.

Open the Terminal app. It should be under Utilities. Alternatively you can use the Mac spotlight computer search function and look for Terminal.

In the terminal run

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

To test the installation, try running brew -v.

Install the Apple developer tools via
```
xcode-select --install
```

Now use brew to install the necessary prerequisites:

brew update
brew install curl autoconf libtool pkg-config graphviz gmp readline zlib

Continue as described in the Common installation steps section.

In this section we assume that you are using the Ubuntu Linux distribution. If your distribution differs then you may need to modify the package manager used (e.g. on Fedora this may involve changing apt to dnf and modifying the package names).

Update the package index and install some necessary prerequisite packages:

sudo apt-get update
sudo apt-get install curl build-essential autoconf libtool pkg-config graphviz libgmp-dev libreadline-dev zlib1g-dev

Continue as described in the Common installation steps section.

Common installation steps

Before proceeding with the install instructions in this section, please make sure you have completed the steps outlined in the System based prerequisites section for your operating system above.

In order to install GAP we follow the installation instructions from the GAP website. We will install GAP in the "home" directory. You are free to use any other directory, if you do so, substitute the ~ in the following commands with whatever base directory you are using.

Type cd ~Enter in your terminal. This will ensure you are in the home directory, where the rest of the install will occur.

Download the current GAP distribution, at time of writing it is 4.15.1. If this has changed, then substitute the appropriate version number in the export command below:

export GAP_VERSION=4.15.1
curl -L "https://github.com/gap-system/gap/releases/download/v${GAP_VERSION}/gap-${GAP_VERSION}.tar.gz" > gap.tar.gz

If all went well you should see output similar to

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100  482M  100  482M    0     0  1823k      0  0:04:31  0:04:31 --:--:-- 2105k

and when using the lsEnter command to list files in the current directory, you should see a file called gap.tar.gz.

Unpack the archive:
```
tar -xvzf gap.tar.gz
```
if all went well the ls command should now reveal a new folder called gap-4.15.1 (or whatever the relevant version is). You can now type rm gap.tar.gzEnter to remove the archive.
Change into the gap directory and run the configure and make scripts:
```
cd gap-${GAP_VERSION}
./configure
make -j8
```
replacing the 8 in the -j8 by the number of cores you want to use. If all goes well, make should finish with without errors and running ./gapEnter gives the GAP prompt (you can quit from the GAP prompt by typing quit;Enter).
We are not quite done yet, since some of the optional packages need to be compiled before they can be used. In order to do so run
```
cd pkg
../bin/BuildPackages.sh
```
To test the package compilation, type ../gapEnter to open a GAP prompt and within the GAP prompt write
```
SetInfoLevel(InfoPackageLoading, 4);
LoadPackage("Semigroups");
```
If the package loads without errors, the compilation has likely been successful.

Otherwise you may see an error similar to the following:

#I  Semigroups: entering LoadPackage 
#I  Semigroups: PackageAvailabilityInfo for version 5.5.4
#I  Semigroups: the kernel module is not compiled, 
#I              the package cannot be loaded.
#I  Semigroups: PackageAvailabilityInfo: the AvailabilityTest function returned false
#I  Semigroups: PackageAvailabilityInfo: no installed version fits
#I  Semigroups: return from LoadPackage, package is not available
fail

If this is the case then type quit;Enter in the GAP session and perform the following steps to compile the Semigroups package manually:

cd semigroups
./configure
make -j4

compilation of the semigroups package is quite memory intensive, and may get killed if the computer runs out of memory. If so try compiling again setting a lower number of threads when running make, e.g. make -j2 or even just make.

To run GAP from an arbitrary folder on your computer you currently need to write ~/gap-$GAP_VERSION/gapEnter. To avoid having to do this execute the following:
```
mkdir -p ~/.local/bin
ln -s ~/gap-${GAP_VERSION}/gap ~/.local/bin/gap
```
This will add the gap executable to the local executable bin. To make it available, we need to make sure the ~/.local/bin directory is in your PATH. On a Linux machine this can be done by
```
echo 'if ! [[ "$PATH" =~ "$HOME/.local/bin:" ]] then PATH="$HOME/.local/bin:$PATH"; fi' >> ~/.bashrc
source ~/.bashrc
```
On a Mac do this instead:
```
echo 'if ! [[ "$PATH" =~ "$HOME/.local/bin:" ]] then PATH="$HOME/.local/bin:$PATH"; fi' >> ~/.zshrc
source ~/.zshrc
```
Test this works by typing gapEnter in the terminal, if all went well it should open a GAP prompt.

If all went well you should now be able to type gapEnter in your terminal, which should give you a GAP prompt, and running LoadPackage("Semigroups"); in the GAP prompt should successfully load the Semigroups package.

Option 2: Experimental install using Julia

Experimental

The content in this section is experimental and may not work on all systems. In this case we advise proceeding with the steps of the Option 1: Standard install section instead.

It has recently become possible to install GAP using the Julia programming language. This installation path is currently experimental but can be much quicker than the method detailed in the Option 1: Standard install section.

If you already installed GAP and Semigroups using the instructions from the section Option 1: Standard install, then skip this section.

For Windows users, it is still required to install wsl and run the following steps from the ubuntu subsystem, as detailed in the Windows tab of the System based prerequisites section. Linux and Windows users (in the ubuntu prompt) should then run

sudo apt-get update
sudo apt-get install curl

and Mac users should run

brew update
brew install curl

to install the required prerequisites.

We follow the Julia install instructions from the Julia website.

Install Julia by running
```
curl -fsSL https://install.julialang.org | sh
```
if you are on Linux or Windows (through the ubuntu prompt), run
```
source ~/.bashrc
```
on Mac run
```
source ~/.zshrc
```
you should now be able to run Julia by typing juliaEnter in the prompt. You can exit the Julia prompt by typing exit()Enter.
Run juliaEnter to get a Julia prompt and run
```
using Pkg; Pkg.add("GAP")
```
this should install the GAP.jl Julia package. If all went well, within the Julia prompt typing
```
using GAP; GAP.prompt();`
```
This should start a GAP prompt. In the GAP prompt type
```
SetInfoLevel(InfoPackageLoading, 4);
LoadPackage("Semigroups");
```
To check that the Semigroups package is available. Exit the GAP prompt by typing quit;Enter, which should return you to the Julia prompt. Exit the Julia prompt too via exit()Enter.

We will now create a script which will allow us to start the gap prompt by simply typing gap in the base shell. To do this first run

mkdir -p ~/.local/bin

Afterwards, if you are on a Linux machine, then run

echo 'if ! [[ "$PATH" =~ "$HOME/.local/bin:" ]] then PATH="$HOME/.local/bin:$PATH"; fi' >> ~/.bashrc
source ~/.bashrc

On a Mac do this instead:

echo 'if ! [[ "$PATH" =~ "$HOME/.local/bin:" ]] then PATH="$HOME/.local/bin:$PATH"; fi' >> ~/.zshrc
source ~/.zshrc

Finally, open julia and within the Julia prompt type
```
using GAP; GAP.Setup.create_gap_sh("~/.local/bin/", "gap");
```
Then exit() the Julia prompt. You should now be able to start a GAP session by typing gapEnter in your terminal.

Installing GAP and the Semigroups package

Option 1: Standard install

System based prerequisites

Common installation steps

Option 2: Experimental install using Julia

Installing GAP and the `Semigroups` package