installOnWindows.rst

.. toctree::
   :hidden:

Setup On Windows

The following was developed using Windows 11 and Visual Studio Community 17 2022.

Software setup

In order to run Basilisk, the following software will be necessary:

• Python 3.9 to 3.14. Version 3.9 is deprecated and will be removed March 2027.
• pip
• Default compiler is Visual Studios 17 2022
• (Optional) A GiT GUI application such as GitKraken to manage your copy of the Basilisk repository

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

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

Configuration

Strongly recommended to stick with default 64-bit installations. Decide whether target deployment is 32 (win32) or 64 (x64) bit. Which ever chosen you will need the matching python and software for that architecture.

Installing Python

Python is installed using the Windows installer found on the Python website. Make sure to choose the correct installer for your architecture. When stepping through the installer there are two menus options menus. The first is the optional features menu for which all options should be selected.

The second menu is the python advanced options menu where both "Download debugging symbols" and "Download debug binaries (requires VS 2017 or later)" should be selected in order to build Basilisk with a Debug profile. A Debug profile is required to place accurate breakpoints/attach a debugger to C/C++ code.

Installing Rust (Optional)

Native Rust module support is optional. The minimum supported version is listed in :ref:`rustModules`.

1. Download and run the rustup-init.exe installer for your architecture from the official Rust installation page. Accept the default stable MSVC toolchain. The Visual Studio C++ tools already required to build Basilisk also provide the linker required by Rust.

2. Close and reopen Command Prompt 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.

Configuring User Variables

Add Basilisk paths into environment variables using the following steps:

• Right-click on My Computer, Select Properties
• Under the Advanced tab, Select Environment Variables
• Under the User (or System, depending on your setup) Variables panel, Select Path, and Click Edit
  • Add the Basilisk library directory (path2bsk/dist3/Basilisk) to your path. Here, path2bsk is replaced with the actual path to the Basilisk folder. Note, the dist3 folder does not exist to begin with, but is created automatically when configuring Basilisk with python conanfile.py as discussed below.

For more information on how to configure the path Variable on Windows see this help link. Example added path formats:

PYTHON_INCLUDE = C:\Program Files\Python314\include
PYTHON_LIB = C:\Program Files\Python314\libs\python314.lib

Note

If any environment variables have been modified (path2bsk paths), Command Prompt needs to be closed and rebooted (and a machine reboot MAY be needed) for the change to take effect.

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:

   $ python -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:

   $ .venv\Scripts\activate
   

   If the virtual environment is activated, users will see (.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) $ python -m pip install -r requirements.txt -r requirements_dev.txt
   

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

   Warning

   Don't use the conan binary installed from the conan web site. This causes several issues with the current build system.

Build Project Process via Command line

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) $ python conanfile.py
   

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

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

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

   For a new command-line build, the script uses Ninja when it is available and otherwise uses Visual Studio 17 2022. The selected build files are created in dist3 and the project is built. You can also specify the generator directly to select another supported version of Visual Studio. For other configure and build options, including running cmake directly, see :ref:`configureBuild`.

   Note

   The default Window compiler is Visual Studio 17. If you want to compile with VS 16, then use python conanfile.py --generator "Visual Studio 16 2019".

   Note

   To build on Windows you need to run an account with admin privileges.

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

   (.venv) $ python -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 python 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) $ python 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 the IDE directly. Further, if you are developing for Basilisk you often just want to configure the Basilisk Visual Studio project file and not build right away. To change the default behavior, disable the automatic build using:

1. Run this command to create a fresh Visual Studio project without building it:

   python conanfile.py --clean --buildProject False
   

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

2. Open the Visual Studio project file inside dist3. This is basilisk.sln on Windows.

   • The source code should appear and be ready for use

   

   • Change the active config to Release instead of debug for solution properties.
   • Within Visual Studio now go under Build menu/Build Solution to build.