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