<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Hello, World! - 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="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">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme -->
<!-- Fetch Clipboard.js from CDN but have a local fallback -->
<script src="https://cdn.jsdelivr.net/clipboard.js/1.6.1/clipboard.min.js"></script>
<script>
if (typeof Clipboard == 'undefined') {
document.write(unescape("%3Cscript src='clipboard.min.js'%3E%3C/script%3E"));
}
</script>
</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;
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
document.querySelector('html').classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li><a href="ch01-00-introduction.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li><ol class="section"><li><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li><a href="ch01-02-hello-world.html" class="active"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li><a href="ch01-03-how-rust-is-made-and-nightly-rust.html"><strong aria-hidden="true">1.3.</strong> How Rust is Made and “Nightly Rust”</a></li></ol></li><li><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Guessing Game Tutorial</a></li><li><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> How Functions Work</a></li><li><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li><a href="ch04-01-what-is-ownership.html"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References & Borrowing</a></li><li><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> Slices</a></li></ol></li><li><a href="ch05-00-structs.html"><strong aria-hidden="true">5.</strong> Using Structs to Structure Related Data</a></li><li><ol class="section"><li><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li><a href="ch06-03-if-let.html"><strong aria-hidden="true">6.3.</strong> Concise Control Flow with if let</a></li></ol></li><li><a href="ch07-00-modules.html"><strong aria-hidden="true">7.</strong> Modules</a></li><li><ol class="section"><li><a href="ch07-01-mod-and-the-filesystem.html"><strong aria-hidden="true">7.1.</strong> mod and the Filesystem</a></li><li><a href="ch07-02-controlling-visibility-with-pub.html"><strong aria-hidden="true">7.2.</strong> Controlling Visibility with pub</a></li><li><a href="ch07-03-importing-names-with-use.html"><strong aria-hidden="true">7.3.</strong> Referring to Names in Different Modules</a></li></ol></li><li><a href="ch08-00-common-collections.html"><strong aria-hidden="true">8.</strong> Common Collections</a></li><li><ol class="section"><li><a href="ch08-01-vectors.html"><strong aria-hidden="true">8.1.</strong> Vectors</a></li><li><a href="ch08-02-strings.html"><strong aria-hidden="true">8.2.</strong> Strings</a></li><li><a href="ch08-03-hash-maps.html"><strong aria-hidden="true">8.3.</strong> Hash Maps</a></li></ol></li><li><a href="ch09-00-error-handling.html"><strong aria-hidden="true">9.</strong> Error Handling</a></li><li><ol class="section"><li><a href="ch09-01-unrecoverable-errors-with-panic.html"><strong aria-hidden="true">9.1.</strong> Unrecoverable Errors with panic!</a></li><li><a href="ch09-02-recoverable-errors-with-result.html"><strong aria-hidden="true">9.2.</strong> Recoverable Errors with Result</a></li><li><a href="ch09-03-to-panic-or-not-to-panic.html"><strong aria-hidden="true">9.3.</strong> To panic! or Not To panic!</a></li></ol></li><li><a href="ch10-00-generics.html"><strong aria-hidden="true">10.</strong> Generic Types, Traits, and Lifetimes</a></li><li><ol class="section"><li><a href="ch10-01-syntax.html"><strong aria-hidden="true">10.1.</strong> Generic Data Types</a></li><li><a href="ch10-02-traits.html"><strong aria-hidden="true">10.2.</strong> Traits: Defining Shared Behavior</a></li><li><a href="ch10-03-lifetime-syntax.html"><strong aria-hidden="true">10.3.</strong> Validating References with Lifetimes</a></li></ol></li><li><a href="ch11-00-testing.html"><strong aria-hidden="true">11.</strong> Testing</a></li><li><ol class="section"><li><a href="ch11-01-writing-tests.html"><strong aria-hidden="true">11.1.</strong> Writing tests</a></li><li><a href="ch11-02-running-tests.html"><strong aria-hidden="true">11.2.</strong> Running tests</a></li><li><a href="ch11-03-test-organization.html"><strong aria-hidden="true">11.3.</strong> Test Organization</a></li></ol></li><li><a href="ch12-00-an-io-project.html"><strong aria-hidden="true">12.</strong> An I/O Project: Building a Command Line Program</a></li><li><ol class="section"><li><a href="ch12-01-accepting-command-line-arguments.html"><strong aria-hidden="true">12.1.</strong> Accepting Command Line Arguments</a></li><li><a href="ch12-02-reading-a-file.html"><strong aria-hidden="true">12.2.</strong> Reading a File</a></li><li><a href="ch12-03-improving-error-handling-and-modularity.html"><strong aria-hidden="true">12.3.</strong> Refactoring to Improve Modularity and Error Handling</a></li><li><a href="ch12-04-testing-the-librarys-functionality.html"><strong aria-hidden="true">12.4.</strong> Developing the Library’s Functionality with Test Driven Development</a></li><li><a href="ch12-05-working-with-environment-variables.html"><strong aria-hidden="true">12.5.</strong> Working with Environment Variables</a></li><li><a href="ch12-06-writing-to-stderr-instead-of-stdout.html"><strong aria-hidden="true">12.6.</strong> Writing Error Messages to Standard Error Instead of Standard Output</a></li></ol></li><li><a href="ch13-00-functional-features.html"><strong aria-hidden="true">13.</strong> Functional Language Features: Iterators and Closures</a></li><li><ol class="section"><li><a href="ch13-01-closures.html"><strong aria-hidden="true">13.1.</strong> Closures: Anonymous Functions that Can Capture Their Environment</a></li><li><a href="ch13-02-iterators.html"><strong aria-hidden="true">13.2.</strong> Processing a Series of Items with Iterators</a></li><li><a href="ch13-03-improving-our-io-project.html"><strong aria-hidden="true">13.3.</strong> Improving Our I/O Project</a></li><li><a href="ch13-04-performance.html"><strong aria-hidden="true">13.4.</strong> Comparing Performance: Loops vs. Iterators</a></li></ol></li><li><a href="ch14-00-more-about-cargo.html"><strong aria-hidden="true">14.</strong> More about Cargo and Crates.io</a></li><li><ol class="section"><li><a href="ch14-01-release-profiles.html"><strong aria-hidden="true">14.1.</strong> Customizing Builds with Release Profiles</a></li><li><a href="ch14-02-publishing-to-crates-io.html"><strong aria-hidden="true">14.2.</strong> Publishing a Crate to Crates.io</a></li><li><a href="ch14-03-cargo-workspaces.html"><strong aria-hidden="true">14.3.</strong> Cargo Workspaces</a></li><li><a href="ch14-04-installing-binaries.html"><strong aria-hidden="true">14.4.</strong> Installing Binaries from Crates.io with cargo install</a></li><li><a href="ch14-05-extending-cargo.html"><strong aria-hidden="true">14.5.</strong> Extending Cargo with Custom Commands</a></li></ol></li><li><a href="ch15-00-smart-pointers.html"><strong aria-hidden="true">15.</strong> Smart Pointers</a></li><li><ol class="section"><li><a href="ch15-01-box.html"><strong aria-hidden="true">15.1.</strong> Box<T> Points to Data on the Heap and Has a Known Size</a></li><li><a href="ch15-02-deref.html"><strong aria-hidden="true">15.2.</strong> The Deref Trait Allows Access to the Data Through a Reference</a></li><li><a href="ch15-03-drop.html"><strong aria-hidden="true">15.3.</strong> The Drop Trait Runs Code on Cleanup</a></li><li><a href="ch15-04-rc.html"><strong aria-hidden="true">15.4.</strong> Rc<T>, the Reference Counted Smart Pointer</a></li><li><a href="ch15-05-interior-mutability.html"><strong aria-hidden="true">15.5.</strong> RefCell<T> and the Interior Mutability Pattern</a></li><li><a href="ch15-06-reference-cycles.html"><strong aria-hidden="true">15.6.</strong> Creating Reference Cycles and Leaking Memory is Safe</a></li></ol></li><li><a href="ch16-00-concurrency.html"><strong aria-hidden="true">16.</strong> Fearless Concurrency</a></li><li><ol class="section"><li><a href="ch16-01-threads.html"><strong aria-hidden="true">16.1.</strong> Threads</a></li><li><a href="ch16-02-message-passing.html"><strong aria-hidden="true">16.2.</strong> Message Passing</a></li><li><a href="ch16-03-shared-state.html"><strong aria-hidden="true">16.3.</strong> Shared State</a></li><li><a href="ch16-04-extensible-concurrency-sync-and-send.html"><strong aria-hidden="true">16.4.</strong> Extensible Concurrency: Sync and Send</a></li></ol></li><li><a href="ch17-00-oop.html"><strong aria-hidden="true">17.</strong> Is Rust an Object-Oriented Programming Language?</a></li><li><ol class="section"><li><a href="ch17-01-what-is-oo.html"><strong aria-hidden="true">17.1.</strong> What Does Object-Oriented Mean?</a></li><li><a href="ch17-02-trait-objects.html"><strong aria-hidden="true">17.2.</strong> Trait Objects for Using Values of Different Types</a></li><li><a href="ch17-03-oo-design-patterns.html"><strong aria-hidden="true">17.3.</strong> Object-Oriented Design Pattern Implementations</a></li></ol></li><li><a href="ch18-00-patterns.html"><strong aria-hidden="true">18.</strong> Patterns Match the Structure of Values</a></li><li><ol class="section"><li><a href="ch18-01-all-the-places-for-patterns.html"><strong aria-hidden="true">18.1.</strong> All the Places Patterns May be Used</a></li><li><a href="ch18-02-refutability.html"><strong aria-hidden="true">18.2.</strong> Refutability: Whether a Pattern Might Fail to Match</a></li><li><a href="ch18-03-pattern-syntax.html"><strong aria-hidden="true">18.3.</strong> All the Pattern Syntax</a></li></ol></li><li><a href="ch19-00-advanced-features.html"><strong aria-hidden="true">19.</strong> Advanced Features</a></li><li><ol class="section"><li><a href="ch19-01-unsafe-rust.html"><strong aria-hidden="true">19.1.</strong> Unsafe Rust</a></li><li><a href="ch19-02-advanced-lifetimes.html"><strong aria-hidden="true">19.2.</strong> Advanced Lifetimes</a></li><li><a href="ch19-03-advanced-traits.html"><strong aria-hidden="true">19.3.</strong> Advanced Traits</a></li><li><a href="ch19-04-advanced-types.html"><strong aria-hidden="true">19.4.</strong> Advanced Types</a></li><li><a href="ch19-05-advanced-functions-and-closures.html"><strong aria-hidden="true">19.5.</strong> Advanced Functions & Closures</a></li></ol></li><li><a href="ch20-00-final-project-a-web-server.html"><strong aria-hidden="true">20.</strong> Final Project: Building a Multithreaded Web Server</a></li><li><ol class="section"><li><a href="ch20-01-single-threaded.html"><strong aria-hidden="true">20.1.</strong> A Single Threaded Web Server</a></li><li><a href="ch20-02-slow-requests.html"><strong aria-hidden="true">20.2.</strong> How Slow Requests Affect Throughput</a></li><li><a href="ch20-03-designing-the-interface.html"><strong aria-hidden="true">20.3.</strong> Designing the Thread Pool Interface</a></li><li><a href="ch20-04-storing-threads.html"><strong aria-hidden="true">20.4.</strong> Creating the Thread Pool and Storing Threads</a></li><li><a href="ch20-05-sending-requests-via-channels.html"><strong aria-hidden="true">20.5.</strong> Sending Requests to Threads Via Channels</a></li><li><a href="ch20-06-graceful-shutdown-and-cleanup.html"><strong aria-hidden="true">20.6.</strong> Graceful Shutdown and Cleanup</a></li></ol></li><li><a href="appendix-00.html"><strong aria-hidden="true">21.</strong> Appendix</a></li><li><ol class="section"><li><a href="appendix-01-keywords.html"><strong aria-hidden="true">21.1.</strong> A - Keywords</a></li><li><a href="appendix-02-operators.html"><strong aria-hidden="true">21.2.</strong> B - Operators and Symbols</a></li><li><a href="appendix-03-derivable-traits.html"><strong aria-hidden="true">21.3.</strong> C - Derivable Traits</a></li><li><a href="appendix-04-macros.html"><strong aria-hidden="true">21.4.</strong> D - Macros</a></li><li><a href="appendix-05-translation.html"><strong aria-hidden="true">21.5.</strong> E - Translations</a></li><li><a href="appendix-06-newest-features.html"><strong aria-hidden="true">21.6.</strong> F - Newest Features</a></li></ol></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<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="submenu">
<li><button class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li><button class="theme" id="rust">Rust</button></li>
<li><button class="theme" id="coal">Coal</button></li>
<li><button class="theme" id="navy">Navy</button></li>
<li><button class="theme" id="ayu">Ayu</button></li>
</ul>
</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>
<!-- 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="ch01-02-hello-world.html#hello-world" id="hello-world"><h2>Hello, World!</h2></a>
<p>Now that you have Rust installed, let’s write your first Rust program. It’s
traditional when learning a new language to write a little program to print the
text “Hello, world!” to the screen, and in this section, we’ll follow that
tradition.</p>
<blockquote>
<p>Note: This book assumes basic familiarity with the command line. Rust itself
makes no specific demands about your editing, tooling, or where your code
lives, so if you prefer an IDE (Integrated Development Environment) to the
command line, feel free to use your favorite IDE. Many IDEs now have some
degree of Rust support; check the IDE’s documentation for details. Enabling
great IDE support has been a recent focus of the Rust team, and progress
has been made rapidly on that front!</p>
</blockquote>
<a class="header" href="ch01-02-hello-world.html#creating-a-project-directory" id="creating-a-project-directory"><h3>Creating a Project Directory</h3></a>
<p>First, make a directory to put your Rust code in. Rust doesn’t care where your
code lives, but for this book, we’d suggest making a <em>projects</em> directory in
your home directory and keeping all your projects there. Open a terminal and
enter the following commands to make a <em>projects</em> directory and a directory
inside that for the “Hello, world!” project:</p>
<p>Linux and Mac:</p>
<pre><code class="language-text">$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world
</code></pre>
<p>Windows CMD:</p>
<pre><code class="language-cmd">> mkdir "%USERPROFILE%\projects"
> cd /d "%USERPROFILE%\projects"
> mkdir hello_world
> cd hello_world
</code></pre>
<p>Windows PowerShell:</p>
<pre><code class="language-powershell">> mkdir $env:USERPROFILE\projects
> cd $env:USERPROFILE\projects
> mkdir hello_world
> cd hello_world
</code></pre>
<a class="header" href="ch01-02-hello-world.html#writing-and-running-a-rust-program" id="writing-and-running-a-rust-program"><h3>Writing and Running a Rust Program</h3></a>
<p>Next, make a new source file and call it <em>main.rs</em>. Rust files always end with
the <em>.rs</em> extension. If you’re using more than one word in your filename, use
an underscore to separate them. For example, you’d use <em>hello_world.rs</em> rather
than <em>helloworld.rs</em>.</p>
<p>Now open the <em>main.rs</em> file you just created, and enter the code shown in
Listing 1-1:</p>
<p><span class="filename">Filename: main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">fn main() {
println!("Hello, world!");
}
</code></pre></pre>
<p><span class="caption">Listing 1-1: A program that prints “Hello, world!”</span></p>
<p>Save the file, and go back to your terminal window. On Linux or macOS, enter
the following commands:</p>
<pre><code class="language-text">$ rustc main.rs
$ ./main
Hello, world!
</code></pre>
<p>On Windows, use <code>.\main.exe</code> instead of <code>./main</code>.</p>
<pre><code class="language-powershell">> rustc main.rs
> .\main.exe
Hello, world!
</code></pre>
<p>Regardless of your operating system, you should see the string <code>Hello, world!</code>
print to the terminal. If you did, then congratulations! You’ve officially
written a Rust program. That makes you a Rust programmer! Welcome!</p>
<a class="header" href="ch01-02-hello-world.html#anatomy-of-a-rust-program" id="anatomy-of-a-rust-program"><h3>Anatomy of a Rust Program</h3></a>
<p>Now, let’s go over what just happened in your “Hello, world!” program in
detail. Here’s the first piece of the puzzle:</p>
<pre><pre class="playpen"><code class="language-rust">fn main() {
}
</code></pre></pre>
<p>These lines define a <em>function</em> in Rust. The <code>main</code> function is special: it’s
the first code that is run for every executable Rust program. The first line
declares a function named <code>main</code> that has no parameters and returns nothing. If
there were parameters, their names would go inside the parentheses, <code>(</code> and <code>)</code>.</p>
<p>Also note that the function body is wrapped in curly brackets, <code>{</code> and <code>}</code>.
Rust requires these around all function bodies. It’s considered good style to
put the opening curly bracket on the same line as the function declaration,
with one space in between.</p>
<blockquote>
<p>At the time of writing, an automatic formatter, <code>rustfmt</code>, is under
development. If you’d like to stick to a standard style across Rust projects,
<code>rustfmt</code> is a tool that will format your code in a particular style. The
plan is to eventually include it with the standard Rust distribution, like
<code>rustc</code>, so depending on when you read this book, you may have it already
installed! Check the online documentation for more details.</p>
</blockquote>
<p>Inside the <code>main</code> function, we have this code:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
println!("Hello, world!");
#}</code></pre></pre>
<p>This line does all of the work in this little program: it prints text to the
screen. There are a number of details to notice here. The first is that Rust
style is to indent with four spaces, not a tab.</p>
<p>The second important part is <code>println!</code>. This is calling a Rust <em>macro</em>, which
is how metaprogramming is done in Rust. If it were calling a function instead,
it would look like this: <code>println</code> (without the <code>!</code>). We’ll discuss Rust macros
in more detail in Appendix D, but for now you just need to know that when you
see a <code>!</code> that means that you’re calling a macro instead of a normal function.</p>
<blockquote>
<a class="header" href="ch01-02-hello-world.html#why-println-is-a-macro" id="why-println-is-a-macro"><h3>Why <code>println!</code> is a Macro</h3></a>
<p>There are multiple reasons why <code>println!</code> is a macro rather than a function,
and we haven’t really explained Rust yet, so it’s not exactly obvious. Here
are the reasons:</p>
<ul>
<li>The string passed to <code>println!</code> can have formatting specifiers in it,
and those are checked at compile-time.</li>
<li>Rust functions can only have a fixed number of arguments, but <code>println!</code>
(and macros generally) can take a variable number.</li>
<li>The formatting specifiers can have named arguments, which Rust functions
cannot.</li>
<li>It implicitly takes its arguments by reference even when they’re passed
by value.</li>
</ul>
<p>If none of this makes sense, don’t worry about it. We’ll cover these concepts
in more detail later.</p>
</blockquote>
<p>Next is <code>"Hello, world!"</code> which is a <em>string</em>. We pass this string as an
argument to <code>println!</code>, which prints the string to the screen. Easy enough!</p>
<p>The line ends with a semicolon (<code>;</code>). The <code>;</code> indicates that this expression is
over, and the next one is ready to begin. Most lines of Rust code end with a
<code>;</code>.</p>
<a class="header" href="ch01-02-hello-world.html#compiling-and-running-are-separate-steps" id="compiling-and-running-are-separate-steps"><h3>Compiling and Running Are Separate Steps</h3></a>
<p>In the “Writing and Running a Rust Program” section, we showed you how to run a
newly created program. We’ll break that process down and examine each step now.</p>
<p>Before running a Rust program, you have to compile it. You can use the Rust
compiler by entering the <code>rustc</code> command and passing it the name of your source
file, like this:</p>
<pre><code class="language-text">$ rustc main.rs
</code></pre>
<p>If you come from a C or C++ background, you’ll notice that this is similar to
<code>gcc</code> or <code>clang</code>. After compiling successfully, Rust outputs a binary
executable.</p>
<p>On Linux, Mac, and PowerShell on Windows, you can see the executable by
entering the <code>ls</code> command in your shell as follows:</p>
<pre><code class="language-text">$ ls
main main.rs
</code></pre>
<p>With CMD on Windows, you’d enter:</p>
<pre><code class="language-cmd">> dir /B %= the /B option says to only show the file names =%
main.exe
main.pdb
main.rs
</code></pre>
<p>This shows we have two files: the source code, with the <em>.rs</em> extension, and
the executable (<em>main.exe</em> on Windows, <em>main</em> everywhere else). All that’s left
to do from here is run the <em>main</em> or <em>main.exe</em> file, like this:</p>
<pre><code class="language-text">$ ./main # or .\main.exe on Windows
</code></pre>
<p>If <em>main.rs</em> were your “Hello, world!” program, this would print <code>Hello, world!</code> to your terminal.</p>
<p>If you come from a dynamic language like Ruby, Python, or JavaScript, you may
not be used to compiling and running a program being separate steps. Rust is an
<em>ahead-of-time compiled</em> language, which means that you can compile a program,
give the executable to someone else, and they can run it even without having
Rust installed. If you give someone a <code>.rb</code>, <code>.py</code>, or <code>.js</code> file, on the other
hand, they need to have a Ruby, Python, or JavaScript implementation installed
(respectively), but you only need one command to both compile and run your
program. Everything is a tradeoff in language design.</p>
<p>Just compiling with <code>rustc</code> is fine for simple programs, but as your project
grows, you’ll want to be able to manage all of the options your project has and
make it easy to share your code with other people and projects. Next, we’ll
introduce you to a tool called Cargo, which will help you write real-world Rust
programs.</p>
<a class="header" href="ch01-02-hello-world.html#hello-cargo" id="hello-cargo"><h2>Hello, Cargo!</h2></a>
<p>Cargo is Rust’s build system and package manager, and Rustaceans use Cargo to
manage their Rust projects because it makes a lot of tasks easier. For example,
Cargo takes care of building your code, downloading the libraries your code
depends on, and building those libraries. We call libraries your code needs
<em>dependencies</em>.</p>
<p>The simplest Rust programs, like the one we’ve written so far, don’t have any
dependencies, so right now, you’d only be using the part of Cargo that can take
care of building your code. As you write more complex Rust programs, you’ll
want to add dependencies, and if you start off using Cargo, that will be a lot
easier to do.</p>
<p>As the vast majority of Rust projects use Cargo, we will assume that
you’re using it for the rest of the book. Cargo comes installed with Rust
itself, if you used the official installers as covered in the “Installation”
section. If you installed Rust through some other means, you can check if you
have Cargo installed by typing the following into your terminal:</p>
<pre><code class="language-text">$ cargo --version
</code></pre>
<p>If you see a version number, great! If you see an error like <code>command not found</code>, then you should look at the documentation for your method of
installation to determine how to install Cargo separately.</p>
<a class="header" href="ch01-02-hello-world.html#creating-a-project-with-cargo" id="creating-a-project-with-cargo"><h3>Creating a Project with Cargo</h3></a>
<p>Let’s create a new project using Cargo and look at how it differs from our
project in <code>hello_world</code>. Go back to your projects directory (or wherever you
decided to put your code):</p>
<p>Linux, Mac, and PowerShell:</p>
<pre><code class="language-text">$ cd ~/projects
</code></pre>
<p>CMD for Windows:</p>
<pre><code class="language-cmd">> cd \d "%USERPROFILE%\projects"
</code></pre>
<p>And then on any operating system run:</p>
<pre><code class="language-text">$ cargo new hello_cargo --bin
$ cd hello_cargo
</code></pre>
<p>We passed the <code>--bin</code> argument to <code>cargo new</code> because our goal is to make an
executable application, as opposed to a library. Executables are binary
executable files often called just <em>binaries</em>. We’ve given <code>hello_cargo</code> as the
name for our project, and Cargo creates its files in a directory of the same
name that we can then go into.</p>
<p>If we list the files in the <em>hello_cargo</em> directory, we can see that Cargo has
generated two files and one directory for us: a <em>Cargo.toml</em> and a <em>src</em>
directory with a <em>main.rs</em> file inside. It has also initialized a new git
repository in the <em>hello_cargo</em> directory for us, along with a <em>.gitignore</em>
file. Git is a common version control system. You can change <code>cargo new</code> to use
a different version control system, or no version control system, by using the
<code>--vcs</code> flag. Run <code>cargo new --help</code> to see the available options.</p>
<p>Open up <em>Cargo.toml</em> in your text editor of choice. It should look similar to
the code in Listing 1-2:</p>
<p><span class="filename">Filename: Cargo.toml</span></p>
<pre><code class="language-toml">[package]
name = "hello_cargo"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
[dependencies]
</code></pre>
<p><span class="caption">Listing 1-2: Contents of <em>Cargo.toml</em> generated by <code>cargo new</code></span></p>
<p>This file is in the <a href="https://github.com/toml-lang/toml"><em>TOML</em></a><!-- ignore --> (Tom’s Obvious, Minimal
Language) format. TOML is used as Cargo’s configuration format.</p>
<p>The first line, <code>[package]</code>, is a section heading that indicates that the
following statements are configuring a package. As we add more information to
this file, we’ll add other sections.</p>
<p>The next three lines set the three bits of configuration that Cargo needs to
see in order to know that it should compile your program: its name, what
version it is, and who wrote it. Cargo gets your name and email information
from your environment. If it’s not correct, go ahead and fix that and save the
file.</p>
<p>The last line, <code>[dependencies]</code>, is the start of a section for you to list any
<em>crates</em> (which is what we call packages of Rust code) that your project will
depend on so that Cargo knows to download and compile those too. We won’t need
any other crates for this project, but we will in the guessing game tutorial in
Chapter 2.</p>
<p>Now let’s look at <em>src/main.rs</em>:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">fn main() {
println!("Hello, world!");
}
</code></pre></pre>
<p>Cargo has generated a “Hello World!” for you, just like the one we wrote in
Listing 1-1! So that part is the same. The differences between our previous
project and the project generated by Cargo that we’ve seen so far are:</p>
<ul>
<li>Our code goes in the <em>src</em> directory</li>
<li>The top level contains a <em>Cargo.toml</em> configuration file</li>
</ul>
<p>Cargo expects your source files to live inside the <em>src</em> directory so that the
top-level project directory is just for READMEs, license information,
configuration files, and anything else not related to your code. In this way,
using Cargo helps you keep your projects nice and tidy. There’s a place for
everything, and everything is in its place.</p>
<p>If you started a project that doesn’t use Cargo, as we did with our project in
the <em>hello_world</em> directory, you can convert it to a project that does use
Cargo by moving your code into the <em>src</em> directory and creating an appropriate
<em>Cargo.toml</em>.</p>
<a class="header" href="ch01-02-hello-world.html#building-and-running-a-cargo-project" id="building-and-running-a-cargo-project"><h3>Building and Running a Cargo Project</h3></a>
<p>Now let’s look at what’s different about building and running your Hello World
program through Cargo! To do so, enter the following commands:</p>
<pre><code class="language-text">$ cargo build
Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs
</code></pre>
<p>This creates an executable file in <em>target/debug/hello_cargo</em> (or
<em>target\debug\hello_cargo.exe</em> on Windows), which you can run with this
command:</p>
<pre><code class="language-text">$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows
Hello, world!
</code></pre>
<p>Bam! If all goes well, <code>Hello, world!</code> should print to the terminal once more.</p>
<p>Running <code>cargo build</code> for the first time also causes Cargo to create a new file
at the top level called <em>Cargo.lock</em>. Cargo uses <em>Cargo.lock</em> to keep track of
the exact versions of dependencies used to build your project. This project
doesn’t have dependencies, so the file is a bit sparse. You won’t ever need to
touch this file yourself; Cargo will manage its contents for you.</p>
<p>We just built a project with <code>cargo build</code> and ran it with
<code>./target/debug/hello_cargo</code>, but we can also use <code>cargo run</code> to compile and
then run:</p>
<pre><code class="language-text">$ cargo run
Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
Running `target/debug/hello_cargo`
Hello, world!
</code></pre>
<p>Notice that this time, we didn’t see the output telling us that Cargo was
compiling <code>hello_cargo</code>. Cargo figured out that the files haven’t changed, so
it just ran the binary. If you had modified your source code, Cargo would have
rebuilt the project before running it, and you would have seen output like
this:</p>
<pre><code class="language-text">$ cargo run
Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
Running `target/debug/hello_cargo`
Hello, world!
</code></pre>
<p>Finally, there’s <code>cargo check</code>. This will quickly check your code to make sure
that it compiles, but not bother producing an executable:</p>
<pre><code class="language-text">$ cargo check
Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs
</code></pre>
<p>Why would you not want an executable? <code>cargo check</code> is often much faster than
<code>cargo build</code>, because Cargo can skip the entire step of producing the
executable. If we’re checking our work throughout the process of writing the
code, this will speed things up! As such, many Rustaceans run <code>cargo check</code> as
they write their program to make sure that it compiles, and then run <code>cargo build</code> once they’re ready to give it a spin themselves.</p>
<p>So a few more differences we’ve now seen:</p>
<ul>
<li>Instead of using <code>rustc</code>, build a project using <code>cargo build</code> or
<code>cargo check</code> (or build and run it in one step with <code>cargo run</code>).</li>
<li>Instead of the result of the build being put in the same directory as our
code, Cargo will put it in the <em>target/debug</em> directory.</li>
</ul>
<p>The other advantage of using Cargo is that the commands are the same no matter
what operating system you’re on, so at this point we will no longer be
providing specific instructions for Linux and Mac versus Windows.</p>
<a class="header" href="ch01-02-hello-world.html#building-for-release" id="building-for-release"><h3>Building for Release</h3></a>
<p>When your project is finally ready for release, you can use <code>cargo build --release</code> to compile your project with optimizations. This will create an
executable in <em>target/release</em> instead of <em>target/debug</em>. These optimizations
make your Rust code run faster, but turning them on makes your program take
longer to compile. This is why there are two different profiles: one for
development when you want to be able to rebuild quickly and often, and one for
building the final program you’ll give to a user that won’t be rebuilt and that
we want to run as fast as possible. If you’re benchmarking the running time of
your code, be sure to run <code>cargo build --release</code> and benchmark with the
executable in <em>target/release</em>.</p>
<a class="header" href="ch01-02-hello-world.html#cargo-as-convention" id="cargo-as-convention"><h3>Cargo as Convention</h3></a>
<p>With simple projects, Cargo doesn’t provide a whole lot of value over just
using <code>rustc</code>, but it will prove its worth as you continue. With complex
projects composed of multiple crates, it’s much easier to let Cargo coordinate
the build. With Cargo, you can just run <code>cargo build</code>, and it should work the
right way.</p>
<p>Even though the <code>hello_cargo</code> project is simple, it now uses much of the real
tooling you’ll use for the rest of your Rust career. In fact, you can get
started with virtually all Rust projects you want to work on with the following
commands to check out the code using Git, change into the project directory,
and build:</p>
<pre><code class="language-text">$ git clone someurl.com/someproject
$ cd someproject
$ cargo build
</code></pre>
<p>If you want to look at Cargo in more detail, check out <a href="https://doc.rust-lang.org/cargo/">its documentation</a>,
which covers all of its features.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch01-01-installation.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="ch01-03-how-rust-is-made-and-nightly-rust.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="ch01-01-installation.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="ch01-03-how-rust-is-made-and-nightly-rust.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>
<!-- Local fallback for Font Awesome -->
<script>
if (getComputedStyle(document.querySelector(".fa")).fontFamily !== "FontAwesome") {
var link = document.createElement('link');
link.rel = 'stylesheet';
link.type = 'text/css';
link.href = '_FontAwesome/css/font-awesome.css';
document.head.insertBefore(link, document.head.firstChild)
}
</script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS script -->
</body>
</html>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
fdedb3cf2140df9b6d419a2338ab1caa
>
files
>
575
