<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Crates and Modules - The Rust Programming Language</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<base href="">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="src/theme/first-edition.css">
</head>
<body class="light">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li class="affix"><a href="README.html">Introduction</a></li><li><a href="getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><a href="guessing-game.html"><strong aria-hidden="true">2.</strong> Tutorial: Guessing Game</a></li><li><a href="syntax-and-semantics.html"><strong aria-hidden="true">3.</strong> Syntax and Semantics</a></li><li><ol class="section"><li><a href="variable-bindings.html"><strong aria-hidden="true">3.1.</strong> Variable Bindings</a></li><li><a href="functions.html"><strong aria-hidden="true">3.2.</strong> Functions</a></li><li><a href="primitive-types.html"><strong aria-hidden="true">3.3.</strong> Primitive Types</a></li><li><a href="comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li><a href="if.html"><strong aria-hidden="true">3.5.</strong> if</a></li><li><a href="loops.html"><strong aria-hidden="true">3.6.</strong> Loops</a></li><li><a href="vectors.html"><strong aria-hidden="true">3.7.</strong> Vectors</a></li><li><a href="ownership.html"><strong aria-hidden="true">3.8.</strong> Ownership</a></li><li><a href="references-and-borrowing.html"><strong aria-hidden="true">3.9.</strong> References and Borrowing</a></li><li><a href="lifetimes.html"><strong aria-hidden="true">3.10.</strong> Lifetimes</a></li><li><a href="mutability.html"><strong aria-hidden="true">3.11.</strong> Mutability</a></li><li><a href="structs.html"><strong aria-hidden="true">3.12.</strong> Structs</a></li><li><a href="enums.html"><strong aria-hidden="true">3.13.</strong> Enums</a></li><li><a href="match.html"><strong aria-hidden="true">3.14.</strong> Match</a></li><li><a href="patterns.html"><strong aria-hidden="true">3.15.</strong> Patterns</a></li><li><a href="method-syntax.html"><strong aria-hidden="true">3.16.</strong> Method Syntax</a></li><li><a href="strings.html"><strong aria-hidden="true">3.17.</strong> Strings</a></li><li><a href="generics.html"><strong aria-hidden="true">3.18.</strong> Generics</a></li><li><a href="traits.html"><strong aria-hidden="true">3.19.</strong> Traits</a></li><li><a href="drop.html"><strong aria-hidden="true">3.20.</strong> Drop</a></li><li><a href="if-let.html"><strong aria-hidden="true">3.21.</strong> if let</a></li><li><a href="trait-objects.html"><strong aria-hidden="true">3.22.</strong> Trait Objects</a></li><li><a href="closures.html"><strong aria-hidden="true">3.23.</strong> Closures</a></li><li><a href="ufcs.html"><strong aria-hidden="true">3.24.</strong> Universal Function Call Syntax</a></li><li><a href="crates-and-modules.html" class="active"><strong aria-hidden="true">3.25.</strong> Crates and Modules</a></li><li><a href="const-and-static.html"><strong aria-hidden="true">3.26.</strong> const and static</a></li><li><a href="attributes.html"><strong aria-hidden="true">3.27.</strong> Attributes</a></li><li><a href="type-aliases.html"><strong aria-hidden="true">3.28.</strong> type aliases</a></li><li><a href="casting-between-types.html"><strong aria-hidden="true">3.29.</strong> Casting between types</a></li><li><a href="associated-types.html"><strong aria-hidden="true">3.30.</strong> Associated Types</a></li><li><a href="unsized-types.html"><strong aria-hidden="true">3.31.</strong> Unsized Types</a></li><li><a href="operators-and-overloading.html"><strong aria-hidden="true">3.32.</strong> Operators and Overloading</a></li><li><a href="deref-coercions.html"><strong aria-hidden="true">3.33.</strong> Deref coercions</a></li><li><a href="macros.html"><strong aria-hidden="true">3.34.</strong> Macros</a></li><li><a href="raw-pointers.html"><strong aria-hidden="true">3.35.</strong> Raw Pointers</a></li><li><a href="unsafe.html"><strong aria-hidden="true">3.36.</strong> unsafe</a></li></ol></li><li><a href="effective-rust.html"><strong aria-hidden="true">4.</strong> Effective Rust</a></li><li><ol class="section"><li><a href="the-stack-and-the-heap.html"><strong aria-hidden="true">4.1.</strong> The Stack and the Heap</a></li><li><a href="testing.html"><strong aria-hidden="true">4.2.</strong> Testing</a></li><li><a href="conditional-compilation.html"><strong aria-hidden="true">4.3.</strong> Conditional Compilation</a></li><li><a href="documentation.html"><strong aria-hidden="true">4.4.</strong> Documentation</a></li><li><a href="iterators.html"><strong aria-hidden="true">4.5.</strong> Iterators</a></li><li><a href="concurrency.html"><strong aria-hidden="true">4.6.</strong> Concurrency</a></li><li><a href="error-handling.html"><strong aria-hidden="true">4.7.</strong> Error Handling</a></li><li><a href="choosing-your-guarantees.html"><strong aria-hidden="true">4.8.</strong> Choosing your Guarantees</a></li><li><a href="ffi.html"><strong aria-hidden="true">4.9.</strong> FFI</a></li><li><a href="borrow-and-asref.html"><strong aria-hidden="true">4.10.</strong> Borrow and AsRef</a></li><li><a href="release-channels.html"><strong aria-hidden="true">4.11.</strong> Release Channels</a></li><li><a href="using-rust-without-the-standard-library.html"><strong aria-hidden="true">4.12.</strong> Using Rust without the standard library</a></li><li><a href="procedural-macros.html"><strong aria-hidden="true">4.13.</strong> Procedural Macros (and custom derive)</a></li></ol></li><li><a href="glossary.html"><strong aria-hidden="true">5.</strong> Glossary</a></li><li><a href="syntax-index.html"><strong aria-hidden="true">6.</strong> Syntax Index</a></li><li><a href="bibliography.html"><strong aria-hidden="true">7.</strong> Bibliography</a></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="draft-warning" class="warning">
<span class="message">You are reading an <strong>outdated</strong> edition of TRPL. For more, go <a href="../index.html">here</a>.</span>
<button type="button" id="hide-draft-warning" title="Hide draft warning" class="button">
<i class="fa fa-times"></i>
</button>
</div>
<!-- Hide / unhide warning before it is displayed -->
<script type="text/javascript">
var warning = localStorage.getItem('trpl-first-edition-draft-warning');
if (warning === 'hidden') {
Array
.from(document.querySelectorAll('#page-wrapper'))
.forEach(function(block) { block.classList.remove('has-warning'); });
var elem = document.getElementById("draft-warning");
elem.parentNode.removeChild(elem);
}
document.addEventListener("DOMContentLoaded", function(event) {
document.getElementById("hide-draft-warning").addEventListener("click", function(e) {
var elem = document.getElementById("draft-warning");
elem.parentNode.removeChild(elem);
localStorage.setItem('trpl-first-edition-draft-warning', 'hidden');
});
});
</script>
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="crates-and-modules.html#crates-and-modules" id="crates-and-modules"><h1>Crates and Modules</h1></a>
<p>When a project starts getting large, it’s considered good software
engineering practice to split it up into a bunch of smaller pieces, and then
fit them together. It is also important to have a well-defined interface, so
that some of your functionality is private, and some is public. To facilitate
these kinds of things, Rust has a module system.</p>
<a class="header" href="crates-and-modules.html#basic-terminology-crates-and-modules" id="basic-terminology-crates-and-modules"><h1>Basic terminology: Crates and Modules</h1></a>
<p>Rust has two distinct terms that relate to the module system: ‘crate’ and
‘module’. A crate is synonymous with a ‘library’ or ‘package’ in other
languages. Hence “Cargo” as the name of Rust’s package management tool: you
ship your crates to others with Cargo. Crates can produce an executable or a
library, depending on the project.</p>
<p>Each crate has an implicit <em>root module</em> that contains the code for that crate.
You can then define a tree of sub-modules under that root module. Modules allow
you to partition your code within the crate itself.</p>
<p>As an example, let’s make a <em>phrases</em> crate, which will give us various phrases
in different languages. To keep things simple, we’ll stick to ‘greetings’ and
‘farewells’ as two kinds of phrases, and use English and Japanese (日本語) as
two languages for those phrases to be in. We’ll use this module layout:</p>
<pre><code class="language-text"> +-----------+
+---| greetings |
+---------+ | +-----------+
+---| english |---+
| +---------+ | +-----------+
| +---| farewells |
+---------+ | +-----------+
| phrases |---+
+---------+ | +-----------+
| +---| greetings |
| +----------+ | +-----------+
+---| japanese |--+
+----------+ | +-----------+
+---| farewells |
+-----------+
</code></pre>
<p>In this example, <code>phrases</code> is the name of our crate. All of the rest are
modules. You can see that they form a tree, branching out from the crate
<em>root</em>, which is the root of the tree: <code>phrases</code> itself.</p>
<p>Now that we have a plan, let’s define these modules in code. To start,
generate a new crate with Cargo:</p>
<pre><code class="language-bash">$ cargo new phrases
$ cd phrases
</code></pre>
<p>If you remember, this generates a simple project for us:</p>
<pre><code class="language-bash">$ tree .
.
├── Cargo.toml
└── src
└── lib.rs
1 directory, 2 files
</code></pre>
<p><code>src/lib.rs</code> is our crate root, corresponding to the <code>phrases</code> in our diagram
above.</p>
<a class="header" href="crates-and-modules.html#defining-modules" id="defining-modules"><h1>Defining Modules</h1></a>
<p>To define each of our modules, we use the <code>mod</code> keyword. Let’s make our
<code>src/lib.rs</code> look like this:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
mod english {
mod greetings {
}
mod farewells {
}
}
mod japanese {
mod greetings {
}
mod farewells {
}
}
#}</code></pre></pre>
<p>After the <code>mod</code> keyword, you give the name of the module. Module names follow
the conventions for other Rust identifiers: <code>lower_snake_case</code>. The contents of
each module are within curly braces (<code>{}</code>).</p>
<p>Within a given <code>mod</code>, you can declare sub-<code>mod</code>s. We can refer to sub-modules
with double-colon (<code>::</code>) notation: our four nested modules are
<code>english::greetings</code>, <code>english::farewells</code>, <code>japanese::greetings</code>, and
<code>japanese::farewells</code>. Because these sub-modules are namespaced under their
parent module, the names don’t conflict: <code>english::greetings</code> and
<code>japanese::greetings</code> are distinct, even though their names are both
<code>greetings</code>.</p>
<p>Because this crate does not have a <code>main()</code> function, and is called <code>lib.rs</code>,
Cargo will build this crate as a library:</p>
<pre><code class="language-bash">$ cargo build
Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
$ ls target/debug
build deps examples libphrases-a7448e02a0468eaa.rlib native
</code></pre>
<p><code>libphrases-<hash>.rlib</code> is the compiled crate. Before we see how to use this
crate from another crate, let’s break it up into multiple files.</p>
<a class="header" href="crates-and-modules.html#multiple-file-crates" id="multiple-file-crates"><h1>Multiple File Crates</h1></a>
<p>If each crate were just one file, these files would get very large. It’s often
easier to split up crates into multiple files, and Rust supports this in two
ways.</p>
<p>Instead of declaring a module like this:</p>
<pre><code class="language-rust ignore">mod english {
// Contents of our module go here.
}
</code></pre>
<p>We can instead declare our module like this:</p>
<pre><code class="language-rust ignore">mod english;
</code></pre>
<p>If we do that, Rust will expect to find either a <code>english.rs</code> file, or a
<code>english/mod.rs</code> file with the contents of our module.</p>
<p>Note that in these files, you don’t need to re-declare the module: that’s
already been done with the initial <code>mod</code> declaration.</p>
<p>Using these two techniques, we can break up our crate into two directories and
seven files:</p>
<pre><code class="language-bash">$ tree .
.
├── Cargo.lock
├── Cargo.toml
├── src
│ ├── english
│ │ ├── farewells.rs
│ │ ├── greetings.rs
│ │ └── mod.rs
│ ├── japanese
│ │ ├── farewells.rs
│ │ ├── greetings.rs
│ │ └── mod.rs
│ └── lib.rs
└── target
└── debug
├── build
├── deps
├── examples
├── libphrases-a7448e02a0468eaa.rlib
└── native
</code></pre>
<p><code>src/lib.rs</code> is our crate root, and looks like this:</p>
<pre><code class="language-rust ignore">mod english;
mod japanese;
</code></pre>
<p>These two declarations tell Rust to look for</p>
<ul>
<li>either <code>src/english.rs</code> or <code>src/english/mod.rs</code>, and</li>
<li>either <code>src/japanese.rs</code> or <code>src/japanese/mod.rs</code>,</li>
</ul>
<p>depending on our preference. In this case, because our modules have sub-modules,
we’ve chosen the <code>mod.rs</code> approach. Both <code>src/english/mod.rs</code> and
<code>src/japanese/mod.rs</code> look like this:</p>
<pre><code class="language-rust ignore">mod greetings;
mod farewells;
</code></pre>
<p>Again, these declarations tell Rust to look for</p>
<ul>
<li><code>src/english/greetings.rs</code> or <code>src/english/greetings/mod.rs</code>,</li>
<li><code>src/english/farewells.rs</code> or <code>src/english/farewells/mod.rs</code>,</li>
<li><code>src/japanese/greetings.rs</code> or <code>src/japanese/greetings/mod.rs</code>,</li>
<li>and <code>src/japanese/farewells.rs</code> or <code>src/japanese/farewells/mod.rs</code>.</li>
</ul>
<p>Because these sub-modules don’t have
their own sub-modules, we’ve chosen to make them
<code>src/english/greetings.rs</code>, <code>src/english/farewells.rs</code>,
<code>src/japanese/greetings.rs</code> and <code>src/japanese/farewells.rs</code>. Whew!</p>
<p>The contents of <code>src/english/greetings.rs</code>,
<code>src/english/farewells.rs</code>, <code>src/japanese/greetings.rs</code> and
<code>src/japanese/farewells.rs</code> are all empty at the moment. Let’s add
some functions.</p>
<p>Put this in <code>src/english/greetings.rs</code>:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
fn hello() -> String {
"Hello!".to_string()
}
#}</code></pre></pre>
<p>Put this in <code>src/english/farewells.rs</code>:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
fn goodbye() -> String {
"Goodbye.".to_string()
}
#}</code></pre></pre>
<p>Put this in <code>src/japanese/greetings.rs</code>:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
fn hello() -> String {
"こんにちは".to_string()
}
#}</code></pre></pre>
<p>Of course, you can copy and paste this from this web page, or type
something else. It’s not important that you actually put ‘konnichiwa’ to learn
about the module system.</p>
<p>Put this in <code>src/japanese/farewells.rs</code>:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
fn goodbye() -> String {
"さようなら".to_string()
}
#}</code></pre></pre>
<p>(This is ‘Sayōnara’, if you’re curious.)</p>
<p>Now that we have some functionality in our crate, let’s try to use it from
another crate.</p>
<a class="header" href="crates-and-modules.html#importing-external-crates" id="importing-external-crates"><h1>Importing External Crates</h1></a>
<p>We have a library crate. Let’s make an executable crate that imports and uses
our library.</p>
<p>Make a <code>src/main.rs</code> and put this in it (it won’t quite compile yet):</p>
<pre><code class="language-rust ignore">extern crate phrases;
fn main() {
println!("Hello in English: {}", phrases::english::greetings::hello());
println!("Goodbye in English: {}", phrases::english::farewells::goodbye());
println!("Hello in Japanese: {}", phrases::japanese::greetings::hello());
println!("Goodbye in Japanese: {}", phrases::japanese::farewells::goodbye());
}
</code></pre>
<p>The <code>extern crate</code> declaration tells Rust that we need to compile and link to
the <code>phrases</code> crate. We can then use <code>phrases</code>’ modules in this one. As we
mentioned earlier, you can use double colons to refer to sub-modules and the
functions inside of them.</p>
<p>(Note: when importing a crate that has dashes in its name "like-this", which is
not a valid Rust identifier, it will be converted by changing the dashes to
underscores, so you would write <code>extern crate like_this;</code>.)</p>
<p>Also, Cargo assumes that <code>src/main.rs</code> is the crate root of a binary crate,
rather than a library crate. Our package now has two crates: <code>src/lib.rs</code> and
<code>src/main.rs</code>. This pattern is quite common for executable crates: most
functionality is in a library crate, and the executable crate uses that
library. This way, other programs can also use the library crate, and it’s also
a nice separation of concerns.</p>
<p>This doesn’t quite work yet, though. We get four errors that look similar to
this:</p>
<pre><code class="language-bash">$ cargo build
Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
src/main.rs:4:38: 4:72 error: function `hello` is private
src/main.rs:4 println!("Hello in English: {}", phrases::english::greetings::hello());
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
note: in expansion of format_args!
<std macros>:2:25: 2:58 note: expansion site
<std macros>:1:1: 2:62 note: in expansion of print!
<std macros>:3:1: 3:54 note: expansion site
<std macros>:1:1: 3:58 note: in expansion of println!
phrases/src/main.rs:4:5: 4:76 note: expansion site
</code></pre>
<p>By default, everything is private in Rust. Let’s talk about this in some more
depth.</p>
<a class="header" href="crates-and-modules.html#exporting-a-public-interface" id="exporting-a-public-interface"><h1>Exporting a Public Interface</h1></a>
<p>Rust allows you to precisely control which aspects of your interface are
public, and so private is the default. To make things public, you use the <code>pub</code>
keyword. Let’s focus on the <code>english</code> module first, so let’s reduce our <code>src/main.rs</code>
to only this:</p>
<pre><code class="language-rust ignore">extern crate phrases;
fn main() {
println!("Hello in English: {}", phrases::english::greetings::hello());
println!("Goodbye in English: {}", phrases::english::farewells::goodbye());
}
</code></pre>
<p>In our <code>src/lib.rs</code>, let’s add <code>pub</code> to the <code>english</code> module declaration:</p>
<pre><code class="language-rust ignore">pub mod english;
mod japanese;
</code></pre>
<p>And in our <code>src/english/mod.rs</code>, let’s make both <code>pub</code>:</p>
<pre><code class="language-rust ignore">pub mod greetings;
pub mod farewells;
</code></pre>
<p>In our <code>src/english/greetings.rs</code>, let’s add <code>pub</code> to our <code>fn</code> declaration:</p>
<pre><code class="language-rust ignore">pub fn hello() -> String {
"Hello!".to_string()
}
</code></pre>
<p>And also in <code>src/english/farewells.rs</code>:</p>
<pre><code class="language-rust ignore">pub fn goodbye() -> String {
"Goodbye.".to_string()
}
</code></pre>
<p>Now, our crate compiles, albeit with warnings about not using the <code>japanese</code>
functions:</p>
<pre><code class="language-bash">$ cargo run
Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
src/japanese/greetings.rs:1:1: 3:2 warning: function is never used: `hello`, #[warn(dead_code)] on by default
src/japanese/greetings.rs:1 fn hello() -> String {
src/japanese/greetings.rs:2 "こんにちは".to_string()
src/japanese/greetings.rs:3 }
src/japanese/farewells.rs:1:1: 3:2 warning: function is never used: `goodbye`, #[warn(dead_code)] on by default
src/japanese/farewells.rs:1 fn goodbye() -> String {
src/japanese/farewells.rs:2 "さようなら".to_string()
src/japanese/farewells.rs:3 }
Running `target/debug/phrases`
Hello in English: Hello!
Goodbye in English: Goodbye.
</code></pre>
<p><code>pub</code> also applies to <code>struct</code>s and their member fields. In keeping with Rust’s
tendency toward safety, simply making a <code>struct</code> public won't automatically
make its members public: you must mark the fields individually with <code>pub</code>.</p>
<p>Now that our functions are public, we can use them. Great! However, typing out
<code>phrases::english::greetings::hello()</code> is very long and repetitive. Rust has
another keyword for importing names into the current scope, so that you can
refer to them with shorter names. Let’s talk about <code>use</code>.</p>
<a class="header" href="crates-and-modules.html#importing-modules-with-use" id="importing-modules-with-use"><h1>Importing Modules with <code>use</code></h1></a>
<p>Rust has a <code>use</code> keyword, which allows us to import names into our local scope.
Let’s change our <code>src/main.rs</code> to look like this:</p>
<pre><code class="language-rust ignore">extern crate phrases;
use phrases::english::greetings;
use phrases::english::farewells;
fn main() {
println!("Hello in English: {}", greetings::hello());
println!("Goodbye in English: {}", farewells::goodbye());
}
</code></pre>
<p>The two <code>use</code> lines import each module into the local scope, so we can refer to
the functions by a much shorter name. By convention, when importing functions, it’s
considered best practice to import the module, rather than the function directly. In
other words, you <em>can</em> do this:</p>
<pre><code class="language-rust ignore">extern crate phrases;
use phrases::english::greetings::hello;
use phrases::english::farewells::goodbye;
fn main() {
println!("Hello in English: {}", hello());
println!("Goodbye in English: {}", goodbye());
}
</code></pre>
<p>But it is not idiomatic. This is significantly more likely to introduce a
naming conflict. In our short program, it’s not a big deal, but as it grows, it
becomes a problem. If we have conflicting names, Rust will give a compilation
error. For example, if we made the <code>japanese</code> functions public, and tried to do
this:</p>
<pre><code class="language-rust ignore">extern crate phrases;
use phrases::english::greetings::hello;
use phrases::japanese::greetings::hello;
fn main() {
println!("Hello in English: {}", hello());
println!("Hello in Japanese: {}", hello());
}
</code></pre>
<p>Rust will give us a compile-time error:</p>
<pre><code class="language-text"> Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
src/main.rs:4:5: 4:40 error: a value named `hello` has already been imported in this module [E0252]
src/main.rs:4 use phrases::japanese::greetings::hello;
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
error: aborting due to previous error
Could not compile `phrases`.
</code></pre>
<p>If we’re importing multiple names from the same module, we don’t have to type it out
twice. Instead of this:</p>
<pre><code class="language-rust ignore">use phrases::english::greetings;
use phrases::english::farewells;
</code></pre>
<p>We can use this shortcut:</p>
<pre><code class="language-rust ignore">use phrases::english::{greetings, farewells};
</code></pre>
<a class="header" href="crates-and-modules.html#re-exporting-with-pub-use" id="re-exporting-with-pub-use"><h2>Re-exporting with <code>pub use</code></h2></a>
<p>You don’t only use <code>use</code> to shorten identifiers. You can also use it inside of your crate
to re-export a function inside another module. This allows you to present an external
interface that may not directly map to your internal code organization.</p>
<p>Let’s look at an example. Modify your <code>src/main.rs</code> to read like this:</p>
<pre><code class="language-rust ignore">extern crate phrases;
use phrases::english::{greetings,farewells};
use phrases::japanese;
fn main() {
println!("Hello in English: {}", greetings::hello());
println!("Goodbye in English: {}", farewells::goodbye());
println!("Hello in Japanese: {}", japanese::hello());
println!("Goodbye in Japanese: {}", japanese::goodbye());
}
</code></pre>
<p>Then, modify your <code>src/lib.rs</code> to make the <code>japanese</code> mod public:</p>
<pre><code class="language-rust ignore">pub mod english;
pub mod japanese;
</code></pre>
<p>Next, make the two functions public, first in <code>src/japanese/greetings.rs</code>:</p>
<pre><code class="language-rust ignore">pub fn hello() -> String {
"こんにちは".to_string()
}
</code></pre>
<p>And then in <code>src/japanese/farewells.rs</code>:</p>
<pre><code class="language-rust ignore">pub fn goodbye() -> String {
"さようなら".to_string()
}
</code></pre>
<p>Finally, modify your <code>src/japanese/mod.rs</code> to read like this:</p>
<pre><code class="language-rust ignore">pub use self::greetings::hello;
pub use self::farewells::goodbye;
mod greetings;
mod farewells;
</code></pre>
<p>The <code>pub use</code> declaration brings the function into scope at this part of our
module hierarchy. Because we’ve <code>pub use</code>d this inside of our <code>japanese</code>
module, we now have a <code>phrases::japanese::hello()</code> function and a
<code>phrases::japanese::goodbye()</code> function, even though the code for them lives in
<code>phrases::japanese::greetings::hello()</code> and
<code>phrases::japanese::farewells::goodbye()</code>. Our internal organization doesn’t
define our external interface.</p>
<p>Here we have a <code>pub use</code> for each function we want to bring into the
<code>japanese</code> scope. We could alternatively use the wildcard syntax to include
everything from <code>greetings</code> into the current scope: <code>pub use self::greetings::*</code>.</p>
<p>What about the <code>self</code>? Well, by default, <code>use</code> declarations are absolute paths,
starting from your crate root. <code>self</code> makes that path relative to your current
place in the hierarchy instead. There’s one more special form of <code>use</code>: you can
<code>use super::</code> to reach one level up the tree from your current location. Some
people like to think of <code>self</code> as <code>.</code> and <code>super</code> as <code>..</code>, from many shells’
display for the current directory and the parent directory.</p>
<p>Outside of <code>use</code>, paths are relative: <code>foo::bar()</code> refers to a function inside
of <code>foo</code> relative to where we are. If that’s prefixed with <code>::</code>, as in
<code>::foo::bar()</code>, it refers to a different <code>foo</code>, an absolute path from your
crate root.</p>
<p>This will build and run:</p>
<pre><code class="language-bash">$ cargo run
Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
Running `target/debug/phrases`
Hello in English: Hello!
Goodbye in English: Goodbye.
Hello in Japanese: こんにちは
Goodbye in Japanese: さようなら
</code></pre>
<a class="header" href="crates-and-modules.html#complex-imports" id="complex-imports"><h2>Complex imports</h2></a>
<p>Rust offers several advanced options that can add compactness and
convenience to your <code>extern crate</code> and <code>use</code> statements. Here is an example:</p>
<pre><code class="language-rust ignore">extern crate phrases as sayings;
use sayings::japanese::greetings as ja_greetings;
use sayings::japanese::farewells::*;
use sayings::english::{self, greetings as en_greetings, farewells as en_farewells};
fn main() {
println!("Hello in English; {}", en_greetings::hello());
println!("And in Japanese: {}", ja_greetings::hello());
println!("Goodbye in English: {}", english::farewells::goodbye());
println!("Again: {}", en_farewells::goodbye());
println!("And in Japanese: {}", goodbye());
}
</code></pre>
<p>What's going on here?</p>
<p>First, both <code>extern crate</code> and <code>use</code> allow renaming the thing that is being
imported. So the crate is still called "phrases", but here we will refer
to it as "sayings". Similarly, the first <code>use</code> statement pulls in the
<code>japanese::greetings</code> module from the crate, but makes it available as
<code>ja_greetings</code> as opposed to simply <code>greetings</code>. This can help to avoid
ambiguity when importing similarly-named items from different places.</p>
<p>The second <code>use</code> statement uses a star glob to bring in all public symbols from
the <code>sayings::japanese::farewells</code> module. As you can see we can later refer to
the Japanese <code>goodbye</code> function with no module qualifiers. This kind of glob
should be used sparingly. It’s worth noting that it only imports the public
symbols, even if the code doing the globbing is in the same module.</p>
<p>The third <code>use</code> statement bears more explanation. It's using "brace expansion"
globbing to compress three <code>use</code> statements into one (this sort of syntax
may be familiar if you've written Linux shell scripts before). The
uncompressed form of this statement would be:</p>
<pre><code class="language-rust ignore">use sayings::english;
use sayings::english::greetings as en_greetings;
use sayings::english::farewells as en_farewells;
</code></pre>
<p>As you can see, the curly brackets compress <code>use</code> statements for several items
under the same path, and in this context <code>self</code> refers back to that path.
Note: The curly brackets cannot be nested or mixed with star globbing.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ufcs.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="const-and-static.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="ufcs.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="const-and-static.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
