mirror of https://github.com/mamba-org/mamba.git
Simplify and correct development documention (#2975)
* Use a single file for contributing guidelines * Add doc builds to taskfile * Fix sphinx warnings * Simplify development doc * Document Taskfile * Update dev_environment.rst Co-authored-by: Johan Mabille <johan.mabille@gmail.com> * Update dev_environment.rst Co-authored-by: Johan Mabille <johan.mabille@gmail.com> * Update dev_environment.rst Co-authored-by: Johan Mabille <johan.mabille@gmail.com> * Update dev_environment.rst Co-authored-by: Johan Mabille <johan.mabille@gmail.com> * Update dev_environment.rst Co-authored-by: Johan Mabille <johan.mabille@gmail.com> * Update dev_environment.rst Co-authored-by: Johan Mabille <johan.mabille@gmail.com> * Update dev_environment.rst Co-authored-by: Johan Mabille <johan.mabille@gmail.com> * Add test-docs task --------- Co-authored-by: Johan Mabille <johan.mabille@gmail.com>
This commit is contained in:
Antoine Prouvost
GitHub
parent
e6967058a9
commit
09cbb34e54
|
|
@ -1,13 +1,15 @@
|
|||
# Contributing
|
||||
==============
|
||||
Contributing
|
||||
==============
|
||||
|
||||
When contributing to this repository, it is always a good idea to first
|
||||
discuss the change you wish to make via issue, email, or any other method with
|
||||
the owners of this repository before making a change.
|
||||
|
||||
We welcome all kinds of contribution -- code or non-code -- and value them
|
||||
highly. We pledge to treat everyone's contribution fairly and with respect and
|
||||
highly. We pledge to treat everyones contribution fairly and with respect and
|
||||
we are here to help awesome pull requests over the finish line.
|
||||
|
||||
Please note we have a code of conduct, and follow it in all your interactions with the project.
|
||||
|
||||
We follow the [NumFOCUS code of conduct](https://numfocus.org/code-of-conduct).
|
||||
We follow the `NumFOCUS code of conduct <https://numfocus.org/code-of-conduct>`_.
|
||||
|
|
@ -10,6 +10,7 @@ vars:
|
|||
CMAKE_BUILD_DIR: '{{.BUILD_DIR}}/cmake'
|
||||
CMAKE_PRESET: 'mamba-unix-shared-debug-dev'
|
||||
CACHE_DIR: '{{.BUILD_DIR}}/pkgs'
|
||||
DOCS_DIR: '{{.BUILD_DIR}}/docs'
|
||||
CPU_PERCENTAGE: 75
|
||||
CPU_TOTAL:
|
||||
sh: >-
|
||||
|
|
@ -48,11 +49,20 @@ tasks:
|
|||
- '{{.prefix}}/conda-meta/**/*'
|
||||
|
||||
create-dev-env:
|
||||
summary: 'Create a local development mamba environment with all needed dependencies'
|
||||
desc: Create a local development mamba environment with all needed dependencies
|
||||
summary: |
|
||||
Create development Conda environment with dependencies and development packages used to build
|
||||
Mamba. Many tasks are automatically run inside this environment.
|
||||
The environment is located at "{{.DEV_ENV_DIR}}" and can also be activated with micromamba to
|
||||
benefit from the executables and LSP tools.
|
||||
cmds: [{task: '_create-env', vars: {prefix: '{{.DEV_ENV_DIR}}'}}]
|
||||
|
||||
create-test-env:
|
||||
summary: 'Copy the development environment'
|
||||
desc: Create a local test environment with as a copy of the dev environment.
|
||||
summary: |
|
||||
Copy the dev environment as a test environment under "{{.TEST_ENV_DIR}}". This environment is
|
||||
used by some task that need to make an actual install of Mamba, ensuring the dev environment
|
||||
is not modified.
|
||||
deps: [create-dev-env]
|
||||
cmds:
|
||||
- task: '_copy-env'
|
||||
|
|
@ -60,12 +70,17 @@ tasks:
|
|||
|
||||
_pre-commit:
|
||||
internal: true
|
||||
summary: 'Run pre-commit hooks inside the development environment'
|
||||
deps: [create-dev-env]
|
||||
cmds:
|
||||
- cmd: '{{.DEV_RUN}} pre-commit run {{.args}}'
|
||||
ignore_error: true
|
||||
pre-commit:
|
||||
desc: Run linters and code formatters.
|
||||
summary: |
|
||||
Run the pre-commit hooks inside the development environment to format and lint the code.
|
||||
It is recommended to install the pre-commit hooks instead using
|
||||
|
||||
pre-commit install
|
||||
cmds: [{task: _pre-commit, vars: {args: '{{.CLI_ARGS | default "--all-files"}}'}}]
|
||||
|
||||
_configure:
|
||||
|
|
@ -84,8 +99,22 @@ tasks:
|
|||
status:
|
||||
- test -f '{{.CMAKE_BUILD_DIR}}/CMakeCache.txt'
|
||||
configure:
|
||||
desc: Configure the CMake build.
|
||||
summary: |
|
||||
CMake makes a one time configuration to detect system properties and find dependencies.
|
||||
This step runs such configuration steps with development options passed in.
|
||||
Extra argument can be passed to CMake using the syntax:
|
||||
|
||||
task configure -- -D SOME_OPTION=True
|
||||
cmds: [{task: _configure, vars: {args: '{{.CLI_ARGS}}'}}]
|
||||
reconfigure:
|
||||
desc: Erase all CMake cache entries and run confiiguration again.
|
||||
summary: |
|
||||
CMake configuration can have some sticky parameters. Use this when in need to start from a
|
||||
clean configuration, for instance when encountering issues with dependencies.
|
||||
Extra argument can be passed to CMake using the syntax:
|
||||
|
||||
task reconfigure -- -D SOME_OPTION=True
|
||||
cmds:
|
||||
- 'rm -rf "{{.CMAKE_BUILD_DIR}}/CMakeCache.txt"'
|
||||
- {task: _configure, vars: {args: '{{.CLI_ARGS}}'}}
|
||||
|
|
@ -101,9 +130,23 @@ tasks:
|
|||
args: '{{.args | default (printf "--parallel %s --target %s" .cpu_count .target)}}'
|
||||
# Again, CMake knows what to rebuild so we always rerun the task
|
||||
build:
|
||||
desc: Build all (or some) CMake targets.
|
||||
summary: |
|
||||
Build all CMake targets, including `micormamba` and `libmambapy`. A single target can be built
|
||||
using:
|
||||
|
||||
task build -- --target micromamba
|
||||
cmds: [{task: '_build', vars: {args: '{{.CLI_ARGS}}'}}]
|
||||
|
||||
micromamba:
|
||||
desc: Run the development `micromamba`.
|
||||
summary: |
|
||||
When developing a feature or tracking down a bug, it can be useful to try it out "for real".
|
||||
This lets you run `micromamba` with the safety of automatic recompile, and disambiguation
|
||||
from a local install of stable `micromamba`.
|
||||
An example run could look like:
|
||||
|
||||
task micromamba -- create -n env -c conda-forge python=3.11
|
||||
deps: [{task: '_build', vars: {target: 'micromamba'}}]
|
||||
cmds:
|
||||
- '"{{.CMAKE_BUILD_DIR}}/micromamba/micromamba" {{.CLI_ARGS}}'
|
||||
|
|
@ -115,6 +158,13 @@ tasks:
|
|||
cmds:
|
||||
- './test_libmamba {{.args}}'
|
||||
test-libmamba:
|
||||
desc: Run `libmamba` C++ based tests.
|
||||
summary: |
|
||||
Run fast C++ tests of libmamba. Running this command will rebuild only `libmamba` and its
|
||||
tests, so compilation error may still happen when building other targets.
|
||||
Test options can be passed as extra command line arguments:
|
||||
|
||||
task test-libmamba -- --test-suite='util::*'
|
||||
cmds: [{task: '_test-libmamba', vars: {args: '{{.CLI_ARGS}}'}}]
|
||||
|
||||
_test-micromamba:
|
||||
|
|
@ -128,9 +178,19 @@ tasks:
|
|||
{{.DEV_RUN}} python -m pytest micromamba/tests/
|
||||
--mamba-pkgs-dir="{{.CACHE_DIR}}" {{.args}}
|
||||
test-micromamba:
|
||||
desc: Run `micromamba` integration tests.
|
||||
summary: |
|
||||
Run slow `micromamba` tests through a Pytest Python framework.
|
||||
Test options can be passed as extra command line arguments:
|
||||
|
||||
task test-micromamba -- -x --failed-first -k 'test_create'
|
||||
cmds: [{task: _test-micromamba, vars: {args: '{{.CLI_ARGS}}'}}]
|
||||
|
||||
install-cpp:
|
||||
desc: Install C++ targets into the test environment.
|
||||
summary: |
|
||||
Installing C++ target is needed to create the Python package but this command rarely needs
|
||||
to be called directly.
|
||||
deps: [_build]
|
||||
cmds:
|
||||
- '{{.DEV_RUN}} cmake --install "{{.CMAKE_BUILD_DIR}}" --prefix "{{.TEST_ENV_DIR}}"'
|
||||
|
|
@ -153,6 +213,10 @@ tasks:
|
|||
cmds: [{task: _test-reposerver, vars: {args: '{{.CLI_ARGS}}'}}]
|
||||
|
||||
install-py:
|
||||
desc: Install the `libmambapy` Python package inside the test environment.
|
||||
summary: |
|
||||
Installing the Python package is required to run `libmambapy` Python tests but this command
|
||||
rarely needs to be called explicitly.
|
||||
deps: [install-cpp]
|
||||
cmds:
|
||||
- >-
|
||||
|
|
@ -166,17 +230,48 @@ tasks:
|
|||
- >-
|
||||
{{.TEST_RUN}} python -m pytest libmambapy/tests/ {{.args}}
|
||||
test-libmambapy:
|
||||
desc: Run `libmambapy` Python based unit tests.
|
||||
summary: |
|
||||
Run the Python unit tests of `libmambapy`. These tests do not test features of `libmamba`
|
||||
but rather that the bindings code runs without errors.
|
||||
Test options can be passed as extra command line arguments:
|
||||
|
||||
task test-libmambapy -- -x --failed-first -k 'specs'
|
||||
cmds: [{task: _test-libmambapy, vars: {args: '{{.CLI_ARGS}}'}}]
|
||||
|
||||
stubgen:
|
||||
desc: Regenerate libmambapy typing stubs.
|
||||
summary: |
|
||||
Regenerate the stub `*.pyi` stubs files providing Python typing information.
|
||||
If this command creates any changes, the modifications needs to be commited.
|
||||
deps: [install-py]
|
||||
cmds:
|
||||
- '{{.TEST_RUN}} python -m pybind11_stubgen -o "{{.BUILD_DIR}}/stubs" libmambapy.core.bindings'
|
||||
- cp "{{.BUILD_DIR}}/stubs/libmambapy/core/bindings-stubs/__init__.pyi" libmambapy/src/libmambapy/__init__.pyi
|
||||
- '{{.DEV_RUN}} pre-commit run --files libmambapy/src/libmambapy/__init__.pyi'
|
||||
|
||||
clean: 'rm -rf {{.BUILD_DIR}}'
|
||||
build-docs:
|
||||
desc: Build the documentation.
|
||||
summary: |
|
||||
Build Mamba documentation using Sphinx.
|
||||
deps: [create-dev-env]
|
||||
cmds:
|
||||
- '{{.DEV_RUN}} python -m sphinx -b html docs/source {{.DOCS_DIR}}'
|
||||
|
||||
clean-ci-caches: >-
|
||||
gh api 'repos/{owner}/{repo}/actions/caches' --paginate --jq '.actions_caches[].id'
|
||||
| xargs -I'{}' gh api -X DELETE 'repos/{owner}/{repo}/actions/caches/{}'
|
||||
test-docs:
|
||||
desc: Test the documentation, for instance for dead links.
|
||||
summary: |
|
||||
Run documentation tests, checking for dead links.
|
||||
deps: [create-dev-env]
|
||||
cmds:
|
||||
- '{{.DEV_RUN}} python -m sphinx -W -b linkcheck docs/source {{.DOCS_DIR}}'
|
||||
|
||||
clean:
|
||||
desc: Remove files generated by Task commands.
|
||||
summary: |
|
||||
Remove files generated by Task commnds. Some files and folder generated by tools may still
|
||||
remain. To entirely clean the repository, run:
|
||||
|
||||
git clean -xdn
|
||||
cmds:
|
||||
- rm -rf {{.BUILD_DIR}}'
|
||||
|
|
|
|||
|
|
@ -47,3 +47,7 @@ dependencies:
|
|||
- pybind11
|
||||
# dev dependencies
|
||||
- pre-commit
|
||||
# Documentation dependencies
|
||||
- sphinx
|
||||
- sphinx-book-theme
|
||||
- myst-parser
|
||||
|
|
|
|||
|
|
@ -1,294 +0,0 @@
|
|||
=============
|
||||
Build locally
|
||||
=============
|
||||
|
||||
Local development environment
|
||||
=============================
|
||||
|
||||
Clone the repo
|
||||
**************
|
||||
|
||||
Start by cloning the repo:
|
||||
|
||||
.. code::
|
||||
|
||||
git clone https://github.com/mamba-org/mamba.git
|
||||
|
||||
Then move to the newly created directory:
|
||||
|
||||
.. code::
|
||||
|
||||
cd mamba
|
||||
|
||||
Install dev requirements
|
||||
************************
|
||||
|
||||
| Make sure you have Mamba's development requirements installed in your environment.
|
||||
| To do so, you can use your existing ``mamba`` or ``micromamba`` installation:
|
||||
|
||||
.. code::
|
||||
|
||||
mamba env update --name <env_name> --file ./<project>/environment-dev.yml
|
||||
|
||||
.. code::
|
||||
|
||||
micromamba install --name <env_name> --file ./<project>/environment-dev.yml
|
||||
|
||||
Pick the correct environment spec file depending on the project you want to build.
|
||||
|
||||
If you don't have an existing env, refer to the :ref:`installation<installation>` page.
|
||||
|
||||
The different parts of this repository are sub-projects, all relying (totally or partially) on ``cmake`` configuration.
|
||||
|
||||
.. note::
|
||||
All ``cmake`` commands listed below use ``bash`` multi-line syntax.
|
||||
On Windows, replace ``\`` trailing character with ``^``.
|
||||
|
||||
.. note::
|
||||
Feel free to use your favorite generator: ``make``, ``ninja``, etc.
|
||||
|
||||
|
||||
Build ``libmamba``
|
||||
==================
|
||||
|
||||
``libmamba`` build is enabled using ``BUILD_LIBMAMBA`` ``cmake`` option.
|
||||
|
||||
Shared library
|
||||
**************
|
||||
|
||||
``BUILD_SHARED`` option needs to be activated:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_LIBMAMBA=ON \
|
||||
-DBUILD_SHARED=ON
|
||||
cmake --build build/
|
||||
|
||||
.. note::
|
||||
``libmamba`` ``cmake`` target represents the shared library
|
||||
|
||||
Static library
|
||||
**************
|
||||
|
||||
``BUILD_STATIC`` option needs to be activated:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_LIBMAMBA=ON \
|
||||
-DBUILD_STATIC=ON
|
||||
cmake --build build/
|
||||
|
||||
.. note::
|
||||
``libmamba-static`` ``cmake`` target represents the static library with static dependencies linkage
|
||||
|
||||
.. note::
|
||||
The ``libmamba`` static library does not embed the dependencies but the ``cmake`` target will expose those dependencies to any executable linking on it
|
||||
|
||||
.. note::
|
||||
The ``libmamba`` static lib still has few symbols required from system shared libraries (``glibc`` for instance)
|
||||
|
||||
.. warning::
|
||||
This version of the library has a small difference versus the shared one, on the way the SSL backend of cURL is set
|
||||
See `libmamba/src/core/fetch.cpp` for more information
|
||||
|
||||
Tests
|
||||
*****
|
||||
|
||||
| C++ tests require ``libmamba`` to be built.
|
||||
| To compile the ``gtest``-based C++ test suite, run:
|
||||
|
||||
.. code::
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_LIBMAMBA=ON \
|
||||
-DBUILD_SHARED=ON \
|
||||
-DBUILD_LIBMAMBA_TESTS=ON
|
||||
cmake --build build/
|
||||
|
||||
You should now be able to run:
|
||||
|
||||
.. code::
|
||||
|
||||
./build/libmamba/tests/test_libmamba
|
||||
|
||||
Alternatively you can use:
|
||||
|
||||
.. code::
|
||||
|
||||
cmake --build build/ --target test
|
||||
|
||||
.. note::
|
||||
If you want to run specific or a subset of tests, you can use ``GTEST_FILTER`` environment variable or the ``--gtest_filter`` flag.
|
||||
|
||||
Build ``libmambapy``
|
||||
====================
|
||||
|
||||
The Python bindings of ``libmamba``, ``libmambapy`` can be built by using the ``BUILD_LIBMAMBAPY`` ``cmake`` option.
|
||||
|
||||
You can either rely on ``libmamba`` package already installed in your environment and run:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_LIBMAMBAPY=ON
|
||||
cmake --build build/
|
||||
|
||||
or rebuild ``libmamba`` at the same time:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_LIBMAMBA=ON \
|
||||
-DBUILD_SHARED=ON \
|
||||
-DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX \
|
||||
-DCMAKE_PREFIX_PATH=$CONDA_PREFIX \
|
||||
-DBUILD_LIBMAMBAPY=ON
|
||||
cmake --build build/
|
||||
|
||||
.. note::
|
||||
When rebuilding ``libmamba``, you also need to install the library in a path it will be found.
|
||||
Use for that the ``CMAKE_INSTALL_PREFIX`` ``cmake`` option to point your current development environment, and ``CMAKE_PREFIX_PATH`` ``cmake`` option to specify the installation prefixes to be searched:
|
||||
|
||||
- ``-DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX`` [unix]
|
||||
- ``-DCMAKE_PREFIX_PATH=$CONDA_PREFIX`` [unix]
|
||||
- ``-DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX\\Library`` [win]
|
||||
- ``-DCMAKE_PREFIX_PATH=$CONDA_PREFIX\\Library`` [win]
|
||||
|
||||
You'll need to install the target to have the bindings Python sub-module correctly located, then you can use ``pip`` to install that Python package:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
make install -C build/
|
||||
pip install -e libmambapy/ --no-deps
|
||||
|
||||
.. note::
|
||||
The editable mode ``-e`` provided by ``pip`` allows to use the source directory as the Python package instead of copying sources inside the environment
|
||||
You can then change the code without having to reinstall the package
|
||||
|
||||
.. note::
|
||||
The ``--no-deps`` tells ``pip`` to skip the dependencies installation, since they are already installed (``libmamba`` installed using ``cmake``)
|
||||
|
||||
.. note::
|
||||
``libmambapy`` is dynamically linking against ``libmamba`` (shared) library
|
||||
|
||||
|
||||
Build ``mamba``
|
||||
===============
|
||||
|
||||
You need to build and install ``libmambapy``, which is a dependency of ``mamba``, then install ``mamba``:
|
||||
|
||||
.. code::
|
||||
|
||||
pip install -e ./mamba/ --no-deps
|
||||
|
||||
.. note::
|
||||
Other dependencies are already installed from the `environment-dev.yml` file
|
||||
|
||||
|
||||
Build ``micromamba``
|
||||
====================
|
||||
|
||||
Dynamically linked
|
||||
******************
|
||||
|
||||
To build ``micromamba``, activate the ``BUILD_MICROMAMBA`` flag in ``cmake`` command:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_MICROMAMBA=ON \
|
||||
-DBUILD_SHARED=ON
|
||||
cmake --build build/
|
||||
|
||||
or rebuild ``libmamba`` at the same time:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_LIBMAMBA=ON \
|
||||
-DBUILD_SHARED=ON \
|
||||
-DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX \
|
||||
-DCMAKE_PREFIX_PATH=$CONDA_PREFIX \
|
||||
-DBUILD_MICROMAMBA=ON
|
||||
cmake --build build/
|
||||
|
||||
.. note::
|
||||
If you need to install, use the ``CMAKE_INSTALL_PREFIX`` ``cmake`` option to point your current development environment:
|
||||
|
||||
- ``-DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX`` [unix]
|
||||
- ``-DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX\\Library`` [win]
|
||||
|
||||
You may need to use the ``CMAKE_PREFIX_PATH`` ``cmake`` option as well, to specify the installation prefixes to be searched:
|
||||
|
||||
- ``-DCMAKE_PREFIX_PATH=$CONDA_PREFIX`` [unix]
|
||||
- ``-DCMAKE_PREFIX_PATH=$CONDA_PREFIX\\Library`` [win]
|
||||
|
||||
.. note::
|
||||
``micromamba`` will be dynamically linked against ``libmamba`` and all its dependencies (``libsolv``, ``libarchive``, etc.)
|
||||
|
||||
.. note::
|
||||
``MICROMAMBA_LINKAGE`` default value is ``DYNAMIC``
|
||||
|
||||
Statically linked
|
||||
*****************
|
||||
|
||||
You can also build ``micromamba`` as a fully statically linked executable. For that, you need to install extra requirements:
|
||||
|
||||
.. code::
|
||||
|
||||
micromamba install --name <env_name> --file ./libmamba/environment-static-dev.yml
|
||||
|
||||
It will install the development version of dependencies, including static libraries.
|
||||
|
||||
Now you can run ``cmake``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_MICROMAMBA=ON \
|
||||
-DBUILD_STATIC=ON
|
||||
cmake --build build/
|
||||
|
||||
or with ``libmamba``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cmake -B build/ \
|
||||
-DBUILD_LIBMAMBA=ON \
|
||||
-DBUILD_STATIC=ON \
|
||||
-DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX \
|
||||
-DCMAKE_PREFIX_PATH=$CONDA_PREFIX \
|
||||
-DBUILD_MICROMAMBA=ON
|
||||
cmake --build build/
|
||||
|
||||
.. note::
|
||||
If you decide to build both the static and shared libraries, ``micromamba`` will link with the shared one. To link
|
||||
with the static library, pass the additional build option ``-DMICROMAMBA_LINKAGE=STATIC``
|
||||
|
||||
Tests
|
||||
*****
|
||||
|
||||
In order to run the Python-based test suite, you need to set the following environment variables:
|
||||
|
||||
.. code::
|
||||
|
||||
export TEST_MAMBA_EXE=build/micromamba/micromamba
|
||||
export MAMBA_ROOT_PREFIX=YOUR_MICROMAMBA_ROOT_PREFIX
|
||||
|
||||
Then, you should be able to run the tests:
|
||||
|
||||
.. code::
|
||||
|
||||
pytest micromamba/tests/
|
||||
|
||||
Since running all the tests would take a great amount of time, you could choose to run only a specific test.
|
||||
To launch ``test_env`` for example, you can run:
|
||||
|
||||
.. code::
|
||||
|
||||
pytest micromamba/tests/test_env.py
|
||||
|
||||
.. note::
|
||||
You could also use ``pytest`` ``-k`` option to filter by test full name or substring.
|
||||
|
|
@ -1,15 +1 @@
|
|||
==============
|
||||
Contributing
|
||||
==============
|
||||
|
||||
When contributing to this repository, it is always a good idea to first
|
||||
discuss the change you wish to make via issue, email, or any other method with
|
||||
the owners of this repository before making a change.
|
||||
|
||||
We welcome all kinds of contribution -- code or non-code -- and value them
|
||||
highly. We pledge to treat everyones contribution fairly and with respect and
|
||||
we are here to help awesome pull requests over the finish line.
|
||||
|
||||
Please note we have a code of conduct, and follow it in all your interactions with the project.
|
||||
|
||||
We follow the `NumFOCUS code of conduct <https://numfocus.org/code-of-conduct>`_.
|
||||
.. include:: ../../../CONTRIBUTING.rst
|
||||
|
|
|
|||
|
|
@ -0,0 +1,209 @@
|
|||
=======================
|
||||
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<installation>` 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
|
||||
|
||||
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
|
||||
|
|
@ -62,5 +62,5 @@ You can try Mamba now by visiting the :ref:`installation page<installation>`!
|
|||
:hidden:
|
||||
|
||||
developer_zone/contributing
|
||||
developer_zone/build_locally
|
||||
developer_zone/dev_environment
|
||||
developer_zone/internals
|
||||
|
|
|
|||
|
|
@ -25,7 +25,8 @@ Installing packages other than Conda and Mamba into the ``base`` environment is
|
|||
Using the ``defaults`` channels
|
||||
-------------------------------
|
||||
|
||||
It is **not recommended** to use the `Anaconda default channels <https://docs.anaconda.com/anaconda/user-guide/tasks/using-repositories/>`_:
|
||||
It is **not recommended** to use the
|
||||
`Anaconda default channels <https://docs.anaconda.com/free/anaconda/reference/default-repositories/>`_:
|
||||
|
||||
- ``pkgs/main``
|
||||
- ``pkgs/r`` / ``R``
|
||||
|
|
@ -71,7 +72,8 @@ Or in your :file:`~/.condarc` file:
|
|||
Mixing the ``defaults`` and ``conda-forge`` channels
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The `Anaconda default channels <https://docs.anaconda.com/anaconda/user-guide/tasks/using-repositories/>`_ are **incompatible** with conda-forge.
|
||||
The `Anaconda default channels <https://docs.anaconda.com/free/anaconda/reference/default-repositories/>`_
|
||||
are **incompatible** with conda-forge.
|
||||
|
||||
Using the default and ``conda-forge`` channels at the same time is not supported and will lead to broken environments:
|
||||
|
||||
|
|
@ -113,7 +115,7 @@ Windows API historically supports paths up to 260 characters. While it's now pos
|
|||
|
||||
|
||||
Long paths support has to be activated
|
||||
**************************************
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
source: Robocorp `troubleshooting documentation <https://robocorp.com/docs/troubleshooting/windows-long-path>`_
|
||||
|
||||
|
|
@ -131,7 +133,7 @@ If the problem persists after those steps, try the following:
|
|||
|
||||
|
||||
cmd.exe does not support calls to long prefixes
|
||||
***********************************************
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
While ``cmd.exe`` shell support long paths prefixing for directory operations such as ``dir``, it doesn't allow to call an executable or a batch file located at a long path prefix.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue