<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>`mod` and the Filesystem - 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">
<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 rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<style>
.page-wrapper.has-warning > .nav-chapters {
/* add height for warning content & margin */
top: 120px;
}
p.warning {
background-color: rgb(242, 222, 222);
border-bottom-color: rgb(238, 211, 215);
border-bottom-left-radius: 4px;
border-bottom-right-radius: 4px;
border-bottom-style: solid;
border-bottom-width: 0.666667px;
border-image-outset: 0 0 0 0;
border-image-repeat: stretch stretch;
border-image-slice: 100% 100% 100% 100%;
border-image-source: none;
border-image-width: 1 1 1 1;
border-left-color: rgb(238, 211, 215);
border-left-style: solid;
border-left-width: 0.666667px;
border-right-color: rgb(238, 211, 215);
border-right-style: solid;
border-right-width: 0.666667px;
border-top-color: rgb(238, 211, 215);
border-top-left-radius: 4px;
border-top-right-radius: 4px;
border-top-style: solid;
border-top-width: 0.666667px;
color: rgb(185, 74, 72);
margin-bottom: 0px;
margin-left: 0px;
margin-right: 0px;
margin-top: 30px;
padding-bottom: 8px;
padding-left: 14px;
padding-right: 35px;
padding-top: 8px;
}
p.warning strong {
color: rgb(185, 74, 72)
}
p.warning a {
color: rgb(0, 136, 204)
}
</style>
<!-- MathJax -->
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<!-- Fetch JQuery from CDN but have a local fallback -->
<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script>
if (typeof jQuery == 'undefined') {
document.write(unescape("%3Cscript src='jquery.js'%3E%3C/script%3E"));
}
</script>
</head>
<body class="light">
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme = localStorage.getItem('theme');
if (theme == null) { theme = 'light'; }
$('body').removeClass().addClass(theme);
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var sidebar = localStorage.getItem('sidebar');
if (sidebar === "hidden") { $("html").addClass("sidebar-hidden") }
else if (sidebar === "visible") { $("html").addClass("sidebar-visible") }
</script>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="ch01-00-introduction.html"><strong>1.</strong> Introduction</a></li><li><ul class="section"><li><a href="ch01-01-installation.html"><strong>1.1.</strong> Installation</a></li><li><a href="ch01-02-hello-world.html"><strong>1.2.</strong> Hello, World!</a></li></ul></li><li><a href="ch02-00-guessing-game-tutorial.html"><strong>2.</strong> Guessing Game Tutorial</a></li><li><a href="ch03-00-common-programming-concepts.html"><strong>3.</strong> Common Programming Concepts</a></li><li><ul class="section"><li><a href="ch03-01-variables-and-mutability.html"><strong>3.1.</strong> Variables and Mutability</a></li><li><a href="ch03-02-data-types.html"><strong>3.2.</strong> Data Types</a></li><li><a href="ch03-03-how-functions-work.html"><strong>3.3.</strong> How Functions Work</a></li><li><a href="ch03-04-comments.html"><strong>3.4.</strong> Comments</a></li><li><a href="ch03-05-control-flow.html"><strong>3.5.</strong> Control Flow</a></li></ul></li><li><a href="ch04-00-understanding-ownership.html"><strong>4.</strong> Understanding Ownership</a></li><li><ul class="section"><li><a href="ch04-01-what-is-ownership.html"><strong>4.1.</strong> What is Ownership?</a></li><li><a href="ch04-02-references-and-borrowing.html"><strong>4.2.</strong> References & Borrowing</a></li><li><a href="ch04-03-slices.html"><strong>4.3.</strong> Slices</a></li></ul></li><li><a href="ch05-00-structs.html"><strong>5.</strong> Using Structs to Structure Related Data</a></li><li><ul class="section"><li><a href="ch05-01-defining-structs.html"><strong>5.1.</strong> Defining and Instantiating Structs</a></li><li><a href="ch05-02-example-structs.html"><strong>5.2.</strong> An Example Program Using Structs</a></li><li><a href="ch05-03-method-syntax.html"><strong>5.3.</strong> Method Syntax</a></li></ul></li><li><a href="ch06-00-enums.html"><strong>6.</strong> Enums and Pattern Matching</a></li><li><ul class="section"><li><a href="ch06-01-defining-an-enum.html"><strong>6.1.</strong> Defining an Enum</a></li><li><a href="ch06-02-match.html"><strong>6.2.</strong> The <code>match</code> Control Flow Operator</a></li><li><a href="ch06-03-if-let.html"><strong>6.3.</strong> Concise Control Flow with <code>if let</code></a></li></ul></li><li><a href="ch07-00-modules.html"><strong>7.</strong> Modules</a></li><li><ul class="section"><li><a href="ch07-01-mod-and-the-filesystem.html" class="active"><strong>7.1.</strong> <code>mod</code> and the Filesystem</a></li><li><a href="ch07-02-controlling-visibility-with-pub.html"><strong>7.2.</strong> Controlling Visibility with <code>pub</code></a></li><li><a href="ch07-03-importing-names-with-use.html"><strong>7.3.</strong> Importing Names with <code>use</code></a></li></ul></li><li><a href="ch08-00-common-collections.html"><strong>8.</strong> Common Collections</a></li><li><ul class="section"><li><a href="ch08-01-vectors.html"><strong>8.1.</strong> Vectors</a></li><li><a href="ch08-02-strings.html"><strong>8.2.</strong> Strings</a></li><li><a href="ch08-03-hash-maps.html"><strong>8.3.</strong> Hash Maps</a></li></ul></li><li><a href="ch09-00-error-handling.html"><strong>9.</strong> Error Handling</a></li><li><ul class="section"><li><a href="ch09-01-unrecoverable-errors-with-panic.html"><strong>9.1.</strong> Unrecoverable Errors with <code>panic!</code></a></li><li><a href="ch09-02-recoverable-errors-with-result.html"><strong>9.2.</strong> Recoverable Errors with <code>Result</code></a></li><li><a href="ch09-03-to-panic-or-not-to-panic.html"><strong>9.3.</strong> To <code>panic!</code> or Not To <code>panic!</code></a></li></ul></li><li><a href="ch10-00-generics.html"><strong>10.</strong> Generic Types, Traits, and Lifetimes</a></li><li><ul class="section"><li><a href="ch10-01-syntax.html"><strong>10.1.</strong> Generic Data Types</a></li><li><a href="ch10-02-traits.html"><strong>10.2.</strong> Traits: Defining Shared Behavior</a></li><li><a href="ch10-03-lifetime-syntax.html"><strong>10.3.</strong> Validating References with Lifetimes</a></li></ul></li><li><a href="ch11-00-testing.html"><strong>11.</strong> Testing</a></li><li><ul class="section"><li><a href="ch11-01-writing-tests.html"><strong>11.1.</strong> Writing tests</a></li><li><a href="ch11-02-running-tests.html"><strong>11.2.</strong> Running tests</a></li><li><a href="ch11-03-test-organization.html"><strong>11.3.</strong> Test Organization</a></li></ul></li><li><a href="ch12-00-an-io-project.html"><strong>12.</strong> An I/O Project</a></li><li><ul class="section"><li><a href="ch12-01-accepting-command-line-arguments.html"><strong>12.1.</strong> Accepting Command Line Arguments</a></li><li><a href="ch12-02-reading-a-file.html"><strong>12.2.</strong> Reading a File</a></li><li><a href="ch12-03-improving-error-handling-and-modularity.html"><strong>12.3.</strong> Improving Error Handling and Modularity</a></li><li><a href="ch12-04-testing-the-librarys-functionality.html"><strong>12.4.</strong> Testing the Library's Functionality</a></li><li><a href="ch12-05-working-with-environment-variables.html"><strong>12.5.</strong> Working with Environment Variables</a></li><li><a href="ch12-06-writing-to-stderr-instead-of-stdout.html"><strong>12.6.</strong> Writing to <code>stderr</code> instead of <code>stdout</code></a></li></ul></li><li><a href="ch13-00-functional-features.html"><strong>13.</strong> Functional Language Features in Rust</a></li><li><ul class="section"><li><a href="ch13-01-closures.html"><strong>13.1.</strong> Closures</a></li><li><a href="ch13-02-iterators.html"><strong>13.2.</strong> Iterators</a></li><li><a href="ch13-03-improving-our-io-project.html"><strong>13.3.</strong> Improving our I/O Project</a></li><li><a href="ch13-04-performance.html"><strong>13.4.</strong> Performance</a></li></ul></li><li><a href="ch14-00-more-about-cargo.html"><strong>14.</strong> More about Cargo and Crates.io</a></li><li><ul class="section"><li><a href="ch14-01-release-profiles.html"><strong>14.1.</strong> Release Profiles</a></li><li><a href="ch14-02-publishing-to-crates-io.html"><strong>14.2.</strong> Publishing a Crate to Crates.io</a></li><li><a href="ch14-03-cargo-workspaces.html"><strong>14.3.</strong> Cargo Workspaces</a></li><li><a href="ch14-04-installing-binaries.html"><strong>14.4.</strong> Installing Binaries from Crates.io with <code>cargo install</code></a></li><li><a href="ch14-05-extending-cargo.html"><strong>14.5.</strong> Extending Cargo with Custom Commands</a></li></ul></li><li><a href="ch15-00-smart-pointers.html"><strong>15.</strong> Smart Pointers</a></li><li><ul class="section"><li><a href="ch15-01-box.html"><strong>15.1.</strong> <code>Box<T></code> Points to Data on the Heap and Has a Known Size</a></li><li><a href="ch15-02-deref.html"><strong>15.2.</strong> The <code>Deref</code> Trait Allows Access to the Data Through a Reference</a></li><li><a href="ch15-03-drop.html"><strong>15.3.</strong> The <code>Drop</code> Trait Runs Code on Cleanup</a></li><li><a href="ch15-04-rc.html"><strong>15.4.</strong> <code>Rc<T></code>, the Reference Counted Smart Pointer</a></li><li><a href="ch15-05-interior-mutability.html"><strong>15.5.</strong> <code>RefCell<T></code> and the Interior Mutability Pattern</a></li><li><a href="ch15-06-reference-cycles.html"><strong>15.6.</strong> Creating Reference Cycles and Leaking Memory is Safe</a></li></ul></li><li><a href="ch16-00-concurrency.html"><strong>16.</strong> Fearless Concurrency</a></li><li><ul class="section"><li><a href="ch16-01-threads.html"><strong>16.1.</strong> Threads</a></li><li><a href="ch16-02-message-passing.html"><strong>16.2.</strong> Message Passing</a></li><li><a href="ch16-03-shared-state.html"><strong>16.3.</strong> Shared State</a></li><li><a href="ch16-04-extensible-concurrency-sync-and-send.html"><strong>16.4.</strong> Extensible Concurrency: <code>Sync</code> and <code>Send</code></a></li></ul></li><li><a href="ch17-00-oop.html"><strong>17.</strong> Is Rust an Object-Oriented Programming Language?</a></li><li><ul class="section"><li><a href="ch17-01-what-is-oo.html"><strong>17.1.</strong> What Does Object-Oriented Mean?</a></li><li><a href="ch17-02-trait-objects.html"><strong>17.2.</strong> Trait Objects for Using Values of Different Types</a></li><li><a href="ch17-03-oo-design-patterns.html"><strong>17.3.</strong> Object-Oriented Design Pattern Implementations</a></li></ul></li><li><a href="ch18-00-patterns.html"><strong>18.</strong> Patterns Match the Structure of Values</a></li><li><ul class="section"><li><a href="ch18-01-all-the-places-for-patterns.html"><strong>18.1.</strong> All the Places Patterns May be Used</a></li><li><a href="ch18-02-refutability.html"><strong>18.2.</strong> Refutability: Whether a Pattern Might Fail to Match</a></li><li><a href="ch18-03-pattern-syntax.html"><strong>18.3.</strong> All the Pattern Syntax</a></li></ul></li><li><a href="ch19-00-advanced-features.html"><strong>19.</strong> Advanced Features</a></li><li><ul class="section"><li><a href="ch19-01-unsafe-rust.html"><strong>19.1.</strong> Unsafe Rust</a></li><li><a href="ch19-02-advanced-lifetimes.html"><strong>19.2.</strong> Advanced Lifetimes</a></li><li><a href="ch19-03-advanced-traits.html"><strong>19.3.</strong> Advanced Traits</a></li><li><a href="ch19-04-advanced-types.html"><strong>19.4.</strong> Advanced Types</a></li><li><a href="ch19-05-advanced-functions-and-closures.html"><strong>19.5.</strong> Advanced Functions & Closures</a></li></ul></li><li><a href="ch20-00-final-project-a-web-server.html"><strong>20.</strong> Final Project: Building a Multithreaded Web Server</a></li><li><ul class="section"><li><a href="ch20-01-single-threaded.html"><strong>20.1.</strong> A Single Threaded Web Server</a></li><li><a href="ch20-02-slow-requests.html"><strong>20.2.</strong> How Slow Requests Affect Throughput</a></li><li><a href="ch20-03-designing-the-interface.html"><strong>20.3.</strong> Designing the Thread Pool Interface</a></li><li><a href="ch20-04-storing-threads.html"><strong>20.4.</strong> Creating the Thread Pool and Storing Threads</a></li><li><a href="ch20-05-sending-requests-via-channels.html"><strong>20.5.</strong> Sending Requests to Threads Via Channels</a></li><li><a href="ch20-06-graceful-shutdown-and-cleanup.html"><strong>20.6.</strong> Graceful Shutdown and Cleanup</a></li></ul></li><li><a href="appendix-00.html"><strong>21.</strong> Appendix</a></li><li><ul class="section"><li><a href="appendix-01-keywords.html"><strong>21.1.</strong> A - Keywords</a></li><li><a href="appendix-02-operators.html"><strong>21.2.</strong> B - Operators</a></li><li><strong>21.3.</strong> C - Derivable Traits</li><li><strong>21.4.</strong> D - Nightly Rust</li><li><strong>21.5.</strong> E - Macros</li><li><strong>21.6.</strong> F - Translations</li><li><a href="appendix-07-newest-features.html"><strong>21.7.</strong> G - Newest Features</a></li></ul></li></ul>
</div>
<div id="page-wrapper" class="page-wrapper has-warning">
<div class="page">
<header><p class="warning">You are reading a <strong>draft</strong> of the next edition of TRPL. For more, go <a href="../index.html">here</a>.</p></header>
<div id="menu-bar" class="menu-bar">
<div class="left-buttons">
<i id="sidebar-toggle" class="fa fa-bars"></i>
<i id="theme-toggle" class="fa fa-paint-brush"></i>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<i id="print-button" class="fa fa-print" title="Print this book"></i>
</div>
</div>
<div id="content" class="content">
<a class="header" href="ch07-01-mod-and-the-filesystem.html#mod-and-the-filesystem" id="mod-and-the-filesystem"><h2><code>mod</code> and the Filesystem</h2></a>
<p>We’ll start our module example by making a new project with Cargo, but instead
of creating a binary crate, we’ll make a library crate: a project that other
people can pull into their projects as a dependency. For example, the <code>rand</code>
crate in Chapter 2 is a library crate that we used as a dependency in the
guessing game project.</p>
<p>We’ll create a skeleton of a library that provides some general networking
functionality; we’ll concentrate on the organization of the modules and
functions but we won’t worry about what code goes in the function bodies. We’ll
call our library <code>communicator</code>. By default, Cargo will create a library unless
another type of project is specified: if we omit the <code>--bin</code> option that we’ve
been using in all of the chapters preceding this one, our project will be a
library:</p>
<pre><code class="language-text">$ cargo new communicator
$ cd communicator
</code></pre>
<p>Notice that Cargo generated <em>src/lib.rs</em> instead of <em>src/main.rs</em>. Inside
<em>src/lib.rs</em> we’ll find the following:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
#[cfg(test)]
mod tests {
#[test]
fn it_works() {
}
}
#}</code></pre></pre>
<p>Cargo creates an empty test to help us get our library started, rather than the
“Hello, world!” binary that we get when we use the <code>--bin</code> option. We’ll look
at the <code>#[]</code> and <code>mod tests</code> syntax in the “Using <code>super</code> to Access a Parent
Module” section later in this chapter, but for now, leave this code at the
bottom of <em>src/lib.rs</em>.</p>
<p>Because we don’t have a <em>src/main.rs</em> file, there’s nothing for Cargo to
execute with the <code>cargo run</code> command. Therefore, we’ll use the <code>cargo build</code>
command to compile our library crate’s code.</p>
<p>We’ll look at different options for organizing your library’s code that will be
suitable in a variety of situations, depending on the intent of the code.</p>
<a class="header" href="ch07-01-mod-and-the-filesystem.html#module-definitions" id="module-definitions"><h3>Module Definitions</h3></a>
<p>For our <code>communicator</code> networking library, we’ll first define a module named
<code>network</code> that contains the definition of a function called <code>connect</code>. Every
module definition in Rust starts with the <code>mod</code> keyword. Add this code to the
beginning of the <em>src/lib.rs</em> file, above the test code:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
mod network {
fn connect() {
}
}
#}</code></pre></pre>
<p>After the <code>mod</code> keyword, we put the name of the module, <code>network</code>, and then a
block of code in curly braces. Everything inside this block is inside the
namespace <code>network</code>. In this case, we have a single function, <code>connect</code>. If we
wanted to call this function from a script outside the <code>network</code> module, we
would need to specify the module and use the namespace syntax <code>::</code>, like so:
<code>network::connect()</code> rather than just <code>connect()</code>.</p>
<p>We can also have multiple modules, side by side, in the same <em>src/lib.rs</em> file.
For example, to also have a <code>client</code> module that has a function named <code>connect</code>
as well, we can add it as shown in Listing 7-1:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
mod network {
fn connect() {
}
}
mod client {
fn connect() {
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 7-1: The <code>network</code> module and the <code>client</code> module
defined side-by-side in <em>src/lib.rs</em></span></p>
<p>Now we have a <code>network::connect</code> function and a <code>client::connect</code> function.
These can have completely different functionality, and the function names do
not conflict with each other because they’re in different modules.</p>
<p>In this case, because we’re building a library, the file that serves as the
entry point for building our library is <em>src/lib.rs</em>. However, in respect to
creating modules, there’s nothing special about <em>src/lib.rs</em>. We could also
create modules in <em>src/main.rs</em> for a binary crate in the same way as we're
creating modules in <em>src/lib.rs</em> for the library crate. In fact, we can put
modules inside of modules, which can be useful as your modules grow to keep
related functionality organized together and separate functionality apart. The
choice of how you organize your code depends on how you think about the
relationship between the parts of your code. For instance, the <code>client</code> code
and its <code>connect</code> function might make more sense to users of our library if
they were inside the <code>network</code> namespace instead, as in Listing 7-2:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
mod network {
fn connect() {
}
mod client {
fn connect() {
}
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 7-2: Moving the <code>client</code> module inside the
<code>network</code> module</span></p>
<p>In your <em>src/lib.rs</em> file, replace the existing <code>mod network</code> and <code>mod client</code>
definitions with the ones in Listing 7-2, which have the <code>client</code> module as an
inner module of <code>network</code>. Now we have the functions <code>network::connect</code> and
<code>network::client::connect</code>: again, the two functions named <code>connect</code> don’t
conflict with each other because they’re in different namespaces.</p>
<p>In this way, modules form a hierarchy. The contents of <em>src/lib.rs</em> are at the
topmost level, and the submodules are at lower levels. Here’s what the
organization of our example in Listing 7-1 looks like when thought of as a
hierarchy:</p>
<pre><code class="language-text">communicator
├── network
└── client
</code></pre>
<p>And here’s the hierarchy corresponding to the example in Listing 7-2:</p>
<pre><code class="language-text">communicator
└── network
└── client
</code></pre>
<p>The hierarchy shows that in Listing 7-2, <code>client</code> is a child of the <code>network</code>
module rather than a sibling. More complicated projects can have many modules,
and they’ll need to be organized logically in order to keep track of them. What
“logically” means in your project is up to you and depends on how you and your
library’s users think about your project’s domain. Use the techniques shown
here to create side-by-side modules and nested modules in whatever structure
you would like.</p>
<a class="header" href="ch07-01-mod-and-the-filesystem.html#moving-modules-to-other-files" id="moving-modules-to-other-files"><h3>Moving Modules to Other Files</h3></a>
<p>Modules form a hierarchical structure, much like another structure in computing
that you’re used to: filesystems! We can use Rust’s module system along with
multiple files to split up Rust projects so not everything lives in
<em>src/lib.rs</em> or <em>src/main.rs</em>. For this example, let’s start with the code in
Listing 7-3:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
mod client {
fn connect() {
}
}
mod network {
fn connect() {
}
mod server {
fn connect() {
}
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 7-3: Three modules, <code>client</code>, <code>network</code>, and
<code>network::server</code>, all defined in <em>src/lib.rs</em></span></p>
<p>The file <em>src/lib.rs</em> has this module hierarchy:</p>
<pre><code class="language-text">communicator
├── client
└── network
└── server
</code></pre>
<p>If these modules had many functions, and those functions were becoming lengthy,
it would be difficult to scroll through this file to find the code we wanted to
work with. Because the functions are nested inside one or more mod blocks, the
lines of code inside the functions will start getting lengthy as well. These
would be good reasons to separate the <code>client</code>, <code>network</code>, and <code>server</code> modules
from <em>src/lib.rs</em> and place them into their own files.</p>
<p>First, replace the <code>client</code> module code with only the declaration of the <code>client</code>
module, so that your <em>src/lib.rs</em> looks like the following:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><code class="language-rust ignore">mod client;
mod network {
fn connect() {
}
mod server {
fn connect() {
}
}
}
</code></pre>
<p>We’re still <em>declaring</em> the <code>client</code> module here, but by replacing the block
with a semicolon, we’re telling Rust to look in another location for the code
defined within the scope of the <code>client</code> module. In other words, the line <code>mod client;</code> means:</p>
<pre><code class="language-rust ignore">mod client {
// contents of client.rs
}
</code></pre>
<p>Now we need to create the external file with that module name. Create a
<em>client.rs</em> file in your <em>src/</em> directory and open it. Then enter the
following, which is the <code>connect</code> function in the <code>client</code> module that we
removed in the previous step:</p>
<p><span class="filename">Filename: src/client.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
fn connect() {
}
#}</code></pre></pre>
<p>Note that we don’t need a <code>mod</code> declaration in this file because we already
declared the <code>client</code> module with <code>mod</code> in <em>src/lib.rs</em>. This file just
provides the <em>contents</em> of the <code>client</code> module. If we put a <code>mod client</code> here,
we’d be giving the <code>client</code> module its own submodule named <code>client</code>!</p>
<p>Rust only knows to look in <em>src/lib.rs</em> by default. If we want to add more
files to our project, we need to tell Rust in <em>src/lib.rs</em> to look in other
files; this is why <code>mod client</code> needs to be defined in <em>src/lib.rs</em> and can’t
be defined in <em>src/client.rs</em>.</p>
<p>Now the project should compile successfully, although you’ll get a few
warnings. Remember to use <code>cargo build</code> instead of <code>cargo run</code> because we have
a library crate rather than a binary crate:</p>
<pre><code class="language-text">$ cargo build
Compiling communicator v0.1.0 (file:///projects/communicator)
warning: function is never used: `connect`, #[warn(dead_code)] on by default
--> src/client.rs:1:1
|
1 | fn connect() {
| ^
warning: function is never used: `connect`, #[warn(dead_code)] on by default
--> src/lib.rs:4:5
|
4 | fn connect() {
| ^
warning: function is never used: `connect`, #[warn(dead_code)] on by default
--> src/lib.rs:8:9
|
8 | fn connect() {
| ^
</code></pre>
<p>These warnings tell us that we have functions that are never used. Don’t worry
about these warnings for now; we’ll address them in the “Controlling Visibility
with <code>pub</code>” section later in this chapter. The good news is that they’re just
warnings; our project built successfully!</p>
<p>Next, let’s extract the <code>network</code> module into its own file using the same
pattern. In <em>src/lib.rs</em>, delete the body of the <code>network</code> module and add a
semicolon to the declaration, like so:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><code class="language-rust ignore">mod client;
mod network;
</code></pre>
<p>Then create a new <em>src/network.rs</em> file and enter the following:</p>
<p><span class="filename">Filename: src/network.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
fn connect() {
}
mod server {
fn connect() {
}
}
#}</code></pre></pre>
<p>Notice that we still have a <code>mod</code> declaration within this module file; this is
because we still want <code>server</code> to be a submodule of <code>network</code>.</p>
<p>Run <code>cargo build</code> again. Success! We have one more module to extract: <code>server</code>.
Because it’s a submodule—that is, a module within a module—our current tactic
of extracting a module into a file named after that module won’t work. We’ll
try anyway so you can see the error. First, change <em>src/network.rs</em> to have
<code>mod server;</code> instead of the <code>server</code> module’s contents:</p>
<p><span class="filename">Filename: src/network.rs</span></p>
<pre><code class="language-rust ignore">fn connect() {
}
mod server;
</code></pre>
<p>Then create a <em>src/server.rs</em> file and enter the contents of the <code>server</code>
module that we extracted:</p>
<p><span class="filename">Filename: src/server.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
fn connect() {
}
#}</code></pre></pre>
<p>When we try to <code>cargo build</code>, we’ll get the error shown in Listing 7-4:</p>
<pre><code class="language-text">$ cargo build
Compiling communicator v0.1.0 (file:///projects/communicator)
error: cannot declare a new module at this location
--> src/network.rs:4:5
|
4 | mod server;
| ^^^^^^
|
note: maybe move this module `network` to its own directory via `network/mod.rs`
--> src/network.rs:4:5
|
4 | mod server;
| ^^^^^^
note: ... or maybe `use` the module `server` instead of possibly redeclaring it
--> src/network.rs:4:5
|
4 | mod server;
| ^^^^^^
</code></pre>
<p><span class="caption">Listing 7-4: Error when trying to extract the <code>server</code>
submodule into <em>src/server.rs</em></span></p>
<p>The error says we <code>cannot declare a new module at this location</code> and is
pointing to the <code>mod server;</code> line in <em>src/network.rs</em>. So <em>src/network.rs</em> is
different than <em>src/lib.rs</em> somehow: keep reading to understand why.</p>
<p>The note in the middle of Listing 7-4 is actually very helpful because it
points out something we haven’t yet talked about doing:</p>
<pre><code class="language-text">note: maybe move this module `network` to its own directory via
`network/mod.rs`
</code></pre>
<p>Instead of continuing to follow the same file naming pattern we used
previously, we can do what the note suggests:</p>
<ol>
<li>Make a new <em>directory</em> named <em>network</em>, the parent module’s name.</li>
<li>Move the <em>src/network.rs</em> file into the new <em>network</em> directory, and
rename <em>src/network/mod.rs</em>.</li>
<li>Move the submodule file <em>src/server.rs</em> into the <em>network</em> directory.</li>
</ol>
<p>Here are commands to carry out these steps:</p>
<pre><code class="language-text">$ mkdir src/network
$ mv src/network.rs src/network/mod.rs
$ mv src/server.rs src/network
</code></pre>
<p>Now when we try to run <code>cargo build</code>, compilation will work (we’ll still have
warnings though). Our module layout still looks like this, which is exactly the
same as it did when we had all the code in <em>src/lib.rs</em> in Listing 7-3:</p>
<pre><code class="language-text">communicator
├── client
└── network
└── server
</code></pre>
<p>The corresponding file layout now looks like this:</p>
<pre><code class="language-text">├── src
│ ├── client.rs
│ ├── lib.rs
│ └── network
│ ├── mod.rs
│ └── server.rs
</code></pre>
<p>So when we wanted to extract the <code>network::server</code> module, why did we have to
also change the <em>src/network.rs</em> file to the <em>src/network/mod.rs</em> file and put
the code for <code>network::server</code> in the <em>network</em> directory in
<em>src/network/server.rs</em> instead of just being able to extract the
<code>network::server</code> module into <em>src/server.rs</em>? The reason is that Rust wouldn’t
be able to recognize that <code>server</code> was supposed to be a submodule of <code>network</code>
if the <em>server.rs</em> file was in the <em>src</em> directory. To clarify Rust’s behavior
here, let’s consider a different example with the following module hierarchy,
where all the definitions are in <em>src/lib.rs</em>:</p>
<pre><code class="language-text">communicator
├── client
└── network
└── client
</code></pre>
<p>In this example, we have three modules again: <code>client</code>, <code>network</code>, and
<code>network::client</code>. Following the same steps we did earlier for extracting
modules into files, we would create <em>src/client.rs</em> for the <code>client</code> module.
For the <code>network</code> module, we would create <em>src/network.rs</em>. But we wouldn’t be
able to extract the <code>network::client</code> module into a <em>src/client.rs</em> file
because that already exists for the top-level <code>client</code> module! If we could put
the code for <em>both</em> the <code>client</code> and <code>network::client</code> modules in the
<em>src/client.rs</em> file, Rust wouldn’t have any way to know whether the code was
for <code>client</code> or for <code>network::client</code>.</p>
<p>Therefore, in order to extract a file for the <code>network::client</code> submodule of
the <code>network</code> module, we needed to create a directory for the <code>network</code> module
instead of a <em>src/network.rs</em> file. The code that is in the <code>network</code> module
then goes into the <em>src/network/mod.rs</em> file, and the submodule
<code>network::client</code> can have its own <em>src/network/client.rs</em> file. Now the
top-level <em>src/client.rs</em> is unambiguously the code that belongs to the
<code>client</code> module.</p>
<a class="header" href="ch07-01-mod-and-the-filesystem.html#rules-of-module-filesystems" id="rules-of-module-filesystems"><h3>Rules of Module Filesystems</h3></a>
<p>Let’s summarize the rules of modules with regard to files:</p>
<ul>
<li>If a module named <code>foo</code> has no submodules, you should put the declarations
for <code>foo</code> in a file named <em>foo.rs</em>.</li>
<li>If a module named <code>foo</code> does have submodules, you should put the declarations
for <code>foo</code> in a file named <em>foo/mod.rs</em>.</li>
</ul>
<p>These rules apply recursively, so if a module named <code>foo</code> has a submodule named
<code>bar</code> and <code>bar</code> does not have submodules, you should have the following files
in your <em>src</em> directory:</p>
<pre><code class="language-text">├── foo
│ ├── bar.rs (contains the declarations in `foo::bar`)
│ └── mod.rs (contains the declarations in `foo`, including `mod bar`)
</code></pre>
<p>The modules should be declared in their parent module’s file using the <code>mod</code>
keyword.</p>
<p>Next, we’ll talk about the <code>pub</code> keyword and get rid of those warnings!</p>
</div>
<!-- Mobile navigation buttons -->
<a href="ch07-00-modules.html" class="mobile-nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
<a href="ch07-02-controlling-visibility-with-pub.html" class="mobile-nav-chapters next">
<i class="fa fa-angle-right"></i>
</a>
</div>
<a href="ch07-00-modules.html" class="nav-chapters previous" title="You can navigate through the chapters using the arrow keys">
<i class="fa fa-angle-left"></i>
</a>
<a href="ch07-02-controlling-visibility-with-pub.html" class="nav-chapters next" title="You can navigate through the chapters using the arrow keys">
<i class="fa fa-angle-right"></i>
</a>
</div>
<!-- Local fallback for Font Awesome -->
<script>
if ($(".fa").css("font-family") !== "FontAwesome") {
$('<link rel="stylesheet" type="text/css" href="_FontAwesome/css/font-awesome.css">').prependTo('head');
}
</script>
<!-- Livereload script (if served using the cli tool) -->
<script src="highlight.js"></script>
<script src="book.js"></script>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
564935689ab5527f955e5449ded02799
>
files
>
248
