As with most languages, Rust is available for a wide number of platforms. It would be impossible to go through installing the compiler on every variant of every operating system. Fortunately, there's an official method of installing Rust, and even though the details may differ slightly, the process is almost the same on all platforms. Therefore, this book will cover installing Rust using rustup on Fedora 27.

https://rustup.rs always contains up-to-date instructions on how to get going on all platforms. On Linux and macOS, it will look something like this:

On Windows, this text is replaced by a link to rustup-init.exe, which is an executable that installs and sets up rustup on Windows.

Run the suggested command that is shown at https://rustup.rs. Run this command in a Terminal. The script suggests some defaults and asks you to confirm them. This is roughly what it should look like after completing the whole script:

Note that this script attempts to set up rustup for your user by editing your .profile and .bash_profile files. If you are using a custom setup, such as another shell, you may need to add the source $HOME/.cargo/env command manually.

After finishing this script, you can verify that it worked by logging off and on from your Terminal and verifying that the tools are in your path:

To build any software that links against external libraries, you will need a C compiler and development versions of any libraries you may be linking against. To ensure that things work properly, install the compiler using the standard method for your operating system.

In Fedora, this would be done using the dnf tool:

sudo dnf install -y gcc

If you are unsure whether you have gcc installed, type the following command in a terminal window:

gcc -version  

If gcc is installed, you'll see something like this:

Open a command-prompt window and type this:

rustc --version  

If everything was installed correctly, you will see something like this:

To effectively code Rust, you will need at least some sort of text editor. All popular editors are properly supported, so if your favorite is Vim, Emacs, or any of the others, you will find a high-quality Rust extension there. The website https://areweideyet.com/ should give a current view of how things are.

We will cover the lightweight IDE from Microsoft, Visual Studio Code, and its most current Rust extension, called simply Rust. This IDE should work fairly well in all the different desktop environments. Installation instructions and packages for several platforms are available at Visual Studio Code's main site, https://code.visualstudio.com.

1. Open up Visual Studio Code and go to the Command Palette, either by the View menu or by the keyboard shortcut Ctrl + Shift + P (which may differ between platforms). Type in install extension to look for the proper command, and then select Install Extensions:

2. After selecting this, type rust into the next field to look for the Rust extension. At the time of writing, the most recent one is made by kalitaalexey:

3. You can install Rust right away by pressing Install; alternatively, click on the list item itself to show information about the extension first. After installing it, reload the editor. The Rust extension is now installed and ready to use!

Your first Rust project is not going to be particularly amazing. If anything, it's going to serve four purposes:

• Showing the structure of a Rust project
• Showing how to create a project by hand
• Showing how to create a project using the Rust Cargo script
• Compiling and executing the program

A Rust project (irrespective of the platform you are developing on) will have the following structure:

The preceding screenshot shows the structure of the simplest Rust project, and as such can be replicated using the following commands:

mkdir firstproject cd firstproject touch Cargo.toml mkdir src cd src touch main.rs

md firstproject cd firstproject md src echo $null >> Cargo.toml cd src echo $null >> main.rs

The Cargo.toml file is the Rust equivalent of a Makefile. When the .toml file is created by hand, it should be edited to contain something like this:

The structure of a Rust project can expand to include documentation as well as the build structure, as follows:

While there is nothing wrong with creating a Rust project by hand, Rust does come with a very handy utility called Cargo. Cargo can be used not only to automate the setting up of a project, but also to compile and execute Rust code. Cargo can be used to create the parts required for a library instead of an executable, and can also generate application documentation.

As with any other script, Cargo works (by default) on the current working directory. (For example, while writing this chapter, my working directory for the example code is ~/Developer/Rust/chapter0 on the Mac and Linux boxes, and J:\Developer\Rust\Chapter0 on the Windows 10 machine.)

In its simplest form, Cargo can generate the correct file structure like this:

cargo new demo_app_name -bin 

The preceding command tells Cargo to create a new structure called demo_app_name, and that it is to be a binary. If you remove -bin, it creates a structure called, which is going to be a library (or more accurately, something other than a binary).

If you don't wish to use the root (say you want to create a library within your binary framework), then instead of demo_app_name, you append the structure before the name relating to your working directory.

In the small example I gave earlier, if I wanted to create a library within my binary structure, I would use the following:

cargo new app_name/mylib  

That will create a structure like this:

