What is propagation of a dependency?

Question

https://nixos.org/manual/nixpkgs/stable/#ssec-stdenv-dependencies 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

What do "downstream" and "upstream" dependencies mean?

What are "non-immediate" and "immediate" dependencies?

Is the concept of a dependency propagating about the dependent relationship between the dependencies of a package?

Could you explain using an example or diagram?

Answer 1

If package A is an "immediate dependency" of package B, that means we need A in a very direct/explicit way when we are building B. Specifically, while building B, we might need to have A be on the PATH, or be in the PKG_CONFIG_PATH, or we might need to run some "setup hooks" (shell scripts) defined by A, or there might be some other way that we need to access A while building B.

A "non-immediate" dependency would be a dependency that is NOT an immediate dependency but is still a dependency in a less direct way: you wouldn't see it directly in your environment if you run env while building B. Maybe we build B using some program, and that program uses some libraries, so those libraries could be said to be a "non-immediate" dependency of B.

By the way, this use of the word "immediate" is not any kind of standard in computer science, so the Nixpkgs manual should really define it better if they are going to use it.

When the author uses the phrase "downstream dependency" they are misusing the word "dependency", so I will not attempt to define the phrase. They are also misusing the phrase "non-immediate". Instead, I will just rewrite that sentence. Here's what it should have said:

If the Nix expression for package B defines package A to be a propagated dependency, then nixpkgs will automatically add A to the immediate dependency list of any package that has B in its immediate dependency list.

That can be convenient because then every package with an immediate dependency on B automatically gets A added to their list of immediate dependencies, without them having to know about A or explicitly mention it anywhere.

(Aside: I wrote a large Nix project called nixcrpkgs and I never needed to have the concept of a propagated dependency in the Nix expressions. If C depends on B and B depends on A and C needs to find A, I just added some symbolic links in the appropriate places in the output of B so that C could find A. Sometimes nixpkgs is just overly complicated without good justifications.)