66 lines
4.3 KiB
HTML
66 lines
4.3 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<title>Packages and Crates</title>
|
||
</head>
|
||
<body>
|
||
<h2 id="packages-and-crates"><a class="header" href="#packages-and-crates">Packages and Crates</a></h2>
|
||
<p>The first parts of the module system we’ll cover are packages and crates.</p>
|
||
<p>A <em>crate</em> is the smallest amount of code that the Rust compiler considers at a
|
||
time. Even if you run <code>rustc</code> rather than <code>cargo</code> and pass a single source code
|
||
file (as we did all the way back in <a href="../ch01/ch01-02-hello-world.html#rust-program-basics">“Rust Program Basics”</a><!-- ignore
|
||
--> in Chapter 1), the compiler considers that file to be a crate. Crates can
|
||
contain modules, and the modules may be defined in other files that get
|
||
compiled with the crate, as we’ll see in the coming sections.</p>
|
||
<p>A crate can come in one of two forms: a binary crate or a library crate.
|
||
<em>Binary crates</em> are programs you can compile to an executable that you can run,
|
||
such as a command line program or a server. Each must have a function called
|
||
<code>main</code> that defines what happens when the executable runs. All the crates we’ve
|
||
created so far have been binary crates.</p>
|
||
<p><em>Library crates</em> don’t have a <code>main</code> function, and they don’t compile to an
|
||
executable. Instead, they define functionality intended to be shared with
|
||
multiple projects. For example, the <code>rand</code> crate we used in <a href="../ch02/ch02-00-guessing-game-tutorial.html#generating-a-random-number">Chapter
|
||
2</a><!-- ignore --> provides functionality that generates random numbers.
|
||
Most of the time when Rustaceans say “crate,” they mean library crate, and they
|
||
use “crate” interchangeably with the general programming concept of a “library.”</p>
|
||
<p>The <em>crate root</em> is a source file that the Rust compiler starts from and makes
|
||
up the root module of your crate (we’ll explain modules in depth in <a href="ch07-02-defining-modules-to-control-scope-and-privacy.html">“Control
|
||
Scope and Privacy with Modules”</a><!-- ignore -->).</p>
|
||
<p>A <em>package</em> is a bundle of one or more crates that provides a set of
|
||
functionality. A package contains a <em>Cargo.toml</em> file that describes how to
|
||
build those crates. Cargo is actually a package that contains the binary crate
|
||
for the command line tool you’ve been using to build your code. The Cargo
|
||
package also contains a library crate that the binary crate depends on. Other
|
||
projects can depend on the Cargo library crate to use the same logic the Cargo
|
||
command line tool uses.</p>
|
||
<p>A package can contain as many binary crates as you like, but at most only one
|
||
library crate. A package must contain at least one crate, whether that’s a
|
||
library or binary crate.</p>
|
||
<p>Let’s walk through what happens when we create a package. First, we enter the
|
||
command <code>cargo new my-project</code>:</p>
|
||
<pre><code class="language-console">$ cargo new my-project
|
||
Created binary (application) `my-project` package
|
||
$ ls my-project
|
||
Cargo.toml
|
||
src
|
||
$ ls my-project/src
|
||
main.rs
|
||
</code></pre>
|
||
<p>After we run <code>cargo new my-project</code>, we use <code>ls</code> to see what Cargo creates. In
|
||
the <em>my-project</em> directory, there’s a <em>Cargo.toml</em> file, giving us a package.
|
||
There’s also a <em>src</em> directory that contains <em>main.rs</em>. Open <em>Cargo.toml</em> in
|
||
your text editor and note that there’s no mention of <em>src/main.rs</em>. Cargo
|
||
follows a convention that <em>src/main.rs</em> is the crate root of a binary crate
|
||
with the same name as the package. Likewise, Cargo knows that if the package
|
||
directory contains <em>src/lib.rs</em>, the package contains a library crate with the
|
||
same name as the package, and <em>src/lib.rs</em> is its crate root. Cargo passes the
|
||
crate root files to <code>rustc</code> to build the library or binary.</p>
|
||
<p>Here, we have a package that only contains <em>src/main.rs</em>, meaning it only
|
||
contains a binary crate named <code>my-project</code>. If a package contains <em>src/main.rs</em>
|
||
and <em>src/lib.rs</em>, it has two crates: a binary and a library, both with the same
|
||
name as the package. A package can have multiple binary crates by placing files
|
||
in the <em>src/bin</em> directory: Each file will be a separate binary crate.</p>
|
||
</body>
|
||
</html>
|