|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +ITKPythonPackage is a cross-platform build system for creating Python binary wheels for the Insight Toolkit (ITK) — an open-source C++ image analysis library. It builds wheels for ITK itself and for ITK external (remote) modules across Linux, macOS, and Windows (x86_64 and arm64/aarch64). |
| 8 | + |
| 9 | +ITK external modules require pre-built ITK artifacts. These are cached as [ITKPythonBuilds](https://github.com/InsightSoftwareConsortium/ITKPythonBuilds) releases to avoid rebuilding ITK for every module. |
| 10 | + |
| 11 | +## Build System |
| 12 | + |
| 13 | +### Running a build |
| 14 | + |
| 15 | +The primary entry point is `scripts/build_wheels.py`, orchestrated via pixi: |
| 16 | + |
| 17 | +```sh |
| 18 | +pixi run build-itk-wheels |
| 19 | +``` |
| 20 | + |
| 21 | +Or directly: |
| 22 | +```sh |
| 23 | +python scripts/build_wheels.py |
| 24 | +``` |
| 25 | + |
| 26 | +### Environment management |
| 27 | + |
| 28 | +**pixi** (conda-like) manages reproducible build environments defined in `pixi.toml`. Environments are composed per-platform and per-Python-version (e.g., `manylinux228-py310`, `macosx-py311`). |
| 29 | + |
| 30 | +### Key environment variables (GitHub Actions compatible) |
| 31 | + |
| 32 | +- `ITK_PACKAGE_VERSION` — Version string for wheels |
| 33 | +- `ITKPYTHONPACKAGE_TAG` — ITKPythonPackage version/tag to use |
| 34 | +- `ITKPYTHONPACKAGE_ORG` — GitHub org (default: InsightSoftwareConsortium) |
| 35 | +- `ITK_MODULE_PREQ` — Module dependencies (`org/repo@tag:org/repo@tag:...`) |
| 36 | +- `CMAKE_OPTIONS` — Extra CMake flags |
| 37 | +- `MANYLINUX_VERSION` — Manylinux ABI version (_2_28, _2_34, etc.) |
| 38 | +- `MACOSX_DEPLOYMENT_TARGET` — macOS minimum deployment target |
| 39 | + |
| 40 | +### Linting |
| 41 | + |
| 42 | +```sh |
| 43 | +pre-commit run --all-files |
| 44 | +``` |
| 45 | + |
| 46 | +Shell script linting was previously via `.travis.yml`; now uses pre-commit hooks. |
| 47 | + |
| 48 | +## Architecture |
| 49 | + |
| 50 | +### Python build scripts (`scripts/`) |
| 51 | + |
| 52 | +Class hierarchy for platform-specific wheel building: |
| 53 | + |
| 54 | +- **`build_wheels.py`** — Main driver. Detects platform/arch, selects pixi environment, creates platform-specific build instance. |
| 55 | +- **`build_python_instance_base.py`** — Abstract base class defining the shared build pipeline (download, configure, build, package). |
| 56 | +- **`linux_build_python_instance.py`** — Linux: TBB support, `auditwheel` for manylinux compliance. |
| 57 | +- **`macos_build_python_instance.py`** — macOS: `delocate` for dylib relocation. |
| 58 | +- **`windows_build_python_instance.py`** — Windows: `delvewheel` for DLL bundling. |
| 59 | + |
| 60 | +Supporting scripts: |
| 61 | +- **`pyproject_configure.py`** — Generates `pyproject.toml` from `pyproject.toml.in` template with platform-specific substitutions. |
| 62 | +- **`wheel_builder_utils.py`** — Shared utilities (subprocess wrappers, path handling, env parsing). |
| 63 | +- **`cmake_argument_builder.py`** — Builds CMake args for both direct invocation (`-DKEY=VALUE`) and scikit-build-core (`--config-setting=cmake.define.KEY=VALUE`). |
| 64 | +- **`BuildManager.py`** — JSON-based build step tracking for resuming interrupted builds. |
| 65 | + |
| 66 | +### CMake layer (`cmake/`) |
| 67 | + |
| 68 | +- **`ITKPythonPackage_Utils.cmake`** — Utility functions for module dependency resolution, wheel-to-group mapping. |
| 69 | +- **`ITKPythonPackage_BuildWheels.cmake`** — Wheel-specific CMake build configuration. |
| 70 | +- **`ITKPythonPackage_SuperBuild.cmake`** — ITK + dependencies superbuild. |
| 71 | + |
| 72 | +### Wheel targets |
| 73 | + |
| 74 | +Defined in `BuildWheelsSupport/WHEEL_NAMES.txt`: itk-core, itk-numerics, itk-io, itk-filtering, itk-registration, itk-segmentation, itk-meta. |
| 75 | + |
| 76 | +### Build backend |
| 77 | + |
| 78 | +Uses **scikit-build-core**. The `pyproject.toml.in` template is the single source of truth for project metadata. |
| 79 | + |
| 80 | +### Conda/pixi-build integration (`packages/libitk-wrapping/`) |
| 81 | + |
| 82 | +The `libitk-wrapping` package is a rattler-build recipe that produces a conda package of ITK C++ with full Python wrapping artifacts. When installed in a pixi/conda environment, the build system automatically detects it and skips the expensive ITK C++ compilation (steps 01-02), reducing remote module build times from ~1-2 hours to ~15 minutes. |
| 83 | + |
| 84 | +- **`packages/libitk-wrapping/recipe.yaml`** — rattler-build recipe (configurable via `ITK_GIT_URL`/`ITK_GIT_TAG` env vars) |
| 85 | +- **`packages/libitk-wrapping/build-libitk-wrapping.sh`** — Unix build script |
| 86 | +- **`packages/libitk-wrapping/build-libitk-wrapping.bat`** — Windows build script |
| 87 | +- **`conda-forge/`** — Prepared conda-forge staged-recipes submission |
| 88 | + |
| 89 | +Detection is in `build_python_instance_base.py:_detect_conda_itk()` — checks `CONDA_PREFIX` and `PIXI_ENVIRONMENT_DIR` for `lib/cmake/ITK-*/ITKConfig.cmake`. |
| 90 | + |
| 91 | +## Shell script entry points |
| 92 | + |
| 93 | +Legacy shell/PowerShell scripts are preserved for backward compatibility with existing CI workflows: |
| 94 | +- `scripts/dockcross-manylinux-download-cache-and-build-module-wheels.sh` (Linux) |
| 95 | +- `scripts/macpython-download-cache-and-build-module-wheels.sh` (macOS) |
| 96 | +- `scripts/windows-download-cache-and-build-module-wheels.ps1` (Windows) |
| 97 | + |
| 98 | +These scripts delegate to the Python build system internally and will skip tarball downloads when a conda-installed ITK is detected. |
| 99 | + |
| 100 | +### Commit message convention |
| 101 | + |
| 102 | +This project follows the ITK commit message convention: `PREFIX: Description`. Valid prefixes: `BUG:`, `COMP:`, `DOC:`, `ENH:`, `PERF:`, `STYLE:`. Enforced via commitizen (configured in `pyproject.toml`, validated by the `commit-msg` pre-commit hook). |
| 103 | + |
| 104 | +## Related repositories |
| 105 | + |
| 106 | +- [ITK](https://github.com/InsightSoftwareConsortium/ITK) — The C++ toolkit itself |
| 107 | +- [ITKPythonBuilds](https://github.com/InsightSoftwareConsortium/ITKPythonBuilds) — Cached ITK build artifacts |
| 108 | +- [ITKRemoteModuleBuildTestPackageAction](https://github.com/InsightSoftwareConsortium/ITKRemoteModuleBuildTestPackageAction) — GitHub Actions reusable workflows for building/testing/packaging |
0 commit comments