How should this table of platforms of dependencies be read?

Question

https://nixos.org/manual/nixpkgs/stable/#ssec-stdenv-dependencies-reference says

A dependency is said to be propagated when some of its other-transitive (non-immediate) downstream dependencies also need it as an immediate dependency. [3]

It is important to note that dependencies are not necessarily propagated as the same sort of dependency that they were before, but rather as the corresponding sort so that the platform rules still line up. 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, 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
build --> build       depsBuildBuild          -1, -1
build --> host        nativeBuildInputs       -1, 0
build --> target      depsBuildTarget         -1, 1
host --> host         depsHostHost            0, 0
host --> target       buildInputs             0, 1
target --> target     depsTargetTarget        1, 1

I was wondering how to read the table?

What do the arrows in "host → target" and "build --> build" mean?

How are the offsets calculated?

Answer 1

So this is quite close to your other question here, and it turns out that my new answer there answer this question as well. Long story short, if you do not build compilers, then you just want to use nativeBuildInputs for dependencies needed at compilation time (cmake, pkg-build etc), and buildInputs for everything else.

For more advanced use-cases, the table you see has two redundant columns: offset is just a numeric translation of the first column, where:

• -1=build (architecture of the machine that builds the program),
• 0=host (architecture of the machine that will run the program),
• 1=target (architecture of the machine that will run the programs compiled by your programs if you build a compiler).

So host -> target is the same thing as setting the tuple (0,1), and it informally means that the dependency will be run on the host, and (if it is a compiler) that it should compile stuff for the architecture target.

The column in the middle is the command to call to attribute the corresponding tuple to a dependency: for instance:

nativeBuildInput = [ gcc ];

will associate build -> host to gcc, i.e. states the flavor of gcc that is needed is the one running on the build architecture, compiling for the host architecture.

More details here.