Chrono feature in built_time() example on docs.rs

[trebinor]

An example function built_time() appears for the latest (0.6.1) version of built on docs.rs

#[cfg(feature = "chrono")]
fn built_time() -> built::chrono::DateTime<built::chrono::Local> {
    built::util::strptime(built_info::BUILT_TIME_UTC)
        .with_timezone(&built::chrono::offset::Local)
}

What is the proper way to enable the chrono feature to enable conditional compilation of built_time()? Maybe this cfg is no longer needed, because commenting it out includes the function. Note that that adding this to Cargo.toml has no effect.

[features]
chrono = []

The fix can be tested by adding built_time() before main() in built/example_project/src/main.rs and adding this to main():

    println!("Build time: {:?}", built_time());

You should see that built_time() is not found when the cfg is present, and the build succeeds if it's commented out.

[lukaslueg]

I'm sorry: What?

[trebinor]

What part is unclear?

[lukaslueg]

I don't understand your intention. Are you trying to use built_time() as demonstrated in the docs, and asking how to do it? Or are you suggesting a doc-bug?

[trebinor]

I'm suggesting it's a either a doc bug that the attribute #[cfg(feature = "chrono")] should pair with the built_time() definition (most likely), or if it's intended maybe I'm not enabling chrono correctly. As it is in your example project and my own crate, I have to remove this attribute or built_time() isn't found at compile time.

[lukaslueg]

The attribute in the docs document that the function is only available if built was built with the chrono-flag enabled. As it is a runtime-function (as opposed to a build-time function), you need built with the flag enabled as a runtime-dependency. As demonstrated here

[trebinor]

I think you've just confirmed example_project's toml has chrono enabled for built as a dependency and a build dependency. I can also see it's enabled during the build step.

   Compiling built v0.6.1 (/home/trebinor/ws/git/lukaslueg/built)
     Running `rustc --crate-name built --edition=2021 /home/trebinor/ws/git/lukaslueg/built/src/lib.rs --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=125 --crate-type lib --emit=dep-info,metadata,link -C embed-bitcode=no -C debuginfo=2 --cfg 'feature="cargo-lock"' --cfg 'feature="chrono"' --cfg 'feature="git2"' --cfg 'feature="semver"' -C metadata=9a969f2a3114e119 -C extra-filename=-9a969f2a3114e119 --out-dir /home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/deps -C incremental=/home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/incremental -L dependency=/home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/deps --extern cargo_lock=/home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/deps/libcargo_lock-a24eb7c1cbdf776b.rmeta --extern chrono=/home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/deps/libchrono-952daf281ef4242f.rmeta --extern git2=/home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/deps/libgit2-8c72b112d11bac36.rmeta --extern semver=/home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/deps/libsemver-de3bcee436d8d491.rmeta -L native=/home/trebinor/ws/git/lukaslueg/built/example_project/target/debug/build/libgit2-sys-d929459472365028/out/build`

Yet built_time() is not found when example_project is built unless I comment out the attribute.

error[E0425]: cannot find function `built_time` in this scope
 --> src/main.rs:9:34
  |
9 |     println!("Build time: {:?}", built_time());
  |                                  ^^^^^^^^^^ not found in this scope

You can try this for yourself by adding the built_time() definition and call in src/main.rs for example_project.

[lukaslueg]

Ah, now I see your point. There is a bit of confusion here: When example_project builds, the chrono-feature is enabled for built at build- and runtime. But it is not enabled for example_project itself. As you mentioned, adding

[features]
chrono = []

to example_project/Cargo.toml has no effect; but this is simply because it is not enabled. One has to actually enable this feature via cargo ... --features chrono. Then it will compile with built_time.

The feature-flag in the docs is there because built::util::strptime is not defined if chrono is not enabled. So the upstream crate needs to be careful not to refer to it if chrono isn't there.

[trebinor]

Ok, I think things are a bit more clear now. I was able to build with cargo build --features chrono after adding a chrono feature to example_project's Cargo.toml.

That section on doc.rs could still use an update, and here's why. The built_time function is said to go in the "the crate's code" implying the downstream crate, example_project in our case, and you say the cfg macro is there because built::util::strptime needs chrono enabled for built. Unfortunately #[cfg(feature = "chrono")] only tests for this feature in the current crate, not the upstream crates. You can see this by removing chrono from dependencies and build-dependencies in example_project's Cargo.toml but keeping chrono = [] and enabling it in the build. built_time is included because the example_project chrono feature is enabled, but the project doesn't build because chrono was not enabled in the built crate. The cfg check didn't do what you suggested.

What we really want is a way for cfg to check for a feature of an upstream crate. Is there really no way to do this? Something like #[cfg(feature = "built::chrono")] ? I couldn't find a way to do this in the Rust book.

[lukaslueg]

The correct way to write this feature in the upstream's crate is

[features]
chrono = ["built/chrono"]

[trebinor]

I had already played around with that. All that does is enable chrono for built, removing the need to do it in dependencies. My point still applies about the check #[cfg(feature = "chrono")] not doing anything with the upstream built crate.

That was the main point of this issue, that the cfg check on built_time isn't useful in checking whether has built has chrono enabled. It would awesome if #[cfg(feature = "built/chrono")] checked if the chrono feature is set in built, but that doesn't work either.