Can't build docs for my crate (⇒ add ability to set environment variables?)

[pkgw]

I just uploaded a new crate, slurm-sys, which provides bindings to a C library called libslurm. However, my docs won't currently build on docs.rs (failure) because on Debian Jessie, the dev packages for libslurm don't include a pkg-config file, which my build.rs expects to exist.

If I could set environment variables in the docs.rs build environment, I could set SLURM_NO_PKG_CONFIG and I think everything would work; and I think this would be the appropriate thing for users to do when no pkg-config file is present. But as far as I can tell, it isn't possible to set this environment variable for the docs.rs build.

Is that correct? Is there another workaround? It wouldn't be the most elegant, but if there were a way for my build.rs script to detect that it is running inside the docs.rs environment, I could add special-case code.

[nickbabcock]

I would also like environment variables to be configurable. In the meantime, I worked around it as follows:

In Cargo.toml

[package.metadata.docs.rs]
rustc-args = ["--cfg",  "<name>_docs_rs"]
rustdoc-args = ["--cfg", "<name>_docs_rs"]

In build script:

#[cfg(<name>_docs_rs)]
fn detect_version() -> String {
    String::from("5.5")
}

#[cfg(not(<name>_docs_rs))]
fn detect_version() -> String {
    // Use environment variables
}

[pkgw]

That's clever! But definitely kludgey :-)

[glts]

This is still a problem, and I don't think a general 'clean' work-around exists. My package bundles a file milter.pc in the project root, and I can build the docs locally with PKG_CONFIG_PATH=. cargo doc, but can't build on docs.rs. So env variable support would be welcome.

[kornelski]

I think you should be able to set env vars in your build.rs. They won't affect your dependencies, but they should affect your pkg_config calls.

[glts]

Thank you, I tried with fn main() { println!("cargo:rustc-env=PKG_CONFIG_PATH=."); } in build.rs but it doesn't have any effect for me.

[jyn514]

Is this a command you're calling in build.rs? Can you use set_var directly?

[glts]

All right, the project is https://gitlab.com/glts/milter. It requires libmilter-dev (Debian/Ubuntu), and it bundles a milter.pc file.

Then cargo doc:

error: failed to run custom build command for `milter-sys v0.1.4`
...
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Failure { command: "\"pkg-config\" \"--libs\" \"--cflags\" \"milter\"", output: Output { status: ExitStatus(ExitStatus(256)), stdout: "", stderr: "Package milter was not found in the pkg-config search path.\nPerhaps you should add the directory containing `milter.pc\'\nto the PKG_CONFIG_PATH environment variable\nNo package \'milter\' found\n" } }', src/libcore/result.rs:1188:5

Then doing exactly what the error message tells me, PKG_CONFIG_PATH=. cargo doc succeeds. But I haven’t been able to have this work on docs.rs, neither with cargo:rustc-env in build.rs, nor with set_var in build.rs.

[jyn514]

@glts the following patch makes the docker build succeed for me:

diff --git a/build.rs b/build.rs
index 6f5ef92..1e5f22a 100644
--- a/build.rs
+++ b/build.rs
@@ -1,4 +1,5 @@
 fn main() {
+    std::env::set_var("PKG_CONFIG_PATH", ".");
     // Hack to make the build work on docs.rs, where PKG_CONFIG_PATH can’t be
     // set. Remove once pkg-config file lands in distro.
     if cfg!(milter_sys_docs_rs) {

[jyn514]

For everybody else on the issue: we now set DOCS_RS=1 unconditionally in the environment so you can tell this is a docs.rs build (#147). Does that meet your use case?

[glts]

@jyn514 All right, thank you for your help.

(For me, it is still unfortunate [?] that I would have to hard-code the variable in build.rs instead of passing it in the docs.rs environment. But moving on.)

[jyn514]

if there were a way for my build.rs script to detect that it is running inside the docs.rs environment, I could add special-case code.

Since we set DOCS_RS=1 I'm going to close this as fixed. Feel free to comment if you have a use-case that isn't helped by that and I'll re-open.

[multimeric]

Although it is possible to work around all these issues using the DOCS_RS var, I think the neater solution would be to add some sort of [package.metadata.docs.rs.env] key to Cargo.toml that lets us add a dictionary of env vars.

The reason this would be preferable is because we want to avoid special cases in our code for environments such as docs.rs, and solving it via configuration is a simple and declarative way to do this.