<!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"> <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" class="active"><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"><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="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 to the command line, feel free to use your favorite IDE.</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 directory for this particular 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 %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 type the following code:</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>Save the file, and go back to your terminal window. On Linux or OSX, enter the following commands:</p> <pre><code class="language-text">$ rustc main.rs $ ./main Hello, world! </code></pre> <p>On Windows, run <code>.\main.exe</code> instead of <code>./main</code>. 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 thing that is run for every executable Rust program. The first line says, “I’m declaring 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 braces, <code>{</code> and <code>}</code>. Rust requires these around all function bodies. It's considered good style to put the opening curly brace on the same line as the function declaration, with one space in between.</p> <p>Inside the <code>main</code> function:</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 E, 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> <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 "Writing and Running a Rust Program", 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 should output a binary executable, which you can see on Linux or OSX 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>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.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 it 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, 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 chapter. 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 and Mac:</p> <pre><code class="language-text">$ cd ~/projects </code></pre> <p>Windows:</p> <pre><code class="language-cmd">> cd %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; you can change this to use a different version control system, or no version control system, by using the <code>--vcs</code> flag.</p> <p>Open up <em>Cargo.toml</em> in your text editor of choice. It should look something like this:</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>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 similar to INI but has some extra goodies and 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 the next chapter.</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 earlier! 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) </code></pre> <p>This should have created 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>, which looks like this:</p> <p><span class="filename">Filename: Cargo.lock</span></p> <pre><code class="language-toml">[root] name = "hello_cargo" version = "0.1.0" </code></pre> <p>Cargo uses the <em>Cargo.lock</em> to keep track of dependencies in your application. This project doesn't have dependencies, so the file is a bit sparse. Realistically, you won't ever need to touch this file yourself; just let Cargo handle it.</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 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 something like this:</p> <pre><code class="language-text">$ cargo run Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) Running `target/debug/hello_cargo` Hello, world! </code></pre> <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 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. Even though this 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:</p> <pre><code class="language-text">$ git clone someurl.com/someproject $ cd someproject $ cargo build </code></pre> <blockquote> <p>Note: If you want to look at Cargo in more detail, check out the official <a href="http://doc.crates.io/guide.html">Cargo guide</a>, which covers all of its features.</p> </blockquote> </div> <!-- Mobile navigation buttons --> <a href="ch01-01-installation.html" class="mobile-nav-chapters previous"> <i class="fa fa-angle-left"></i> </a> <a href="ch02-00-guessing-game-tutorial.html" class="mobile-nav-chapters next"> <i class="fa fa-angle-right"></i> </a> </div> <a href="ch01-01-installation.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="ch02-00-guessing-game-tutorial.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>