Skip to content

Commit

Permalink
DOC: Document development with Pixi
Browse files Browse the repository at this point in the history
Pixi is not envisioned as the only way to develop ITK, but an easy and
reproducible way to set up a local development environment.

Provide an overview on how to install pixi, run ITK tests, and perform
more specific local development.
  • Loading branch information
thewtex committed Oct 24, 2024
1 parent e2eef2d commit 1b75686
Show file tree
Hide file tree
Showing 3 changed files with 95 additions and 3 deletions.
83 changes: 83 additions & 0 deletions Documentation/docs/contributing/build_test_itk.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Build and test ITK

The [CMake] build system was initially created to support development of ITK; ITK is built following standard CMake practices.

ITK's tests are defined with CTest, and the tests can be executed via `ctest`.

## Pixi

An easy and reproducible way to build and test ITK for development is via [Pixi]. Pixi will provide locally-scoped build tools such as toolchains, `cmake`, `ninja`, and `python`.

First, install `pixi`,

::::{tab-set}

:::{tab-item} Linux & macOS
```shell
curl -fsSL https://pixi.sh/install.sh | bash
```
:::

:::{tab-item} Windows
`PowerShell`:
```powershell
iwr -useb https://pixi.sh/install.ps1 | iex
```
`winget`:
```
winget install prefix-dev.pixi
```
:::

::::

or use [another pixi installation option].

You might need to restart your terminal or source your shell for the changes to take effect.

ITK's Pixi configuration uses the [conda-forge compiler] and the [Ninja] CMake generator.

### Test C++

To configure, build, and run ITK's C++ tests,

```shell
# Change to the ITK source directory
cd src/ITK

pixi run test
```

### Test Python

To configure, build, and run ITK's Python bindings and run the Python and C++ tests,

```shell
# Change to the ITK source directory
cd src/ITK

pixi run test-python
```

### Further testing and development

Additional pixi tasks to run specific steps of the `configure`, `build`, `test` development process or create builds with other [CMake build types] are listed with

```shell
pixi task list
```

To start up a shell environment with all build dependencies:

```shell
pixi shell
```

Once in the pixi shell, `cmake`, `ninja`, `ctest`, etc can be executed in the local `build/` directory containing the build to perform targeted development.

[another pixi installation option]: https://pixi.sh/latest/#installer-script-options
[CMake]: https://cmake.org/
[CMake build types]: https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html
[conda-forge compiler]: https://anaconda.org/conda-forge/cxx-compiler
[Ninja]: https://ninja-build.org/
[Pixi]: https://pixi.sh/
13 changes: 11 additions & 2 deletions Documentation/docs/contributing/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,16 @@ the [`setup-git-aliases`] script for general Git tasks in ITK.
Visit the *Pro Git: Setup* resource in [Git Help] for further
information on setting up your local Git environment.

(build)=
Local Build and Testing
-----------------------

See our guide on how to [build and test ITK] to make and test your change
locally.

(workflow)=
Workflow
--------
Git Workflow
------------

ITK development uses a branchy workflow based on topic branches.
This corresponds to the *Fork & Pull Model* mentioned in the
Expand Down Expand Up @@ -387,6 +394,7 @@ Actual releases have tags named by the release version number.
:maxdepth: 3
:caption: 📖 More Information
build_test_itk.md
ITK Software Guide, Book 1, Part III: Development Guidelines <https://itk.org/ItkSoftwareGuide.pdf>
git_help.md
GitHub flow guide <https://guides.github.com/introduction/flow/index.html>
Expand All @@ -405,6 +413,7 @@ python_packaging.md
[ITK Git Cheatsheet]: ./GitCheatSheet.pdf
[download instructions]: ../download.md
[Updating Third Party]: ./updating_third_party.md
[build and test ITK]: ./build_test_itk.md

[`SetupForDevelopment.sh`]: https://github.com/InsightSoftwareConsortium/ITK/blob/master/Utilities/SetupForDevelopment.sh
[`setup-git-aliases`]: https://github.com/InsightSoftwareConsortium/ITK/blob/master/Utilities/GitSetup/setup-git-aliases
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ outputs = ["build-debug/CMakeFiles/"]

[tool.pixi.feature.python.tasks.build-debug-python]
cmd = "cmake --build build-debug-python"
description = "Build ITK - Debug"
description = "Build ITK Python - Debug"
outputs = ["build-debug/lib/**"]
depends-on = ["configure-debug-python"]

Expand Down

0 comments on commit 1b75686

Please sign in to comment.