Cargo

• Cargo is Rust’s build system and package manager
• Cargo.toml specifies dependencies and their version
• cargo build will build your project

  • Default profile is dev (debug)

  • To compile with Release optimizations use --release flag

  • Output binaries will be in target/<profile>/

  • Profiles can be modified in Cargo.toml:

    [profile.dev]
    opt-level = 0
    
    [profile.release]
    opt-level = 3
    

    • The opt-level setting controls the number of optimizations Rust will apply to your code, with a range of 0 to 3.
• The crate registry at crates.io distributes the source code of your packages, so it primarily hosts code that is open source.
• cargo run will build and run your project
• cargo check checks if the project compiles but it does not generate any executable
• rustc is the compiler for the Rust programming language, provided by the project itself. Compilers take your source code and produce binary code, either as a library or executable. Most Rust programmers don't invoke rustc directly, but instead, do it through Cargo. It's all in service of rustc though! If you want to see how Cargo calls rustc, you can: $ cargo build --verbose. And it will print out each rustc invocation.
• If we want to use a toolchain different from the default one we can: cargo +<toolchainName>
• Cargo "features" provide a mechanism to express conditional compilation and optional dependencies.Cargo "features" provide a mechanism to express conditional compilation and optional dependencies.Cargo "features" provide a mechanism to express conditional compilation  and optional dependencies.
  • Features for the package being built can be enabled on the command-line with flags such as --features

Generating Documentation

• Rust also has a particular kind of comment for documentation, known conveniently as a documentation comment, that will generate HTML documentation.
  • The HTML displays the contents of documentation comments for public API items intended for programmers interested in knowing how to use your crate as opposed to how your crate is implemented.
• Documentation comments use three slashes, ///, instead of two and support Markdown notation for formatting the text.
• Place documentation comments just before the item they’re documenting.
• We can generate the HTML documentation from this documentation comment by running cargo doc
  • This command runs the rustdoc tool distributed with Rust and puts the generated HTML documentation in the target/doc directory.
  • For convenience, running cargo doc --open will build the HTML for your current crate’s documentation (as well as the documentation for all of your crate’s dependencies) and open the result in a web browser.
• There are some sections that crate authors commonly use in their documentation:
  • Examples
  • Panics: The scenarios in which the function being documented could panic. Callers of the function who don’t want their programs to panic should make sure they don’t call the function in these situations.
  • Errors: If the function returns a Result, describing the kinds of errors that might occur and what conditions might cause those errors to be returned can be helpful to callers so they can write code to handle the different kinds of errors in different ways.
  • Safety: If the function is unsafe to call (we discuss unsafety in Chapter 19), there should be a section explaining why the function is unsafe and covering the invariants that the function expects callers to uphold.
• Adding example code blocks in your documentation comments can help demonstrate how to use your library, and doing so has an additional bonus: running cargo test will run the code examples in your documentation as tests!
• //!, adds documentation to the item that contains the comments rather than adding documentation to the items following the comments.
  • We typically use these doc comments inside the crate root file (src/lib.rs by convention) or inside a module to document the crate or the module as a whole.

Setting Up a Crates.io Account