installOnMacOS.rst

.. toctree::
   :hidden:

Setup On macOS

These instruction outline how to install Basilisk (BSK) on a clean version of macOS. Basilisk requires the use of Python 3.9 to 3.14. Version 3.9 is deprecated and will be removed March 2027.

The following python package dependencies are automatically checked and installed in the steps below.

.. literalinclude:: ../../../requirements.txt
   :language: python

Attention!

If you are running a new Apple computer with the M-series ARM64 processor, be sure to download a version of Python that is compatible with M-series processor. The Python.org web site contains Universal binaries for Python 3.9 and onward. Regarding the python packages via pip, the required packages can all be installed readily in a native form using the standard installation instructions below.

Developer Software Tools

In order to run Basilisk on macOS, the following software is necessary:

1. Get the Apple Xcode Developer tool from the App Store

   • After Xcode is installed, start up the program to let it finish installing development components

   • Open a Terminal window to install the command line tools using:

     $ xcode-select --install
     

2. (Optional) Get the SourceTree or GitKraken application to be able to pull and manage a copy of Basilisk

3. (Optional) Get the PyCharm application to be able to edit python source files

4. (Optional, required to build docs locally) Install Doxygen and Graphviz via Homebrew:

   $ brew install doxygen graphviz
   

Optional Rust Toolchain

Native Rust module support is optional. Install the stable Rust toolchain with the official rustup installer. The minimum supported version is listed in :ref:`rustModules`.

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the on-screen instructions, then open a new terminal so that the updated PATH is available. The installer provides the rustc compiler, the Cargo build and dependency manager, and the rustup toolchain manager. Verify the installation with:

$ rustc --version
$ cargo --version

Update an existing stable toolchain with rustup update stable.

Install Python 3

To install Python 3 on macOS there are two common options:

1. (Preferred) Download the installer package from python.org. This will configure your your macOS environment for Python 3 and can readily be upgraded by downloaded a newer installer package.
2. Install python 3 through the HomeBrew package management system. The site has the command line to install homebrew from a terminal window using brew install python3.

Using A Python Virtual Environment

Attention!

We strongly recommend using a python virtual environment while installing basilisk or running basilisk modules. For more info, read this. The virtual environment has the benefit that you won't have conflicts with other versions of Python or python packages that your computer has installed. It lets you install packages specific to this environment and they won't interfere with other python projects you may have. However, you must turn this environment on and off each time you want to use it.

The following steps show how to create, active ad de-activate a virtual environment. The remaining installation steps work regardless if done within a virtual environment or not.

1. In a Terminal window change your current directory to be the Basilisk folder, then create a virtual environment using:

   $ python3 -m venv .venv
   

   This creates a hidden folder inside the Basilisk folder which will store all the python packages and environment information.

2. Activate virtual environment when needing configure, build or run Basilisk:

   $ source .venv/bin/activate
   

   The above step will add (.venv) before the prompt.

3. Deactivate the virtual environment to return to the normal operating system environment:

   (.venv) $ deactivate
   

Installing required python support packages

1. Basilisk uses conan for native package management. Install the Python runtime and build requirements before invoking the build script:

   (.venv) $ python3 -m pip install -r requirements.txt -r requirements_dev.txt
   

   The conan repositories information is automatically setup by conanfile.py.

Build Project Process via Terminal

When all the prerequisite installations are complete, the project can be built as follows.

1. The conanfile.py will setup, configure and run the Basilisk build. For a basic installation, from the root Basilisk folder use:

   (.venv) $ python3 conanfile.py
   

   To include native Rust modules, use the Rust-enabled configuration instead:

   (.venv) $ python3 conanfile.py --rustModules True
   

   See :ref:`rustModules` for details about creating and testing Rust modules.

   For other configure and build options, see :ref:`configureBuild`. For a new command-line build, the script uses Ninja when it is available and otherwise uses Unix Makefiles. The selected build files are created in dist3.

   Note

   If you wish to use the another version of python 3 configure the Python paths in :ref:`customPython`

   Warning

   If you get an error message in cmake saying it can’t find the compiler tools, open a Terminal window and type:

   $ xcode-select -p
   

   This should return:

   /Applications/Xcode.app/Contents/Developer
   

   If instead you get a different director such as /Library/Developer/CommandLineTools, then correct this compiler directory path using:

   sudo xcode-select --reset
   

   Now clear the Cmake cache and try running the configure and build process again.

2. Register the completed dist3 build as an editable Basilisk installation and install the optional example dependencies:

   (.venv) $ python3 -m pip install --no-build-isolation -e ".[examples]"
   

   Use -e . instead of -e ".[examples]" for an installation without the example-only dependencies. This command is required only once after creating the virtual environment. Do not repeat it after subsequent python3 conanfile.py, clean, or incremental native builds.

3. To test your setup you can run one of the :ref:`examples`:

   • For example, in the terminal window, make basilisk/examples/ the current directory.

   • Run one of the tutorial scenarios, such as:

     (.venv) $ python3 scenarioBasicOrbit.py
     

Building with IDE

Conan file will build the project by default. However, this can take longer to compile than building the Basilisk project in Xcode directly. Further, if you are developing for Basilisk you often just want to configure the Basilisk Xcode project file and not build right away. To change the default behavior disable the automatic build using:

1. Create a fresh Xcode project by setting the buildProject argument to False:

   (.venv) $ python3 conanfile.py --clean --buildProject False
   

   The --clean option removes the existing dist3 build before selecting Xcode. It is required when a prior command-line build used Ninja or Unix Makefiles because CMake cannot change the generator of an existing build directory.

2. Open the Xcode project file inside dist3. This is basilisk.xcodeproj on macOS.

   • The source code should appear and be ready for use

     

   • Ensure that the target scheme is set to ALL_BUILD as shown in figure above

   • Within Xcode now go under Product/Build For/Profiling to build for Release.

   Warning

   The default configuration is Release. In Xcode, build for profiling; otherwise, Xcode can select a configuration for which the Conan-installed libraries are unavailable.

FAQs

1. Q: Experiencing problems when trying to change the directory in which to clone the url
   • A: clone it in the default directory, and copy it into the preferred one after it is done cloning.
2. Q : I updated my macOS system to the latest released, and I can no longer run CMake or build with Xcode.
   • A: Do a clean build as described in :ref:`FAQ`.