Setting up the Digraphs package for development

This short guide aims to get GAP and a development version of the Digraphs package up and running in on various different operating systems in a uniform manner. It assumes little to no previous experience with the Linux shell and GAP. More experienced readers may wish to skip to the final section on compiling the development version of the Digraphs package.

Setting up the shell environment

In this section we will try and set up a unified Linux shell environment from which we can install GAP, Digraphs and all the required dependencies in future steps. The section is divided into subsections based on the operating system of the development device.

On Windows

The Windows shell is very different from the Linux shell and for various reasons it is much easier to develop the GAP software by using a Linux shell. Thankfully it is quite easy to get one up and running for Windows:

0. We will follows the guide available on the Microsoft docs page to install WSL-2.

1. 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".

2. 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.

3. You may need to restart your device once the installation is finished.

4. Optionally, you can also install the windows terminal:
   https://docs.microsoft.com/en-us/windows/terminal/install
   This is a terminal similar to the cmd or powershell terminals of Windows, but its slightly easier to customize and has a nicer color-scheme out of the box.

5. Once this is all done, open a terminal. This can be either windows-terminal or powershell or cmd (type either one in the search bar).

6. Within the terminal run the command ubuntu.

7. If all went well, you should be prompted to create a username and password for the default Linux user.

8. Finally, the prompt should have changed to something like user@computer-name:~$.

Troubleshooting the WSL install

Some things may go wrong when doing the above. Here are some common issues and fixes:

The wsl --install command gets stuck without making progress

Troubleshooting steps:

0. 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.

1. Check if wsl is enabled by running the Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux command.

2. If the output of the above command indicates that wsl is disabled, then run Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

On Mac

For a Mac we will install the Homebrew package manager. A package manager is a shell utility that allows us to easily install and upgrade software without leaving the shell. This is something that comes by default with most Linux distributions like Ubuntu, but is not present by default on Macs. Thankfully the install is really easy:

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

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

3. To test the installation, try running

   brew -v
   

From now on wherever the guide uses the apt package manager, substitute this for brew.

On Linux

If you are already running a Linux distribution then you should be ok for the rest of the guide. Make sure to substitute apt for whatever package manager you are using.

Updating software

Just to make sure we have up to date tools for the rest of the setup we should now run the following commands within Ubuntu:

sudo apt update && sudo apt upgrade

Or for a Mac run:

sudo brew update && sudo brew upgrade

Installing GAP

We will now attempt to install GAP. The instructions will be written assuming you are working within an Linux terminal (for example the Ubuntu terminal provided by WSL on windows, see above). On a Mac things should be more or less the same, but you should use brew install instead of apt install.

Installing the necessary tools

Before we go installing GAP itself, we will need a couple of tools. To get them, run

sudo apt install curl build-essential autoconf libtool

A breakdown of the tools and their function is as follows:

curl - used to download files over the internet
build-essential - essential tools for compiling C source code
autoconf - for configuring make scripts
libtool - for finding libraries when running `autogen.sh`

Note: If you want a wider set of tools that can be used with GAP, you might want to run

sudo apt-get install autoconf build-essential curl git graphviz libtool libgmp-dev texlive-full

or on a Mac,

brew install git autoconf automake curl GMP graphviz libtool

You might be wondering now "why don't we just use apt to install gap"? Indeed this is possible and will actually work, however we will get the version of GAP that has been packaged by the Ubuntu (or Homebrew or whatever other distribution you use) maintainers. This is usually not the latest version. For example, at time of writing the version of GAP packaged with Ubuntu is 4.8.8 which is almost 5 years old!

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.

Downloading GAP

0. Run cd ~. This will ensure you are in the home directory, where the rest of the install will occur.

1. Download the current GAP distribution, at time of writing it is 4.13.0, the latest release can be found on the gap downloads page, where you can also find the relevant URL which you can substitute in this command:

curl -L https://github.com/gap-system/gap/releases/download/v4.13.0/gap-4.13.0.tar.gz > gap.tar.gz

the -L parameter tells curl to follow redirects in case the link doesn't directly lead to a file, the > operator at the end redirects the output of the curl command into the file 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 ls command to list files in the current directory, you should see a file called gap.tar.gz.

2. Unpack the archive:

tar -xvzf gap.tar.gz

if all went well the ls command should now reveal a new folder called gap-4.13.0 (or whatever the relevant version is). You can now rm gap.tar.gz to remove the archive.

Compiling GAP

What we have downloaded is the source code for GAP, it is not yet compiled and so we can't really execute it. To do so we will follow the steps from the GAP webpage.

1. Change into the gap directory cd gap-4.13.0.

2. Run the configure command ./configure. This will run a number of tests to figure out e.g. what compiler you are using, what libraries are available and so on, and use this information to create a Makefile which will then tell the make command how to assemble the sources in the next step.

3. Run the make command make -j8 replacing the 8 by the number of cores you want to use. The -j flag parallelizes the execution which makes it much faster especially on large codebases. If all goes well, make should finish with without errors and running ./gap gives the GAP prompt:

 ┌───────┐   GAP 4.13.0 of 2024-03-15
 │  GAP  │   https://www.gap-system.org
 └───────┘   Architecture: x86_64-pc-linux-gnu-default64-kv9
 Configuration:  gmp 6.2.1, GASMAN, readline
 Loading the library and packages ...
 Packages:   AClib 1.3.2, Alnuth 3.2.1, AtlasRep 2.1.8, AutPGrp 1.11, Browse 1.8.21, 
             CaratInterface 2.3.6, CRISP 1.4.6, Cryst 4.1.27, CrystCat 1.1.10, 
             CTblLib 1.3.9, curlInterface 2.3.2, FactInt 1.6.3, FGA 1.5.0, Forms 1.2.9, 
             GAPDoc 1.6.7, genss 1.6.8, IO 4.8.2, IRREDSOL 1.4.4, LAGUNA 3.9.6, 
             orb 4.9.0, Polenta 1.3.10, Polycyclic 2.16, PrimGrp 3.4.4, RadiRoot 2.9, 
             recog 1.4.2, ResClasses 4.7.3, SmallGrp 1.5.3, Sophus 1.27, SpinSym 1.5.2, 
             StandardFF 1.0, TomLib 1.2.11, TransGrp 3.6.5, utils 0.85
 Try '??help' for help. See also '?copyright', '?cite' and '?authors'
gap> 

4. We are not quite done yet, since some of the optional packages (including digraphs and libsemigroups) need to be compiled before they can be used. In order to do so run cd pkg and ../bin/BuildPackages.sh --parallel. This should now start the quite slow process of compiling all of the packages, feel free to go brew some tea while its chugging along. (Note that if you have moved the GAP directory between steps 3. and 4. then this step might throw an error. Please re-run steps 1-4.)

5. To test the package compilation, run ../gap and within the GAP prompt write LoadPackage("digraphs");. If the package loads without errors, the compilation has likely been successful. To test things further you could run DigraphsTestInstall(); within GAP, which runs a set of tests

Aliasing the GAP executable

We now have compiled GAP, but typing gap in the shell from an arbitrary directory wont work. We will solve this by creating an alias to the gap executable.

1. To do so run (one a Mac substitute .zshrc for .bashrc)

echo "alias gap=~/gap-4.13.0/gap" >> ~/.bashrc

This will append the line alias gap=~/gap-4.13.0/gap to your bash (or zsh on Mac) configuration file which will tell the terminal what we mean by the gap command.

2. You can now either restart the terminal or source the new bashrc with source ~/.bashrc, this will load the configuration.

3. Test by running the gap command in your terminal.

Installing the development version of the Digraphs package

Under construction