↓Skip to main content
  1. Blog/

Installing Acoustics Toolbox (AT) on macOS Silicon

Table of Contents

Overview
#

The Acoustics Toolbox (AT) programs were written in Fortran and must be compiled into machine-readable binary executables prior to use. Unlike computers running the Windows operating system (OS), Apple’s computers run the Unix-based macOS and code compilation is dependent on the unique chipset of the computer on which AT will be run (the same is true for computers running Linux). This document describes the prerequisites and general procedure for installing AT on macOS.

Helpful Concepts
#

Unix Operating System
#

The Unix operating system on which macOS is built has a system directory structure that can be cryptic for casual or even advanced computer users. To better understand where various tools and software are installed on your Mac, consult this introduction to the Unix file system.

Terminal/Shell/ZSH
#

The Terminal application on macOS is a command-line interface (CLI) that allows users to interact with the OS and is sometimes referred to as a “shell”. Since macOS Catalina, the program behind the CLI by default is Z shell (Zsh), and is a replacement of the older bash CLI software.

Environment (System) Variables
#

Environment variables–sometimes called system variables–are configuration settings that are used by the OS and a variety of programs. For example, the system variable PATH dictates which directories in the OS directory structure are searched when a command is typed into the Terminal. To query a list of environment variables, run the following command in Terminal:

env

A long list of variables will be returned formatted as VARIABLE=<value>. To query a specific environment variable, e.g., the PATH variable, run the following:

echo $PATH

These values can be overridden in the running Terminal session by running the following:

user@host:~$ export SHELL=/bin/bash

Additionally, values can be pre-pended or appended by placing a colon between the current value of the variable and the additional value, e.g.:

export PATH=/prepended/path:$PATH # Prepending
export PATH=$PATH:/appended/path # Appending

The order in which the additional value is placed is important, as commands typed in Terminal cycle through the path from first to last and execute the first instance of the command that is found.

To modify existing or define new environment variables in all future Terminal sessions, create a .zprofile or .zshrc file in the user’s home directory as follows:

cd ~
touch .zshrc

Environment variables can be altered or defined in the file as follows:

export PATH=/prepended/path:$PATH

To apply changes in .zshrc or .zprofile in the currently running Terminal session, run the following from the user’s home directory:

source .zshrc

Prerequisites
#

Several open source software tools must be installed on your computer prior to installing AT on macOS. You can check if the following tools are installed by opening a Terminal session and running which <program>. For example, to check if GNU Make is installed, run the following:

which make

If installed, the path to the program is printed, e.g., usr/bin/make. If not installed, an error will be displayed: make not found

Some tools may already be installed, particularly if you have previously installed Xcode Command Line Tools (a.k.a. Apple Command Line Tools). Unfortunately, these versions of the tools are sometimes unable to successfully compile AT, and the tool must be installed using an alternative package manager called Homebrew. With two versions of a tool installed on macOS, care must be taken to ensure the desired version of the tool is on the $PATH system variable when compiling AT.

Homebrew
#

Homebrew is a package manager for macOS. Similar to how apt works for Linux, Homebrew enables users to download open source software from online repositories. Instructions for how to install Homebrew are provided on their website.

When installing Homebrew, pay close attention to the messages displayed in the Terminal toward the end of the installation process. Specific instructions on how to update your PATH environment variable are provided so that programs installed using Homebrew can be found when called from Terminal.

GNU Make
#

GNU Make is a tool used to compile source files and code into executable, binary files. AT installation is performed using GNU Make.

GNU Compiler Collection (GCC)
#

GCC is a collection of open-source software compiler tools for a variety of languages. One of the compilers included is GNU Fortran (GFortran), which is what is required to compile AT. While GCC is included in Xcode Command Line Tools, it unfortunately does not compile AT successfully. To verify that the incorrect version is installed, run the following:

which gcc

If the output is /usr/bin/gcc, GCC is indeed installed, but it is unclear if the correct version of GFortran is available, which can be checked with:

which gfortran

If the output is usr/bin/gfortran or gfortran not found, then the correct version of GFortran is not installed, and GCC must be installed using Homebrew.

To install GCC using Homebrew, run the following:

brew install gcc

Once installed, verify that the correct version of GFortran is installed:

which gfortran

