Official API for build scripts

[epage]

Problem

Having a Rust API would help with several problems

• Help people migrate through build script best practices (e.g. Cannot extend build directives within cargo #11461)
• Avoid people making type mistakes
• Bring documentation more inline with people's workflow, e.g. IDEs auto-completing and rendering doc comments
• Help improve discoverability of APIs
• Ensures a feedback loop with the cargo team, hoping it avoids some failure modes where compatibility is broken
• Reduce duplicated effort
  • build_script
  • build-rs
  • build-env
  • vergen
  • foreman <=0.4.0 (package name was handed off and used for a different purpose after that version)
  • system-deps
  • rsconf

Proposed Solution

A crate that provides an API for working with build scripts

• Low level API handling writing of directives, reading runtime env variables, etc (see also Official API for reading cargo env variables #12431)
• A higher level API to help with re-run-if-changed

Notes

Things to work out

• Name
• If we co-maintain, how repo and publish permissions work out
• How do we handle the MSRV because the cargo repo currently only handles "latest" (see also fix: Set MSRV for internal packages #12381) see Set and verify all MSRVs in CI #12654

As for timing, it'd help if we had this to recommend before we fully resolve #11461 so we can tell people to migrate once, rather than twice

FCP

[epage]

FYI we now have an MSRV policy as of #12654