Skip to content

/rust-cookbook

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add build tools section & basic `cc` example #298

Merged
merged 1 commit into from Sep 29, 2017

Conversation

Reviewers

@budziq budziq

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
2 participants
@jaemk @budziq
@jaemk
Copy link
Contributor

jaemk commented Sep 27, 2017

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?
@budziq

budziq requested changes Sep 27, 2017
View changes

Copy link
Collaborator

budziq left a comment

Thanks!
That is exemplar work @jaemk !

I have some minor suggestions due to not knowing how I wanted to look before you have made all the work.
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:

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 27, 2017

Collaborator

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

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 27, 2017

Collaborator

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 ?

This comment has been minimized.

Sign in to view
Copy link
@jaemk

jaemk Sep 27, 2017

Author Contributor

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 Tools
  • Custom Build Steps
  • Building FFI Libraries
  • Compiling and Integrating Non-Rust Code
  • Build Script Support (the conventional name used by cargo)

If not, I think Development Tools might be better for covering a broader topic-space.

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 27, 2017

Collaborator

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 ;)

This comment has been minimized.

Sign in to view
Copy link
@jaemk

jaemk Sep 28, 2017

Author Contributor

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`

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 27, 2017

Collaborator

I would prefer to have this information in the textual description above instead of a comment here.

This comment has been minimized.

Sign in to view
Copy link
@jaemk

jaemk Sep 28, 2017

Author Contributor

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()

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 27, 2017

Collaborator

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.
@jaemk

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

jaemk commented Sep 27, 2017

Thanks @budziq! I'll get to this later tonight!

@jaemk jaemk force-pushed the jaemk:build_tools branch from 5bd561a to 489fe19 Sep 28, 2017

@jaemk

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

jaemk commented Sep 28, 2017

@budziq I went with Build Time Tooling (thoughts?) and cleaned up / added extra info to the first example's description.
@budziq

budziq requested changes Sep 28, 2017
View changes

Copy link
Collaborator

budziq left a comment

Thanks @jaemk just some final touches and we are ready to merge! Sorry to catch the small details so late.
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

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 28, 2017

Collaborator

typo in the domain ;)

This comment has been minimized.

Sign in to view
Copy link
@jaemk

jaemk Sep 28, 2017

Author Contributor

good catch!
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

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 28, 2017

Collaborator

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".

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 28, 2017

Collaborator

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] |

This comment has been minimized.

Sign in to view
Copy link
@budziq

budziq Sep 28, 2017

Collaborator

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)

This comment has been minimized.

Sign in to view
Copy link
@jaemk

jaemk Sep 28, 2017

Author Contributor

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.
@jaemk

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

jaemk commented Sep 28, 2017

@budziq No problem, thanks for the thorough read-through!
@jaemk
Add build time tooling section 
issue #292
- Add new `build_tools.md` file/section
- Add a simple `cc` crate example
Loading status checks…
b9ef026

@jaemk jaemk force-pushed the jaemk:build_tools branch from 489fe19 to b9ef026 Sep 28, 2017

@jaemk

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

jaemk commented Sep 29, 2017

@budziq let me know if you see anything else
@budziq

budziq approved these changes Sep 29, 2017
View changes

@budziq budziq merged commit 403f9e6 into rust-lang-nursery:master Sep 29, 2017
2 checks passed

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@budziq

This comment has been minimized.

Sign in to view
Copy link
Collaborator

budziq commented Sep 29, 2017

Excellent work! Thanks @jaemk
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.