If installed correctly, the following path should be returned: /opt/homebrew/bin/gfortran If still incorrect, reload your .zshrc or .zprofile by running

source .zshrc

Alternatively, you can close the current Terminal session and open a new one. Check the version again with which gfortran. If the path is still incorrect, consult the voluminous Homebrew and Stack Exchange forums for troubleshooting guidance.

Installation
#

Download AT source files
#

Download the latest AT zip file from the HLS website and unzip to the desired location. For the purposes of this tutorial, AT will be unzipped to the home directory such that all files will be contained in the directory ~/at (in full form, /Users/<username>/at).

Edit the Makefile
#

  1. Open the file named Makefile with a text editor.

  2. Scroll down to the section titled *** ifort. Comment out all commands in this section by placing a pound sign (#) in front of any lines missing them, e.g.: # export FC=ifort

  3. Scroll down to the section titled *** GNU Compiler Collection GFORTRAN. Ensure the Fortran compiler environment variable is active (uncommented): export FC=gfortran

  4. Underneath this line should be one other line that is active (uncommented) that starts like:
    export FFLAGS= -mcpu=apple-m2 -Bstatic -Waliasing etc.

    The option flag -mcpu specifies the computer architecture for which the compiler should be optimized; there are many options. GFortran lags behind Mac hardware releases by weeks or months, and setting the architecture to an older or different chipset may not work. You are welcome to try compiling with this flag included, but I recommend removing it altogether. I have not noticed any major performance impacts when removing the -mcpu flag, and doing so allowed for compiling AT with no errors.

Compile AT
#

In Terminal, change your working directory to the AT directory (/users/<username>/at):

cd at

Compile AT by simply calling Make within the AT directory:

make

GFortran will begin compiling the source files contained within the AT directory as directed by the Makefile. Upon completion, a success message will be displayed.

If compiling fails, an error message will be displayed. Perform troubleshooting (common suspect is the Makefile option flags). Before attempting to compile again, remove any previously compiled files by running:

make clean

Placing AT Programs on PATH
#

The AT programs can now be run, but as installed, they must be called in Terminal by specifying their full path, e.g., a generic Kraken call would look like:

/Users/<username>/at/kraken/kraken.exe envfile.env

This is rather tedious and can be circumvented in a few ways such that the program can be run by simply running:

kraken.exe envfile.env

Create Symbolic Links #

Symbolic links, also known as aliases on Mac (shortcuts on Windows), can be placed in one of the system folders that is included in the PATH environment variable. One such place to store these symbolic links is in a directory meant for user-installed programs:

/usr/local/bin/

The following can be saved and run as a shell script, or run line by line within Terminal. In the first line, replace <path to AT> with where your AT installation is currently located. Recall in the previous step that this was at /users/<username>/at

AT_PATH=<path to AT> # <-- Set path to your AT folder here
ln -s $AT_PATH/Kraken/bounce.exe /usr/local/bin/bounce.exe
ln -s $AT_PATH/Kraken/kraken.exe /usr/local/bin/kraken.exe
ln -s $AT_PATH/Kraken/krakenc.exe /usr/local/bin/krakenc.exe
ln -s $AT_PATH/KrakenField/field.exe /usr/local/bin/field.exe
ln -s $AT_PATH/KrakenField/field3d.exe /usr/local/bin/field3d.exe
ln -s $AT_PATH/Bellhop/bellhop.exe /usr/local/bin/bellhop.exe
ln -s $AT_PATH/Bellhop/bellhop3d.exe /usr/local/bin/bellhop3d.exe
ln -s $AT_PATH/Scooter/scooter.exe /usr/local/bin/scooter.exe
ln -s $AT_PATH/Scooter/sparc.exe /usr/local/bin/sparc.exe

Once complete, open a new Terminal session or reload the current one by running:

source ~/.zshrc

Check that the AT programs are on PATH:

which kraken.exe

These commands should return /usr/local/bin/kraken.exe

Add the AT directory to PATH
#

The AT sub-directories can be added to PATH directly in the .zshrc or .zprofile by adding the following lines:

AT_PATH=<path to AT>
export PATH="$AT_PATH/Kraken:\
$AT_PATH/KrakenField:\
$AT_PATH/Bellhop:\
$AT_PATH/Scooter:\
$PATH"