Add build tools section & basic cc example
#298
Conversation
src/build_tools.md
Outdated
| Common use cases include `rust` code generation and compilation of bundled `C/C++/asm` code. | ||
| See `crates.io`'s [documentation on the matter][build-script-docs] for more information. | ||
|
|
||
| Notes: |
There was a problem hiding this comment.
I would remove the notes section here. The play button will not work anyway as these examples will be no_run anyway.
src/build_tools.md
Outdated
| @@ -0,0 +1,122 @@ | |||
| # Build Tools | |||
There was a problem hiding this comment.
In the hindsight I'm not sure if "Development Tools" would not be a better name but I'm willing to crowd source here. What do you think @jaemk ?
There was a problem hiding this comment.
Now that I'm thinking about it, I'm wondering what other types of examples (other than cc stuff) will eventually be included here, if any. Does something of this nature deserve a more specifically named category? Maybe one of the following?
External Build ToolsCustom Build StepsBuilding FFI LibrariesCompiling and Integrating Non-Rust CodeBuild Script Support(the conventional name used by cargo)
If not, I think Development Tools might be better for covering a broader topic-space.
There was a problem hiding this comment.
Hmm in time we might want to have here other types of support tooling such as
so imho Development Tools, Compile time or Build time dependencies might be appropriate (I'm leaning towards the last one). But I'll let you chose, its easy enough to change anytime ;)
There was a problem hiding this comment.
What do you think of Build Time Tooling or Build Time Tools?
src/build_tools.md
Outdated
| extern crate cc; | ||
|
|
||
| fn main() { | ||
| // builds a static lib: `libhello.a` |
There was a problem hiding this comment.
I would prefer to have this information in the textual description above instead of a comment here.
There was a problem hiding this comment.
I've made note of the output name in the example description, including a link to the compile method that talks about the naming scheme of output files. But I've also kept a comment nearby to make it clear that the compile output may not necessarily match the specified name.
src/build_tools.md
Outdated
|
|
||
| fn main() { | ||
| // builds a static lib: `libhello.a` | ||
| cc::Build::new() |
There was a problem hiding this comment.
I'd love to see some hyperlinked references pointing to the used structs and methods as this is the firs formative example in this section.
|
Thanks @budziq! I'll get to this later tonight! |
|
@budziq I went with |
src/links.md
Outdated
| [cat-encoding-badge]: https://badge-cache.kominick.com/badge/encoding--x.svg?style=social | ||
| [cat-encoding]: https://crates.io/categories/encoding | ||
| [cat-external-ffi-bindings-badge]: https://badge-cache.kominick.com/badge/external_ffi_bindings--x.svg?style=social | ||
| [cat-external-ffi-bindings]: https://crate.io/categories/external-ffi-bindings |
src/build_tools.md
Outdated
|
|
||
| [build-script-docs]: http://doc.crates.io/build-script.html | ||
| [playground]: https://play.rust-lang.org | ||
| [cc-build]: https://docs.rs/cc/1.0.0/cc/struct.Build.html |
There was a problem hiding this comment.
I would suggest using wildcard version numbers in doc.rs links
src/build_tools.md
Outdated
| # Build Time Tooling | ||
|
|
||
| This section covers "build-time" tooling, or code that is run prior to compiling a crate's source code. | ||
| Conventionally, build-time code lives in a `build.rs` file and is commonly referred to as a "build script". |
There was a problem hiding this comment.
Sorry to catch this this late but generally we strive to use backticks `` for code /symbols or external commands and for other text we use different form of emphasis (italics or bold). So I would change the method of emphasis for the file/language/crate/website names and use the backticks only for symbols and language keywords (extern)
src/intro.md
Outdated
|
|
||
| | Recipe | Crates | Categories | | ||
| |--------|--------|------------| | ||
| | [Compile and link statically to a bundled C library][ex-cc-static-bundled] | [![cc-badge]][cc] | [![cat-development-tools-badge]][cat-development-tools] [![cat-rust-patterns-badge]][cat-rust-patterns] [![cat-external-ffi-bindings-badge]][cat-external-ffi-bindings] | |
There was a problem hiding this comment.
I'm not sure about the "rust-patterns" badge is appropriate here (infact the the "external-ffi-bindings" to as these is pretty much reselved for "*sys" crates and the bindgen)
There was a problem hiding this comment.
I also wasn't too sure which categories were appropriate when I first start this, so I just chose a couple and forgot to ask you earlier! I agree, just Development Tools seems appropriate now.
|
@budziq No problem, thanks for the thorough read-through! |
issue rust-lang-nursery#292 - Add new `build_tools.md` file/section - Add a simple `cc` crate example
|
@budziq let me know if you see anything else |
|
Excellent work! Thanks @jaemk |
issue #292
@budziq Here's what I've got so far. Were you thinking of a more in-depth build-tools intro? Does the wording make sense?