The Cargo.toml file requires no editing (at this stage), as it contains the information we had to enter manually when we created the project by hand.

As we are all able to create directory structures, Cargo is then able to build and execute our source code.

If you look at the source code that comes with this chapter, you will find a directory called app_name. To build this package using Cargo, type the following from a Terminal (or command on Windows) window:

cd app_name 
cargo build app_name  

This will build the source code; finally you will be informed that the compilation has been successful:

Next, we can use Cargo to execute the binary as follows:

cargo run

If everything has worked, you will see something like the following:

As with any sort of utility, it's possible to "daisy-chain" the build and execution into one line, as follows:

cargo build; cargo run  

When the Rust compiler compiles the source files, it generates something known as an object file. The object file takes the source file (which we can read and understand) and compiles this into a form that can be joined with other libraries to create a binary.

This is a good idea, as it cuts down on compilation time; if a source file has not been changed, there is no need to recompile the file, as the object file will be the same.

Sometimes, the object file becomes out of date, or code in another object file causes a panic due to conflicts. In this case, it is not uncommon to "clean" the build. This removes the object files, and the compiler then has to recompile all the source files.

Also, it should always be performed prior to creating a release build.

The standard Unix make program performs this with the clean command (make clean). Cargo performs the clean operation in a way similar to the make utility in Unix:

cargo clean  

A comparison of the directories shows what happens when using the preceding Cargo command:

The entire target directory structure has simply been removed (the preceding screenshot was from a Mac, hence the dSYM and plist files. These do not exist on Linux and Windows).

As with other languages, Rust is able to create documentation based on meta tags with the source files. Take the following example:

fn main() 
{ 
   print_multiply(4, 5); 
} 
 
/// A simple function example 
/// 
/// # Examples 
/// 
/// ``` 
/// print_multiply(3, 5); 
///  
/// ``` 
 
fn print_multiply(x: i32, y: i32) 
{ 
   println!("x * y = {}", x * y); 
} 

The comments preceded by /// will be converted into documentation.

The documentation can be created in one of two ways: via Cargo or by using the rustdoc program.

As with the other operations provided by Cargo, when documentation is created, it acts as a wrapper for rustdoc. The only difference is that with rustdoc you have to specify the directory that the source file sits in. Cargo acts dumb in this case, and creates the documentation for all source files.

In its simplest form, the rustdoc command is used as follows:

cargo doc
rustdoc src/main.rs  

Cargo does have the advantage of creating the doc structure within the root folder, whereas rustdoc creates the structure within the target (which is removed with cargo clean).

Hopefully, unit testing is not something you will be unfamiliar with. A unit test is a test that operates on a specific function or method rather than an entire class or namespace. It ensures that the function operates correctly on the data it is presented with.

Unit tests within Rust are very simple to create (two examples are given in the assert_unittest and unittest directories). The following has been taken from the unittest example:

fn main() { 
    println!("Tests have not been compiled, use rustc --test instead (or cargo test)"); 
} 
 
#[test] 
fn multiply_test() 
{ 
   if 2 * 3 == 5 
   { 
      println!("The multiply worked"); 
   } 
} 

When this is built and executed, you may be surprised by the following result:

We have hit a limitation of unit testing: if we are not testing the data but the operation, how can we know that the result itself is correct?

Unit testing provides the developer with a number of methods called assertion methods:

#[test] 
fn multiply() 
{ 
   assert_eq!(5, 2 * 3); 
} 

In the preceding code snippet, we use the assert_eq! (assert equal) macro. The first argument is the answer expected, and the second argument is what is being tested. If 2 * 3 = 5, then the assertion is true and passes the unit test.

For a Rust developer, Cargo is an amazing utility. In addition to these common facilities, it also has other commands, which are listed in the table that follows. All commands follow this form:

cargo <command> <opts>  

fetch

generate-lockfile

git-checkout

cargo git-checkout -url=URL        

locate-project

login

cargo login -host=HOST   token        

owner

package

pkgid

publish

read-manifest

rustc

search

update

verify-project

version

yank

As you can now appreciate, the Cargo utility script is extremely powerful and flexible.

We now have a fully working installation of Rust, and are ready for the get-go. We've explained how to set up a project, both manually and via the Cargo utility, and you should already have an appreciation of how useful Cargo is.

In the next chapter, we'll be looking at the foundation of any language: variables.