Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Setting up your development environment

To develop MUSE2 locally you will need the following components:

  • Git
  • Rust development tools
  • C++ development tools (needed for bindings to the HiGHS solver)

Optional requirements:

You can either install the necessary developer tools locally on your machine manually (a bare metal installation) or use the provided development container. Bare metal installation should generally be preferred if you plan on doing substantial development, as you should get better performance locally (and therefore shorter compile times), as well as making it easier to interact with your local filesystem. Development containers provide a mechanism for installing all the tools you will need (into a Docker container) and are generally used either via Visual Studio Code running locally or GitHub Codespaces, which run on GitHub-provided virtual machines running remotely.

We provide a justfile for some common developer tasks.

Installing tools

Option 1: Bare metal installation

Installing the Rust toolchain

We recommend that developers use rustup to install the Rust toolchain. Follow the instructions on the rustup website.

This project defines the required version of the Rust toolchain in rust-toolchain.toml. The first time you attempt to run cargo (see Building and developing MUSE2), this toolchain should be downloaded and installed automatically by rustup.

Installing C++ tools for HiGHS

The highs-sys crate requires a C++ compiler and CMake to be installed on your system. These may be installed already, but if you encounter errors during the build process for highs-sys (e.g. “Unable to find libclang”), you should follow the instructions in the highs-sys repository.

Option 2: Developing inside a container

If you wish to use the development container locally with Visual Studio Code, you should first install the Dev Containers extension. Note you will also need Docker to be installed locally. For more information, see the documentation.

You can use GitHub Codespaces to develop directly from your web browser. For more information, please see GitHub’s guide. When you first create your Codespace, you will be asked whether you wish to install the recommended extensions and you should choose “yes”.

Downloading the MUSE2 source code

Unless you are developing in a GitHub Codespace (see above), you will need to download the MUSE2 source code to your local machine before you can develop it. Like many projects, MUSE2 is stored in a Git repository hosted on GitHub. Many IDEs, such as Visual Studio Code, provide an interface to clone Git repositories, but you can also use the Git command-line tool (see installation instructions), like so:

git clone https://github.com/EnergySystemsModellingLab/MUSE2

The source code will now be available in a folder named MUSE2.

Pre-Commit hooks

We use pre-commit to automatically run a number of hooks for this repository when a new Git commit is made. You can run pre-commit via our justfile, provided you have uv installed.

You can enable pre-commit for this repository with:

just pre-commit install

Thereafter, a series of checks should be run every time you commit with Git. In addition, the pre-commit hooks are also run as part of the CI pipeline.

Note: you may get errors due to the clippy hook failing. In this case, you may be able to automatically fix them by running cargo clipfix (which we have defined as an alias in .cargo/config.toml).