Getting Started · Installation

macOS

The two options, in order of preference, are compiling from source or using Docker. There are a few extra steps required on a Mac versus Linux.

Compiling from Source

These instructions were tested in October 2026 on macOS 26 (Tahoe) on an Apple Silicon Mac, using Apple's Command Line Tools 15, Homebrew, GNU readline 8.3 and GNU bison 3.8. The whole build takes under a minute.

Quick version

If you already have the Command Line Tools and Homebrew, this is all you need:

brew install readline bison
git clone https://github.com/jeffreyadams/atlasofliegroups.git
cd atlasofliegroups
export PATH=/opt/homebrew/opt/bison/bin:$PATH
export CPATH=/opt/homebrew/opt/readline/include
make -j8 rl_libs="-L/opt/homebrew/opt/readline/lib -lreadline"
cd atlas-scripts
../atlas all.at

The steps below explain each line and what to do if something is missing.

What you need (none of it comes with macOS)

You do not need the full Xcode app, and you do not need MacPorts.

1. Install the Command Line Tools

Open the Terminal app (in Applications → Utilities) and type:

xcode-select --install

If they are already installed you will get a message saying so. (On a new Mac, the commands git, make and g++ exist but only pop up a dialog offering to install these tools.)

2. Install Homebrew

Type brew --version. If the command is not found, install Homebrew by following the instructions at brew.sh, which come down to:

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

At the end it prints a few “Next steps” commands that add brew to your PATH; run those, then open a new Terminal window.

3. Install readline and bison

brew install readline bison

Homebrew installs both of these “keg-only”: they go into /opt/homebrew/opt/readline and /opt/homebrew/opt/bison but are not put on the default search paths, because macOS has its own (unsuitable) versions. Step 5 tells the build where to find them.

4. Download the source code using git

Choose a directory to store the source code, navigate there in Terminal, then type:

git clone https://github.com/jeffreyadams/atlasofliegroups.git
cd atlasofliegroups

This creates a subdirectory atlasofliegroups and stores the files there. If you are not familiar with git see Help with git.

5. Compile

In the atlasofliegroups directory:

export PATH=/opt/homebrew/opt/bison/bin:$PATH
export CPATH=/opt/homebrew/opt/readline/include
make -j8 rl_libs="-L/opt/homebrew/opt/readline/lib -lreadline"

The first line puts the new bison ahead of Apple's; the second tells the compiler where the readline header files are; rl_libs tells the linker where the readline library is. (-j8 compiles 8 files at a time.) The export lines only last for the current Terminal window, so repeat them whenever you recompile. You will see many compiler warnings; these are expected. If all goes well you will have two programs, atlas and Fokko, in the atlasofliegroups directory.

6. Test it

cd atlas-scripts
../atlas all.at

Atlas loads its library and shows the atlas> prompt. Try:

atlas> set G=Sp(4,R)
Variable G: RealForm
atlas> trivial(G)
Value: final parameter(x=10,lambda=[2,1]/1,nu=[2,1]/1)
atlas> dimension(G)
Value: 10
atlas> quit

The up-arrow should recall previous commands, and the Tab key should complete names. Congratulations! Go on to After compiling for the next steps.

Why these steps? Mac pitfalls

• The compiler. On a Mac the command g++ is not GNU g++ but Apple's clang compiler under another name. The Makefile uses g++ -std=c++14, so it gets Apple clang, which works well; there is no need to install another compiler.
• bison. macOS includes bison version 2.3 (from 2006), which is too old. Without step 3 the build stops with parser.y:62.9-16: syntax error, unexpected identifier, expecting string followed by 'parser.tab.h' file not found.
• readline. macOS includes a library called libreadline, but it is really a different library (libedit) in disguise. If the build is not pointed at GNU readline as in step 5, it may compile but command-line editing will not work properly.
• Use rl_libs, not LDFLAGS. The atlas program is linked by a second Makefile (in sources/interpreter) that only looks at rl_libs.
• Old settings from MacPorts. Earlier versions of these instructions used MacPorts and had you add a line like export rl_libs="-lreadline -lcurses -L/opt/local/lib" to ~/.zprofile (or .profile, .zshrc, .cshrc), plus copies of readline headers in /usr/local/include/readline. These are no longer needed. Setting rl_libs on the make command line as above overrides the old setting, but you can delete the old line. MacPorts typically stops working after a major macOS upgrade.

To check which readline your programs use, run otool -L atlas Fokko. Both should list /opt/homebrew/opt/readline/lib/libreadline.8.dylib.

If you cannot get readline to work at all, make readline=false builds atlas without it (no command history or tab completion). To start a build over from scratch, run make clean.

After compiling

We recommend installing a short atlas command that you can run from any directory. On a Mac, ~/bin does not exist and is not on your PATH by default, so first:

mkdir -p ~/bin
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zprofile

Then open a new Terminal window, go to the atlasofliegroups directory, and type:

make install BINDIR=~/bin

(Plain make install without BINDIR does nothing.) This puts a small script ~/bin/atlas that runs the program and automatically loads all.at from the atlas-scripts directory. Don't move or delete the atlasofliegroups directory afterwards, since the script points to it.

We recommend creating a directory atlasofliegroups/my_files and always starting atlas from there:

cd atlasofliegroups
mkdir my_files
cd my_files
atlas

File Input and Output

Atlas looks for files in the working directory and the atlas-scripts directory (or whatever you specify with --path). Output files are always written to the working directory.

Updating the atlas software

In the atlasofliegroups directory:

git pull origin master

If only .at files changed you typically do not need to recompile. If .cpp or .w files changed, recompile using the three lines in step 5.

Using Docker

Docker installs a self-contained Linux container on your machine. Install Docker (community version), then:

sudo docker run -it jeffreyadams/atlasofliegroups:version1.1

This downloads and runs the software. The first time takes a few minutes; subsequent runs are much faster. To update:

sudo docker pull jeffreyadams/atlasofliegroups:version1.1

File Input and Output in Docker

Since Docker runs in a container, extra effort is required for file I/O. Use the -v flag to mount a host directory:

sudo docker run -it -v /host/path:/container/path jeffreyadams/atlasofliegroups:version1.1