DEP_* environment variable documentation not clear

[indygreg]

Problem

https://doc.rust-lang.org/cargo/reference/build-scripts.html says:

Any other element is a user-defined metadata that will be passed to dependents. More information about this can be found in the links section.

This implies to me that DEP_* variables will always be set if they are emitted by a dependent crate.

But if you read the linked https://doc.rust-lang.org/cargo/reference/build-scripts.html#the-links-manifest-key it starts to mention association with the links manifest key. It doesn't say so explicitly, but experimentation reveals the links key is required in order for DEP_* variables to be set on the dependent crate.

Possible Solution(s)

Clarify documentation that links is necessary to make DEP_* appear.

Even better would be to always set the DEP_* environment variables. Cargo seems to lack a generic way to pass metadata between crate build scripts outside of library/linkage info. I frequently find myself wanting this feature for indygreg/PyOxidizer, which is doing some wonky things in build scripts. It would be immensely useful if state could be passed between dependencies via environment variables. I'm sure there is already a feature request for that somewhere though...

Notes

Output of cargo version:

1.40.0

[ehuss]

The build script chapter has been largely reworked, which I think should go live tomorrow with the new release. https://doc.rust-lang.org/beta/cargo/reference/build-scripts.html Perhaps you can take a look and see if it makes it clearer that it is links specific?

As for passing more information, I think that is covered by #3544?

[indygreg]

The new docs say cargo:KEY=VALUE — Metadata, used by links scripts. and the docs for [links] appears largely unchanged. I think I'd like to see an only used by where it defines the cargo:KEY=VALUE syntax.

#3544 does appear to track the feature I want!

[ehuss]

Would be happy to have a PR that clarifies whichever parts are not clear.

[epage]

On https://doc.rust-lang.org/cargo/reference/build-scripts.html

As mentioned above in the output format, each build script can generate an arbitrary set of metadata in the form of key-value pairs. This metadata is passed to the build scripts of dependent packages. For example, if the package bar depends on foo, then if foo generates key=value as part of its build script metadata, then the build script of bar will have the environment variables DEP_FOO_KEY=value. See the “Using another sys crate” for an example of how this can be used.

Other -sys packages can take advantage of the DEP_NAME_KEY=value environment variables to better integrate with other packages. See the “Using another sys crate” example.

On https://doc.rust-lang.org/cargo/reference/environment-variables.html

DEP__ — For more information about this set of environment variables, see build script documentation about links.

For me, the current docs seem clear. We'd welcome input on further improvement but I'm going to go ahead and close this as resolved as its easy to always be moving the fence posts on improvements.