Expand documentation on build scripts. #7565
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
(rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
alexcrichton
reviewed
Nov 6, 2019
There was a problem hiding this comment.
This looks fantastic, thanks so much for taking the time to write all this up @ehuss!
I've just got one small nit, but otherwise I think all the content here is great.
| * [`rustc_version`](https://crates.io/crates/rustc_version), | ||
| [`version_check`](https://crates.io/crates/version_check) — These crates | ||
| provide ways to implement conditional compilation based on the current | ||
| version of `rustc`. |
There was a problem hiding this comment.
I'm slightly hesitant to recommend these because there's actually quite a few on crates.io, and some (like rustc_version) have known drawbacks and hindrances in terms of compile time and/or robustness of the parser. I'd also personally recommend autocfg, but maybe we should just maintain a list of all of them here?
There was a problem hiding this comment.
Yea, it's tough because I don't want it to seem too much like an endorsement or recommendation, but more like "here are some popular examples". What if there was a disclaimer of some kind? I included those two version crates just because they have such a huge number of downloads, and I figure the reader can decide which one is right for them.
I think I just forgot to add autocfg.
I think a warning about compile times is a good idea.
There was a problem hiding this comment.
Ok, sounds reasonable to me!
Also add `autocfg` to the list.
|
@bors: r+ |
|
📌 Commit dd546ea has been approved by |
bors
added
S-waiting-on-bors
bors
added a commit
that referenced
this pull request
Nov 7, 2019
Expand documentation on build scripts.
This restructures and adds some more documentation for writing build scripts. An overview:
- Move examples to a separate chapter.
- Add some links to common build dependencies.
- Rewrote the example of linking to system libraries.
- Rewrote some of the `links` and `-sys` examples.
- Added a "conditional compilation" example.
- De-emphasize setting `build = "build.rs"`.
- Explain how build scripts run.
- Give each `cargo:` instruction a separate section with more detail.
- More detail on how `rerun-if` stuff works. Also, try to emphasize best practices, especially in examples.
- Try to clarify `links` and go into more detail.
- Document the jobserver.
- Expand on environment variables.
- Document dylib search path behavior.
I have explicitly skipped trying to document rpath issues, as it seems to be a mess, and I can't really sort it out.
I'd be happy to have any feedback for things to add or change.
Closes #1251
Closes #2236
Closes #2888
Closes #3304
Closes #3968
Closes #5499
Closes #7338
|
☀️ Test successful - checks-azure |
bors
added a commit
to rust-lang/rust
that referenced
this pull request
Nov 17, 2019
Update Cargo, books ## cargo 12 commits in 5da4b4d47963868d9878480197581ccbbdaece74..8280633db680dec5bfe1de25156d1a1d53e6d190 2019-10-28 21:53:41 +0000 to 2019-11-11 23:17:05 +0000 - Don't panic when parsing `/proc/stat` (rust-lang/cargo#7580) - Fix unused configuration key warning for a few keys under `build`. (rust-lang/cargo#7575) - Add back support for `BROWSER` envvar in `cargo doc --open`. (rust-lang/cargo#7576) - Only include "already existing ..." comment in gitignore on conflict (rust-lang/cargo#7570) - Add VS Code user dir to .gitignore (rust-lang/cargo#7578) - Added aliases to subcommand typo suggestions. (rust-lang/cargo#7486) - Use multiple requirement syntax consistently (rust-lang/cargo#7573) - Update verison to 0.42 (rust-lang/cargo#7568) - Expand documentation on build scripts. (rust-lang/cargo#7565) - Update crossbeam-utils requirement from 0.6 to 0.7 (rust-lang/cargo#7566) - don't download std-docs on CI (rust-lang/cargo#7513) - Change my-buddy to github-handle (rust-lang/cargo#7553) ## nomicon 2 commits in 5004ad30d69f93553ceef74439fea2159d1f769e..58e36e0e08dec5a379ac568827c058e25990d6cd 2019-10-12 19:52:40 +0200 to 2019-10-30 08:14:24 -0500 - remove references to the nursery - Add github action to replace Travis.yml (rust-lang/nomicon#172) ## reference 7 commits in 4b21b64..45558c4 2019-10-27 22:33:11 +0100 to 2019-11-08 14:47:35 +0100 - Audit code blocks. (rust-lang/reference#715) - Update coherence and orphan rules documentation to match RFC 2451 (rust-lang/reference#703) - Update organization name (rust-lang/reference#713) - State that no_implicit_prelude also applies to nested modules (rust-lang/reference#707) - expand Copy docs (rust-lang/reference#711) - github action doesn't use the nursery (rust-lang/reference#706) - Migrate to GitHub Actions. (rust-lang/reference#705) ## book 1 commits in 28fa3d15b0bc67ea5e79eeff2198e4277fc61baf..e79dd62aa63396714278d484d91d48826737f47f 2019-10-29 07:16:09 -0500 to 2019-10-30 07:33:12 -0500 - No need for an iterator here to fetch values (rust-lang/book#1957) ## rust-by-example 1 commits in f3197ddf2abab9abdbc029def8164f4a748b0d91..dcee312c66267eb5a2f6f1561354003950e29105 2019-10-29 10:17:40 -0300 to 2019-10-31 11:26:53 -0300 - refactor: simplify extracting Result from Option (rust-lang/rust-by-example#1283) ## edition-guide 2 commits in e58bc4ca104e890ac56af846877c874c432a64b5..f553fb26c60c4623ea88a1cfe731eafe0643ce34 2019-07-31 20:14:12 +0200 to 2019-10-30 08:27:42 -0500 - remove old references to the nursery - Port from Travis to GitHub Actions (rust-lang/edition-guide#192)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This restructures and adds some more documentation for writing build scripts. An overview:
linksand-sysexamples.build = "build.rs".cargo:instruction a separate section with more detail.rerun-ifstuff works. Also, try to emphasize best practices, especially in examples.linksand go into more detail.I have explicitly skipped trying to document rpath issues, as it seems to be a mess, and I can't really sort it out.
I'd be happy to have any feedback for things to add or change.
Closes #1251
Closes #2236
Closes #2888
Closes #3304
Closes #3968
Closes #5499
Closes #7338