Setup On macOS¶
These instruction outline how to install Basilisk (BSK) on a clean version of macOS. Basilisk requires the use of Python 3. Don’t use the Python 2 system that comes with macOS.
Developer Software Tools¶
In order to run Basilisk on macOS, the following software is necessary:
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
(Optional) Get the SourceTree application to be able to pull and manage a copy of Basilisk
(Optional) Get the PyCharm application to be able to edit python source files
Install Python 3¶
To install Python 3 on macOS there are two common options:
(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.
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.
Install HomeBrew Support Packages¶
Install HomeBrew using a Terminal window and pasting the install script from the HomeBrew web site.
The new SWIG version 4 is compatible with Basilisk. Install the SWIG software package using:
$ brew install swig
If you want to install the HomeBrew version of
cmake, you can do so with:
$ brew install cmake $ brew link cmake
You need at least version 3.14 or higher.
Setting up the Python Environment¶
The following instructions recommend installing all the required python packages in the user
~/Library/Python folder. This has the benefit that no
sudo command is required to install and run Basilisk, and the user Python folder can readily be replaced if needed. If you are familiar with python you can install in other locations as well.
If you wish to use the HomeBrew version of python, or generally have multiple copies of python installed on your system, configure the CMake Python paths as described in Using a Custom Python Installation after following these instructions.
We suggest you remove any other python packages (such as Anaconda), or change the path in your terminal shell if you really want to keep it.
In the following instructions, be sure to follow the sequence of tasks as outlined below.
PATH Environment Variable¶
As this installation will install all required Python packages in the
user home directory
Library/Python folder, the
must be setup within the terminal environment.
Open a terminal window
To open these system files in TextEdit.app for easy editing, you can use the shell
opencommand in steps 3 through 6 below
If using a zsh shell, then
$ open .zshrc
Add the line:
If using a Bash shell, then
$ open ~/.bash_profile
Add the line:
Save and close the file
Open a new terminal window for the path to take effect
Installing required python support packages¶
Basilisk uses conan for package managing. In order to do so, users must install conan:
$ pip3 install --user conan
The conan repositories information is automatically setup by
conanversion 1.25.x has issues on macOS where it doesn’t properly link system frameworks. Stick with 1.24.x for now.
If you are upgrading from a version of Basilisk prior to 1.8.0, be sure to delete the
.conanfolder in your home directory to create a clean copy compatible with the current build system.
The following python packages are the minimum required packages for Basilisk. They are installed and checked for the correction version in the steps below.
Optional Packages: The above directions install the Basilisk base software. There are a series of optional packages that enhance this capability, including
pytestto run an automated test suite of unit and integrated tests.
Build Project Process via Terminal¶
When all the prerequisite installations are complete, the project can be built as follows.
conanfile.pywill setup and configure the Basilisk build. For a basic installation, from the root Basilisk folder use:
For other configure and build options, see Building the Software Framework. This creates the Xcode project in
Note that the default configuration is building for Release. When you open the project in XCode, note that you need to build for profiling. Otherwise you get errors about not being able to find appropriate conan installed libraries.
python3 conanfile.pyprocess will verify that the minimum required Basilisk python packages are installed, and that the version is correct. If not, the user is prompted to install the package with
pip3in the system or user folder.
If you wish to use the another version of python 3 configure the Python paths in Using a Custom Python Installation
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:
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.
Open the Xcode project file inside
dist3. This is
To test your setup you can run one of the Example Scripts:
For example, in the terminal window, make
basilisk/src/examples/the current directory.
Run one of the tutorial scenarios, such as:
$ python3 scenarioBasicOrbit.py
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.
Q : Permission denied when using brew
A: Add sudo to the start of the command. If you do not have superuser access, get superuser access.
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 FAQ - Frequency Asked Questions.