From 69c7504aa61226529fc4bc095be11e9f201e488c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Schr=C3=B6der?= Date: Sun, 5 Oct 2025 16:53:02 +0200 Subject: [PATCH] doc: align formatting in dependency type tables --- doc/stdenv/cross-compilation.chapter.md | 26 ++++++++++++------------- doc/stdenv/stdenv.chapter.md | 16 +++++++-------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/stdenv/cross-compilation.chapter.md b/doc/stdenv/cross-compilation.chapter.md index ca56d8816c3a..26630b78fd73 100644 --- a/doc/stdenv/cross-compilation.chapter.md +++ b/doc/stdenv/cross-compilation.chapter.md @@ -86,7 +86,7 @@ If both the dependency and depending packages aren't compilers or other machine- Finally, if the depending package is a compiler or other machine-code-producing tool, it might need dependencies that run at "emit time". This is for compilers that (regrettably) insist on being built together with their source languages' standard libraries. Assuming build != host != target, a run-time dependency of the standard library cannot be run at the compiler's build time or run time, but only at the run time of code emitted by the compiler. -Putting this all together, that means that we have dependency types of the form "X→ E", which means that the dependency executes on X and emits code for E; each of X and E can be `build`, `host`, or `target`, and E can be `*` to indicate that the dependency is not a compiler-like package. +Putting this all together, that means that we have dependency types of the form `X → E`, which means that the dependency executes on `X` and emits code for `E`; each of `X` and `E` can be `build`, `host`, or `target`, and `E` can be `*` to indicate that the dependency is not a compiler-like package. Dependency types describe the relationships that a package has with each of its transitive dependencies. You could think of attaching one or more dependency types to each of the formal parameters at the top of a package's `.nix` file, as well as to all of *their* formal parameters, and so on. Triples like `(foo, bar, baz)`, on the other hand, are a property of an instantiated derivation -- you could would attach a triple `(mips-linux, mips-linux, sparc-solaris)` to a `.drv` file in `/nix/store`. @@ -94,17 +94,17 @@ Only nine dependency types matter in practice: #### Possible dependency types {#possible-dependency-types} -| Dependency type | Dependency’s host platform | Dependency’s target platform | -|-----------------|----------------------------|------------------------------| -| build → * | build | (none) | -| build → build | build | build | -| build → host | build | host | -| build → target | build | target | -| host → * | host | (none) | -| host → host | host | host | -| host → target | host | target | -| target → * | target | (none) | -| target → target | target | target | +| Dependency type | Dependency’s host platform | Dependency’s target platform | +|-------------------|----------------------------|------------------------------| +| `build → *` | `build` | (none) | +| `build → build` | `build` | `build` | +| `build → host` | `build` | `host` | +| `build → target` | `build` | `target` | +| `host → *` | `host` | (none) | +| `host → host` | `host` | `host` | +| `host → target` | `host` | `target` | +| `target → *` | `target` | (none) | +| `target → target` | `target` | `target` | Let's use `g++` as an example to make this table clearer. `g++` is a C++ compiler written in C. Suppose we are building `g++` with a `(build, host, target)` platform triple of `(foo, bar, baz)`. This means we are using a `foo`-machine to build a copy of `g++` which will run on a `bar`-machine and emit binaries for the `baz`-machine. @@ -235,7 +235,7 @@ One would think that `localSystem` and `crossSystem` overlap horribly with the t ### Implementation of dependencies {#ssec-cross-dependency-implementation} -The categories of dependencies developed in [](#ssec-cross-dependency-categorization) are specified as lists of derivations given to `mkDerivation`, as documented in [](#ssec-stdenv-dependencies). In short, each list of dependencies for "host → target" is called `deps` (where `host`, and `target` values are either `build`, `host`, or `target`), with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `deps` is automatically taken from `pkgs`. (These `pkgs`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time. +The categories of dependencies developed in [](#ssec-cross-dependency-categorization) are specified as lists of derivations given to `mkDerivation`, as documented in [](#ssec-stdenv-dependencies). In short, each list of dependencies for `host → target` is called `deps` (where `host`, and `target` values are either `build`, `host`, or `target`), with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `deps` is automatically taken from `pkgs`. (These `pkgs`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time. Now, for most of Nixpkgs's history, there were no `pkgs` attributes, and most packages have not been refactored to use it explicitly. Prior to those, there were just `buildPackages`, `pkgs`, and `targetPackages`. Those are now redefined as aliases to `pkgsBuildHost`, `pkgsHostTarget`, and `pkgsTargetTarget`. It is acceptable, even recommended, to use them for libraries to show that the host platform is irrelevant. diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index 2a0b239740c0..6013436f2b8a 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -327,14 +327,14 @@ Dependency propagation takes cross compilation into account, meaning that depend To determine the exact rules for dependency propagation, we start by assigning to each dependency a couple of ternary numbers (`-1` for `build`, `0` for `host`, and `1` for `target`) representing its [dependency type](#possible-dependency-types), which captures how its host and target platforms are each "offset" from the depending derivation’s host and target platforms. The following table summarize the different combinations that can be obtained: -| `host → target` | attribute name | offset | typical purpose | -| ------------------- | ------------------- | -------- | --------------------------------------------- | -| `build --> build` | `depsBuildBuild` | `-1, -1` | compilers for build helpers | -| `build --> host` | `nativeBuildInputs` | `-1, 0` | build tools, compilers, setup hooks | -| `build --> target` | `depsBuildTarget` | `-1, 1` | compilers to build stdlibs to run on target | -| `host --> host` | `depsHostHost` | `0, 0` | compilers to build C code at runtime (rare) | -| `host --> target` | `buildInputs` | `0, 1` | libraries | -| `target --> target` | `depsTargetTarget` | `1, 1` | stdlibs to run on target | +| Dependency type | attribute name | offset | typical purpose | +| ----------------- | ------------------- | -------- | --------------------------------------------- | +| `build → build` | `depsBuildBuild` | `-1, -1` | compilers for build helpers | +| `build → host` | `nativeBuildInputs` | `-1, 0` | build tools, compilers, setup hooks | +| `build → target` | `depsBuildTarget` | `-1, 1` | compilers to build stdlibs to run on target | +| `host → host` | `depsHostHost` | `0, 0` | compilers to build C code at runtime (rare) | +| `host → target` | `buildInputs` | `0, 1` | libraries | +| `target → target` | `depsTargetTarget` | `1, 1` | stdlibs to run on target | Algorithmically, we traverse propagated inputs, accumulating every propagated dependency’s propagated dependencies and adjusting them to account for the “shift in perspective” described by the current dependency’s platform offsets. This results in a sort of transitive closure of the dependency relation, with the offsets being approximately summed when two dependency links are combined. We also prune transitive dependencies whose combined offsets go out-of-bounds, which can be viewed as a filter over that transitive closure removing dependencies that are blatantly absurd.