OUT_DIR should be symlinked in a meaningful way

[Firstyear]

Describe the problem you are trying to solve
When using OUT_DIR with something like clap to generate argument completions, the recommendation is to use cargo's OUT_DIR value as the location to emit these to. However, when there are generated, they are placed into a folder such as:

target/debug/build/
    - kanidm-3cf33c76b6bbe4d1/out
    - kanidm-9693c458c15d1b42/out

Post build, tools that want to install these completions to a system, it's impossible to determine which is the latest build hash (this is not contained in cargo metadata for example). This means you have to:

• cargo clean
• rebuild
• rely on globbing to remove the hash.

Describe the solution you'd like

Not all tools support this, so it would be clearer if there was a way to link from the latest build to it's relevant hash. For example:

target/debug/build/
    - kanidm-3cf33c76b6bbe4d1/out
    - kanidm-9693c458c15d1b42/out
    - kanidm -> kanidm-9693c458c15d1b42

This way the OUT_DIR content can be found in ./target/profile/build/package/out without knowledge of the latest build hash.

This makes OUT_DIR more usable for build.rs components when generating external content and easier to find that content for installers.

Notes
clap completions - https://alephalpha.github.io/rlifesrc-doc/clap/struct.App.html#method.gen_completions

[ehuss]

For now, build scripts are not intended for general-purpose build tasks such as building shell completions or man pages. The OUT_DIR is intentionally opaque as it is only intended for rustc interaction. I'm going to close as this is likely a large consideration that would probably be best approached through the RFC process. I understand that it can be frustrating not being able to build additional artifacts via cargo commands directly. For now, I would suggest using something like the cargo-xtask or cargo-make or other similar tools.

[Firstyear]

The docs contradict this though:

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

OUT_DIR — If the package has a build script, this is set to the folder where the build script should place its output. See below for more information. (Only set during compilation.)

It literally says this is where the buildscript should be placing output. So IMO either this documentation is wrong, or OUT_DIR needs to be improved to assist in it's usage as a build_script output location.