Ctrl+K

Development Environment

Development Environment#

Warning

These instructions have some inaccuracies on Windows.

Get the code and Mamba#

Clone the repo#

Fork and clone the repository in your preferred manner. Refer to GitHub documentation for how to do so.

Install micromamba#

Setting the development environment requires conda, mamba, or micromamba. Since some commands are automated with micromamba, and to avoid any runtime linking issue, it is best to work with micromamba.

Refer to the installation page for how to install micromamba or mamba.

Develop using Taskfile#

Many development operations can be automated and chained using Taskfile. You can follow the installation instructions there, or install it via conda-forge.

micromamba create -n mamba -c conda-forge go-task
micromamba activate -n mamba

If you’re running on an OSX machine, you’ll need to install GNU coreutils as well for the Taskfile to work.

micromamba create -n mamba -c conda-forge go-task coreutils
micromamba activate -n mamba

Running commands#

Tasks and their descriptions can be queried with:

task --list-all

At the time of writing, the following tasks are available:

task: Available tasks for this project:
* build:                 Build all (or some) CMake targets.
* build-docs:            Build the documentation.
* clean:                 Remove files generated by Task commands.
* configure:             Configure the CMake build.
* create-dev-env:        Create a local development mamba environment with all needed dependencies
* create-test-env:       Create a local test environment with as a copy of the dev environment.
* install-cpp:           Install C++ targets into the test environment.
* install-py:            Install the ``libmambapy`` Python package inside the test environment.
* micromamba:            Run the development ``micromamba``.
* pre-commit:            Run linters and code formatters.
* reconfigure:           Erase all CMake cache entries and run confiiguration again.
* stubgen:               Regenerate libmambapy typing stubs.
* test-docs:             Test the documentation, for instance for dead links.
* test-libmamba:         Run ``libmamba`` C++ based tests.
* test-libmambapy:       Run ``libmambapy`` Python based unit tests.
* test-micromamba:       Run ``micromamba`` integration tests.

For instance to run libmamba tests, execute:

task test-libmamba

Tasks have dependencies expressed between them. For instance, when running a tests task, compilation and installation steps will be run automatically as needed.

Extra command line arguments can also be passed to the underlying command:

task test-libmamba -- --test-suite='util::*'

Further documentation about a specific task can be queried with the --summary option:

task --summary test-libmamba

A dry-run mode can also be used to know what commands would be run, without actually running them:

task --dry-run test-libmamba

Development tools#

With any command, task will run create-dev-env with all development dependencies. This environment can be activated to get development tools such as LSP code completion and lint.

Running commands manually#

Note

Even if not using Taskfile, the file Taskfile.dist.yml can provide insights on useful commands. The CI files in .github/workflow provide an alternative way of developing Mamba.

Install development dependencies#

micromamba create -n mamba -c conda-forge -f dev/environment.yml
micromamba activate -n mamba

Compile libmamba and other artifacts#

libmamba is built using CMake. Typically during development, we build everything dynamically using dependencies from Conda-Forge.

The first step is to configure the build options. A recommended set is already provided as CMake Preset, but feel free to use any variations.

Note

All cmake commands listed below use bash multi-line syntax. On Windows, replace \ trailing character with ^.

cmake -B build/ -G Ninja --preset mamba-unix-shared-debug-dev

Compilation can then be launched with:

cmake --build build/ --parallel

libmamba tests#

The tests for libmamba are written in C++.

./build/libmamba/tests/test_libmamba

micromamba integration tests#

Many micromamba integration tests are written through a pytest Python wrapper. The environment variable TEST_MAMBA_EXE controls which executable is being tested.

export TEST_MAMBA_EXE="${PWD}/build/micromamba/micromamba"
python -m pytest micromamba/tests

libmambapy tests#

To run the libmambapy tests, the Python package needs to be properly installed first.

Warning

This needs to be done every time libmamba changes.

cmake --install build/ --prefix "${CONDA_PREFIX}"

Then the Python bindings can be installed

python -m pip install --no-deps --no-build-isolation libmambapy/

Finally the tests can be run:

python -m pytest libmambapy/tests

Code Formatting#

Code formatting is done using Pre-Commit hooks. Whichever way you decided to install development dependencies, we recommend installing Pre-Commit hooks with

pre-commit install

Alternatively, the checks can be run manually

pre-commit run --all-files
Contents