1.10.2. Initial setup: Mac

Note that you may need administrator privileges on your Mac for the installation steps detailed here.

1.10.2.1. Python

To test whether you already have the required Python version, open a Terminal window and try the following:

python3 --version

If python3 is already set up, you’ll see a version number. If that version is 3.7 or later, you should be ready as far as Python goes; continue to Additional requirements.

If not, recent versions of macOS should print a messsage saying, “xcode-select: No developer tools were found, requesting install.” A dialog box will then pop up that says, “The ‘python3’ command requires the command line developer tools. Would you like to install the tools now?” Press Install and go through the installation process. This will take a while; once it’s done, test by doing python3 --version again. (You may need to open a new Terminal window.) If the printed version number looks good, continue to Additional requirements.

If instead python3 gives “command not found,” or the version is less than 3.7, you might need to install Python; continue to Aliasing python3 to python. Otherwise, continue to Additional requirements.

1.10.2.1.1. Aliasing python3 to python

Try the same command as above, but instead of python3 just do python (no number). If that version is 3.7 or later, you can tell your Mac that when you say python3 you want it to use python:

echo alias python3="$(which python)" >> ~/.bashrc
echo alias python3="$(which python)" >> ~/.zshrc

This will make it so that bash scripts, like what we use to build our docs, know what to do for python3. python3 will also be available in new Terminal sessions if your shell is zsh (the default since macOS 10.15) or bash.

If you were able to do this, you can continue to Additional requirements. If not, continue to the next section.

1.10.2.1.2. Conda

If your python doesn’t exist or is too old, we suggest using Python via Conda. First, check whether you already have Conda installed: Do I already have Conda installed? If not, install Conda (How do I install Conda?), then come back here.

Try this to check the Python version in the base Conda environment:

conda run -n base python3 --version

Repeat with all your Conda environments as needed until you find one that’s Python 3.7 or later. Let’s say your ENVNAME environment works. In that case, just make sure to do conda activate ENVNAME before running the commands in the documentation-building instructions.

1.10.2.2. Additional requirements

1.10.2.2.1. Container software or Conda environment

We recommend building the software in what’s called a container—basically a tiny little operating system with just some apps and utilities needed by the doc-building process. This is nice because, if we change the doc-building process in ways that require new versions of those apps and utilities, that will be completely invisible to you. You won’t need to manually do anything to update your setup to work with the new process; it’ll just happen automatically.

We recommend using the container software Podman, which you can install with Homebrew. (How do I install Homebrew?)

  1. Install Podman with brew install podman.

  2. Set up and start a Podman “virtual machine” with podman machine init --now.

  3. Test your installation by doing podman run --rm hello-world. If it worked, you should see ASCII art of the Podman logo.

You may not be able to install Podman or any other containerization software, so there is an alternative method: a Conda environment.

  1. Install Conda, if needed (see How do I install Conda?).

  2. Follow the instructions for setting up the ctsm_pylib Conda environment in Sect. 1.3.4.

1.10.2.2.2. Git tools

Note: Do this section after handling Python, because the Python installation process might bring the Git tools with it.

To test whether you have the required Git tools already, open a Terminal window and try the following:

git --version
git-lfs --version

If either of those fail with “command not found,” you’ll need to install them. The recommended way is with Homebrew. (How do I install Homebrew?)

  1. Use Homebrew to install Git, if needed.

  2. Use Homebrew to install Git LFS, if needed.

1.10.2.3. Frequently-asked questions

1.10.2.3.1. What kind of chip does my Mac have?

For certain steps in this installation process, you may need to know whether your Mac has an Intel (x86_64) or an Apple Silicon (arm64) chip. If you don’t know, visit Apple’s Mac computers with Apple silicon page for instructions.

1.10.2.3.2. How do I install Homebrew?

  1. Install Homebrew using the instructions at https://brew.sh/. Make sure to follow the instructions during this process for adding Homebrew to your path.

  2. Check your installation by making sure that brew --version doesn’t error.

1.10.2.3.3. Do I already have Conda installed?

You can check whether you have Conda installed like so:

conda env list

If that shows you something like

# conda environments:
#
base           /Users/you/...
another_env    /Users/you/.../...
...

instead of the “command not found” error, then you do have conda installed! (Note that the second column doesn’t really matter.)

1.10.2.3.4. How do I install Conda?

We suggest installing Conda, if needed, via Miniforge:

  1. Download Miniforge and install it. (What kind of chip does my Mac have?) You can also install Miniforge via Homebrew, if you already have that installed. (How do I install Homebrew?)

  2. Activate Conda permanently in your shell by opening a new Terminal window and doing conda init "$(basename $SHELL)".

You should now have conda and an up-to-date version of python3 available, although will need to open another new Terminal window for it to work.