mamba/docs/source/developer_zone/dev_environment.rst

=======================
Development Envrionment
=======================

.. warning::

   These instructions have some inaccuracies on Windows.

Get the code and Mamba
======================

Clone the repo
**************

Fork and clone the repository in your prefered 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 :ref:`installation<umamba-install>` page for how to install micromamba or mamba.

Develop using Taskfile
======================

Many development operations can be automated and chained using `Taskfile <https://taskfile.dev/>`_.
You can follow the installation instructions there, or install it via ``conda-forge``.


.. code:: bash

    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.

.. code:: bash

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

Running commands
****************

Tasks and their descriptions can be queried with:

.. code:: bash

    task --list-all

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

.. code::

   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:

.. code:: bash

    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:

.. code:: bash

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

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

.. code:: bash

    task --summary test-libmamba

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

.. code:: bash

    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 <https://microsoft.github.io/language-server-protocol/>`_ 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 develoment dependencies
*******************************

.. code:: bash

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

Compile ``libmmaba`` 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 ``^``.

.. code:: bash

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

Compilation can then be launched with:

.. code:: bash

    cmake --build build/ --parallel

``libmamba`` tests
******************

The tests for libamba are written in C++.

.. code:: bash

    ./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.

.. code:: bash

   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 ``libamamba`` changes.

.. code:: bash

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

Then the Python bindings can be installed

.. code:: bash

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

Finally the tests can be run:

.. code:: bash

    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

.. code:: bash

   pre-commit install

Alternatively, the checks can be run manually

.. code:: bash

   pre-commit run --all-files