3.4. Installation for developers¶
Developers of MUSE will need to have the version control tool git installed in their system and be familiar with its usage. The Introduction to Git and GitHub for software development course created by Imperial RSE Team can be a good place to start.
3.4.1. Installing MUSE source code in editable mode¶
Once you have git in your system, clone the MUSE repository with:
git clone https://github.com/SGIModel/MUSE_OS.git
For developing MUSE, it is highly recommended to use virtual environments, so that you have more control on the versions of the dependencies being used, making easy to change them without affecting other tools using Python, or even to have several environments in parallel for different purposes (Eg. new features, bug fixing…). You can either use conda or venv as explained in Creating virtual environments.
Once you have your environment created, activate it and install MUSE within the environment:
cd MUSE_OS
# 1- Create virtual environment
# 2- Activate virtual environment
# 3- Finally, install MUSE in editable mode with:
python -m pip install -e .[dev,doc]
Depending on your system, you might need to add quotation marks around [dev,doc] as in "[dev,doc]". This will install MUSE and all the dependencies required for its development. The downloaded code can be modified and the changes will be automatically reflected in the environment.
3.4.2. Installing pre-commit hooks¶
To ensure the consistency of the code with other developers, install the pre-commit hooks, which will run a series of checks whenever there is a new commit:
python -m pip install pre-commit
pre-commit install
3.4.3. Running tests¶
In the developing phase, MUSE can also be used to run test cases to check that the model would reproduce expected results from a defined set of input data. Tests can be run with the command [pytest](https://docs.pytest.org/en/latest/), from the testing framework of the same name.
Within the MUSE-OS directory, just run:
python -m pytest
3.4.4. Building the documentation¶
The documentation can be built with Sphinx:
python -m sphinx -b html docs docs/build
This command will use pandoc under the hood, which might not be available in your system. If that were the case, install it following the instructions in the official webpage. It will also build the graphs and flow diagrams with graphviz, which also needs to be installed separately from the official webpage.
The main page for the documentation can then be found at docs/build/html/index.html and the file can viewed from any web browser.
3.4.5. Create the standalone version of MUSE¶
We use pyinstaller to create a standalone version of MUSE, a version that bundles together MUSE and all its dependencies (including Python) in a way that can be easily distributed and used in any compatible system without having to install anything. In Standalone MUSE we describe how to get and use this standalone version.
If you want to create such a version yourself during the development process, just run:
pyinstaller muse_dir.spec
This will start the (potentially long) process of collecting all the dependencies and MUSE itself and put them into a dist sub-folder, in binary form.
3.4.6. Configuring VSCode¶
VSCode users will find that the repository is setup with default settings file. Users will still need to choose the virtual environment, or conda environment where to run the code. This will change the .vscode/settings.json file and add a user-specific path to it. Users should try and avoid committing changes to .vscode/settings.json indiscriminately.