{ "cells": [ { "cell_type": "markdown", "id": "670184c1-8f72-475b-94a3-0d9f49eff4d2", "metadata": {}, "source": [ "## Hello, Cargo!\n", "\n", "Cargo is Rust’s build system and package manager. Most Rustaceans use this tool to manage their Rust projects because Cargo handles a lot of tasks for you, such as building your code, downloading the libraries your code depends on, and building those libraries. (We call the libraries that your code needs *dependencies*.)\n", "\n", "The simplest Rust programs, like the one we’ve written so far, don’t have any dependencies. If we had built the “Hello, world!” project with Cargo, it would only use the part of Cargo that handles building your code. As you write more complex Rust programs, you’ll add dependencies, and if you start a project using Cargo, adding dependencies will be much easier to do.\n", "\n", "Because the vast majority of Rust projects use Cargo, the rest of this book assumes that you’re using Cargo too. Cargo comes installed with Rust if you used the official installers discussed in the `“Installation”` section. If you installed Rust through some other means, check whether Cargo is installed by entering the following in your terminal:\n", "\n", "```sh\n", "$ cargo --version\n", "```\n", "\n", "If you see a version number, you have it! If you see an error, such as `command not found`, look at the documentation for your method of installation to determine how to install Cargo separately.\n", "\n", "### Creating a Project with Cargo\n", "\n", "Let’s create a new project using Cargo and look at how it differs from our original “Hello, world!” project. Navigate back to your *projects* directory (or wherever you decided to store your code). Then, on any operating system, run the following:\n", "\n", "```sh\n", "$ cargo new hello_cargo\n", "$ cd hello_cargo\n", "```\n", "\n", "The first command creates a new directory and project called *hello_cargo*. We’ve named our project *hello_cargo*, and Cargo creates its files in a directory of the same name.\n", "\n", "Go into the *hello_cargo* directory and list the files. You’ll see that Cargo has generated two files and one directory for us: a *Cargo.toml* file and a src directory with a *main.rs* file inside.\n", "\n", "It has also initialized a new Git repository along with a *.gitignore* file. Git files won’t be generated if you `run cargo` new within an existing Git repository; you can override this behavior by using `cargo new --vcs=git`\n", "\n", "
\n", " more details\n", " \n", " Open Cargo.toml in your text editor of choice. It should look similar to the code in Listing 1-2.\n", "\n", " Filename: *Cargo.toml*\n", "\n", " ```sh\n", " [package]\n", " name = \"hello_cargo\"\n", " version = \"0.1.0\"\n", " edition = \"2021\"\n", "\n", " # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html\n", "\n", " [dependencies]\n", " ```\n", " This file is in the *TOML (Tom’s Obvious, Minimal Language)* format, which is Cargo’s configuration format.\n", "\n", " The first line, `[package]`, is a section heading that indicates that the following statements are configuring a \n", " package. As we add more information to this file, we’ll add other sections.\n", "\n", " The next three lines set the configuration information Cargo needs to compile your program: the name, the version, and the edition of Rust to use. We’ll talk about the `edition` key in `Appendix E`.\n", "\n", " The last line, `[dependencies]`, is the start of a section for you to list any of your project’s dependencies. In Rust, packages of code are referred to as crates. We won’t need any other crates for this project, but we will in the first project in Chapter 2, so we’ll use this dependencies section then.\n", "\n", " Now open *src/main.rs* and take a look:\n", "\n", " Filename: *src/main.rs*\n", "\n", " ```rust\n", " fn main() {\n", " println!(\"Hello, world!\");\n", " }\n", " ```\n", "\n", " ## Building and Running a Cargo Project\n", " Now let’s look at what’s different when we build and run the “Hello, world!” program with Cargo! From your *hello_cargo* directory, build your project by entering the following command:\n", "\n", " ```sh\n", " $ cargo build\n", " Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)\n", " Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs\n", " ```\n", "\n", "We just built a project with `cargo build` and ran it with `./target/debug/hello_cargo`, but we can also use `cargo run` to compile the code and then run the resultant executable all in one command:\n", "\n", "\n", " ```rust\n", " $ cargo run\n", " Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs\n", " Running `target/debug/hello_cargo`\n", " Hello, world!\n", " ```\n", "\n", "Cargo also provides a command called `cargo check`. This command quickly checks your code to make sure it compiles but doesn’t produce an executable:\n", "\n", "```sh\n", " $ cargo check\n", " Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)\n", " Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs\n", "```\n", "\n", "## Building for Release\n", "With simple projects, Cargo doesn’t provide a lot of value over just using `rustc`, but it will prove its worth as your programs become more intricate. Once programs grow to multiple files or need a dependency, it’s much easier to let Cargo coordinate the build.\n", "\n", "Even though the `hello_cargo` project is simple, it now uses much of the real tooling you’ll use in the rest of your Rust career. In fact, to work on any existing projects, you can use the following commands to check out the code using Git, change to that project’s directory, and build:\n", "\n", "```sh\n", "$ git clone example.org/someproject\n", "$ cd someproject\n", "$ cargo build\n", "```\n", "
" ] } ], "metadata": { "kernelspec": { "display_name": "Rust", "language": "rust", "name": "rust" }, "language_info": { "codemirror_mode": "rust", "file_extension": ".rs", "mimetype": "text/rust", "name": "Rust", "pygment_lexer": "rust", "version": "" } }, "nbformat": 4, "nbformat_minor": 5 }