Setup pixi (#170)

* wip setup pixi project

* wip pixi setup: python dependencies and tasks

* pixi setup add doc feature

* wip pixi setup: add dev tasks

* setup pixi: more tweaks

* add mypy pixi task

* add pixi lock file

* ci tests: bump min macos version

* add ci workflow: test cpp with pixi (linux)

* ci: fix pixi version

* ci: pixi fix task name

* ci: pixi fix task environment

* ci: pixi fix task environment take 2

* doc: add pixi specific details

* nit

Author: benbovy

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
           - {os: windows-latest, label: "windows"}
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up GCC (Linux)
         uses: egor-tensin/setup-gcc@v1
@@ -67,7 +67,7 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup micromamba
         uses: mamba-org/setup-micromamba@v1
@@ -91,7 +91,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Python
         uses: actions/setup-python@v5
@@ -106,3 +106,17 @@ jobs:
         run: |
           python -m pip install numpy==1.26.4 pytest
           pytest python/fastscapelib/tests -vv --color=yes
+
+  test_cpp_with_pixi:
+    name: Test C++ with pixi
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - uses: prefix-dev/[email protected]
+        with:
+          pixi-version: v0.40.1
+          cache: true
+
+      - run: pixi run  --environment cpp run-tests

doc/source/build_options.md

@@ -48,6 +48,75 @@ default). See below for more explanations.
     it to build fastscapelib (useful for testing)
 ```
 
+(pixi-configuration)=
+
+## Pixi Configuration
+
+Fastscapelib provides everything needed to manage its dependencies and run
+common tasks via [pixi].
+
+If you have `pixi` installed, you can install a development environment for your
+platform simply by executing the following command from Fastscapelib's project
+root directory:
+
+```
+$ pixi install --environment dev
+```
+
+The following environments are defined:
+
+```{list-table}
+:widths: 25 75
+
+* - ``build``
+  - All tools and dependencies needed to build and install Fastscapelib's
+    core (C++) library.
+* - ``cpp``
+  - For running C++ tests and benchmarks.
+* - ``python``
+  - All tools and dependencies needed to build Fastscapelib's Python bindings
+* - ``doc``
+  - For building Fastscapelib's documentation.
+* - ``dev``
+  - For contributing to Fastscapelib's code (including test and lint tools).
+```
+
+Those environments are used to run Fastscapelib's pixi tasks, e.g.,
+
+```
+$ pixi run build-python
+```
+
+Here is a subset of the available tasks:
+
+```{list-table}
+:widths: 25 75
+
+* - ``run-tests``
+  - Run the C++ tests (build them if needed).
+* - ``run-benchmarks``
+  - Run the benchmarks (build them if needed).
+* - ``build-python``
+  - Build the Python bindings (note the python bindings are built and installed
+    in the pixi environments during the `pixi install` steps)
+* - ``run-tests-python``
+  - Run the Python bindings tests.
+* - ``run-mypy``
+  - Run the Python static type checker.
+* - ``build-doc``
+  - Build the documentation.
+* - ``pre-commit-install``
+  - Run `pre-commit install` (a set of git hooks that will automatically
+    check and format the source code prior to each commit)
+* - ``update-compile-commands``
+  - Create of update the compile commands database (useful for C++ LSP
+    servers)
+```
+
+For more details, check the [pixi] documentation. The full pixi configuration
+for Fastscapelib can be found in the `pixi.toml` file located in the project
+root directory.
+
 (run-cpp-tests)=
 
 ## Build and Run the C++ Tests
@@ -139,4 +208,5 @@ $ build/benchmarks/./benchmark_fastscapelib
 
 [google-benchmark]: https://github.com/google/benchmark
 [google-test]: https://github.com/google/googletest
+[pixi]: https://pixi.sh
 [pytest]: https://docs.pytest.org/

doc/source/contributing.md

@@ -85,6 +85,11 @@ We strongly recommend installing all the dependencies and development tools in a
 new [conda](https://conda.io/docs/) environment created specifically for this
 project.
 
+:::{note}
+If you are using [pixi], setting a development environment is easy! See
+{ref}`pixi-configuration`.
+:::
+
 You can create a new conda environment with all the dependencies needed for both
 C++ and Python development by running the following command from the
 repository's root directory:
@@ -259,3 +264,5 @@ following tasks are run automatically using GitHub Actions:
 - run pre-commit to check for code formatting inconsistencies
 - run mypy for checking Python type hints
 - build the documentation on readthedocs
+
+[pixi]: https://pixi.sh

doc/source/install.md

@@ -93,7 +93,8 @@ in a (CMake) project.
 
 Fastscapelib [conda] packages are available for all stable versions via the
 conda-forge channel. You can install Fastscapelib's C++ headers and all the
-dependencies using the following command (alternatively you can use [mamba]):
+dependencies using the following command (alternatively you can use [mamba] or
+[pixi]):
 
 ```bash
 $ conda install fastscapelib -c conda-forge
@@ -197,6 +198,7 @@ See [scikit-build-core]'s documentation for more available options.
 [numpy]: https://numpy.org
 [pip]: https://pip.pypa.io
 [pybind11]: https://pybind11.readthedocs.io
+[pixi]: https://pixi.sh
 [xtensor]: https://xtensor.readthedocs.io
 [xtensor-python]: https://xtensor-python.readthedocs.io
 [scikit-build-core]: https://scikit-build-core.readthedocs.io