From 7f10862d55f852f8a32a9ae20f3d3221c7e8d170 Mon Sep 17 00:00:00 2001 From: Tim de Jager Date: Mon, 6 Jan 2025 14:58:41 +0100 Subject: [PATCH 1/2] feat: build backend docs --- docs/build/backends.md | 33 +++++++++++++++++++++++++++++++++ mkdocs.yml | 2 ++ 2 files changed, 35 insertions(+) create mode 100644 docs/build/backends.md diff --git a/docs/build/backends.md b/docs/build/backends.md new file mode 100644 index 000000000..d4b81bc06 --- /dev/null +++ b/docs/build/backends.md @@ -0,0 +1,33 @@ +!!! note + This documentation page needs some more details and explanations. + It is currently a work in progress. + +To decouple the building of a conda package from pixi we provide something what are called build backends. +These are essentially executables following a specific protocol that is implemented for both pixi and the build backend. +This also allows for decoupling of the build backend from pixi and it's manifest specification. + +The backends we are currently developing are available in the following [conda channel](https://prefix.dev/channels/pixi-build-backends). +And are being developed in the [pixi-build-backends](https://github.com/prefix-dev/pixi-build-backends) repository. + +### Installation +When looking at the following build-section: + +```toml +[build-system] +build-backend = { name = "pixi-build-cmake", version = "*" } +channels = [ + "https://prefix.dev/pixi-build-backends" + "https://prefix.dev/conda-forge", +] +``` + +This will allow pixi to install desired backends from the `pixi-build-backends` channel, and any requirements from `conda-forge`. Backends are installed into isolated environments, and will be shared across pixi projects. + +### Overriding the Build Backend +Sometimes you want to override the build backend that is used by pixi. Meaning overriding the backend that is specified in the [`[build-system]`](../reference/pixi_manifest.md#the-build-system). We currently have two environment variables that allow for this: + +1. `PIXI_BUILD_BACKEND_OVERRIDE`: This environment variable allows for overriding of one or multiple backends. Use `{name}={path}` to specify a backend name mapped to a path and `,` to separate multiple backends. +For example: `pixi-build-cmake=/path/to/bin,pixi-build-python` will: + 1. override the `pixi-build-cmake` backend with the executable located at `/path/to/bin` + 2. and will use the `pixi-build-python` backend from the `PATH`. +2. `PIXI_BUILD_BACKEND_OVERRIDE_ALL`: If this environment variable is set to *some* value e.g `1` or `true`, it will not install any backends in isolation and will assume that all backends are overridden and available in the `PATH`. This is useful for development purposes. e.g `PIXI_BUILD_BACKEND_OVERRIDE_ALL=1 pixi install` diff --git a/mkdocs.yml b/mkdocs.yml index d7b74588f..388639d5d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -131,6 +131,8 @@ nav: - Building a Python package: build/python.md - Building a C++ Package: build/cpp.md - Multiple Packages in Workspace: build/workspace.md + - Background: + - Build Backends: build/backends.md - Advanced: - Authentication: advanced/authentication.md - Channel Logic: advanced/channel_priority.md From b0123f9a2ce79e48731fab85f7a15b72087e5960 Mon Sep 17 00:00:00 2001 From: Tim de Jager Date: Mon, 6 Jan 2025 16:02:16 +0100 Subject: [PATCH 2/2] feat: more doc improvements --- docs/build/backends.md | 13 ++--------- docs/reference/pixi_manifest.md | 23 +++++-------------- .../pixi_tomls/simple_pixi_build.toml | 5 ++++ mkdocs.yml | 5 ++-- 4 files changed, 15 insertions(+), 31 deletions(-) diff --git a/docs/build/backends.md b/docs/build/backends.md index d4b81bc06..c4a0eb1d4 100644 --- a/docs/build/backends.md +++ b/docs/build/backends.md @@ -1,7 +1,3 @@ -!!! note - This documentation page needs some more details and explanations. - It is currently a work in progress. - To decouple the building of a conda package from pixi we provide something what are called build backends. These are essentially executables following a specific protocol that is implemented for both pixi and the build backend. This also allows for decoupling of the build backend from pixi and it's manifest specification. @@ -13,15 +9,10 @@ And are being developed in the [pixi-build-backends](https://github.com/prefix-d When looking at the following build-section: ```toml -[build-system] -build-backend = { name = "pixi-build-cmake", version = "*" } -channels = [ - "https://prefix.dev/pixi-build-backends" - "https://prefix.dev/conda-forge", -] +--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:build-system" ``` -This will allow pixi to install desired backends from the `pixi-build-backends` channel, and any requirements from `conda-forge`. Backends are installed into isolated environments, and will be shared across pixi projects. +5. This will allow pixi to install desired backends from the `pixi-build-backends` channel, and any requirements from `conda-forge`. Backends are installed into isolated environments, and will be shared across pixi projects. ### Overriding the Build Backend Sometimes you want to override the build backend that is used by pixi. Meaning overriding the backend that is specified in the [`[build-system]`](../reference/pixi_manifest.md#the-build-system). We currently have two environment variables that allow for this: diff --git a/docs/reference/pixi_manifest.md b/docs/reference/pixi_manifest.md index a771cbeef..34bc124e0 100644 --- a/docs/reference/pixi_manifest.md +++ b/docs/reference/pixi_manifest.md @@ -797,12 +797,8 @@ Pixi sometimes introduces new features that are not yet stable, but that we woul An example of a preview feature in the project manifest: -```toml title="pixi.toml" -[workspace] -name = "foo" -channels = [] -platforms = [] -preview = ["pixi-build"] +```toml +--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:preview" ``` Preview features in the documentation will be marked as such on the relevant pages. @@ -823,8 +819,7 @@ The package section is used to define the package that is built by the project. Pixi only allows this table if `preview = ["pixi-build"]` is set in `[workspace]`. ```toml -[package] -version = "1.0.0" +--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:package" ``` ### Host, Build, dependencies @@ -840,8 +835,7 @@ For Python packages, these are the most common dependency types. For compiled languages, these are less common and would basically be dependencies that you do not need when compiling the package but are needed when running it. ```toml -[package.run-dependencies] -rich = "*" +--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:run-dependencies" ``` ### The `build-system` @@ -855,14 +849,9 @@ The build system is a table that can contain the following fields: - `version`: the version of the build backend to use. ```toml -[build-system] # (5)! -build-backend = { name = "pixi-build-python", version = "*" } -channels = [ - "https://prefix.dev/pixi-build-backends", - "https://prefix.dev/conda-forge", -] +--8<-- "docs/source_files/pixi_tomls/simple_pixi_build.toml:build-system" ``` !!! note We are currently not publishing the backends on conda-forge, but will do so in the future. - For now the backends are published at "https://prefix.dev/pixi-build-backends". + For now the backends are published at [conda channel](https://prefix.dev/channels/pixi-build-backends). diff --git a/docs/source_files/pixi_tomls/simple_pixi_build.toml b/docs/source_files/pixi_tomls/simple_pixi_build.toml index 8835972b9..1f911bf29 100644 --- a/docs/source_files/pixi_tomls/simple_pixi_build.toml +++ b/docs/source_files/pixi_tomls/simple_pixi_build.toml @@ -39,4 +39,9 @@ hatchling = "*" simple_python = { path = "." } # --8<-- [end:dependencies] +# --8<-- [start:run-dependencies] +[run-dependencies] +rich = ">=13.9.4,<14" +# --8<-- [end:run-dependencies] + # --8<-- [end:full] diff --git a/mkdocs.yml b/mkdocs.yml index 388639d5d..aad65baef 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -126,13 +126,12 @@ nav: - Pytorch Installation: features/pytorch.md - Building Packages: - Getting started: build/getting_started.md - - Dependency Types: build/dependency_types.md - Tutorials: - Building a Python package: build/python.md - Building a C++ Package: build/cpp.md - Multiple Packages in Workspace: build/workspace.md - - Background: - - Build Backends: build/backends.md + - Dependency Types: build/dependency_types.md + - Build Backends: build/backends.md - Advanced: - Authentication: advanced/authentication.md - Channel Logic: advanced/channel_priority.md