Rewrite build script documentation in terms of build-rs

[Xaeroxe]

This documentation https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/build-scripts.md is authored on the assumption that the cargo owned build-rs crate is not used for build scripts. We should consider rewriting this in terms of build-rs in order to encourage adoption of that crate. The current documentation could remain as supplemental material, such that crates which have not yet adopted build-rs can continue to be understood and maintained. This is a substantial change to how build scripts are typically authored, so should warrant an FCP at minimum.

This could enable us to provide better APIs for more complex build flows. Some examples of this are provided at #14816. Another idea is that when cargo is compiling with checksum freshness mode for fingerprints, the rerun-if-changed function could compute a correct checksum for the file, and then provide it to cargo for use in subsequent builds. That would resolve the outstanding issue at #14136 "How should we handle checksums for files processed by build scripts?"

Encouraging the adoption of build-rs by the ecosystem better enables us to evolve this API in a type-safe manner, and build more capabilities into it.

[hanna-kruppe]

Aside: whenever I see something about Cargo having adopted build-rs, I check crates.io and see no new versions of build-rs since 2022. Either I’m looking at the wrong crate or there’s a few steps missing before it makes sense to advertise this crate as The Way to write build scripts 🤔

[epage]

Looks like we forgot to add it to our publish list
https://github.com/rust-lang/cargo/blob/master/publish.py