01: Getting Started

Installing Rust and the Cargo package manager.

Here's what we'll learn in this lesson:

1. How to install Rust and create a new project
2. Adding a library to our Rust project using Cargo
3. Our first code example, using dotenv

To get started with Rust, we'll first need to install a command line tool called rustup. rustup installs The Rust Programming Language from official release channels. More advanced features include the ability to switch between different versions of Rust (stable, beta, nightly, etc) and also cross-compile for various platforms.

Step 1 of 3: install rustup

In this course, we'll be referring to the official Rust book from time to time as a source of truth.

So as a first step (and for brevity), check out the installation steps here.

A note about the Rust book linked above: this is a free, popular online resource for newcomers to Rust. While I recommend giving it a read if you have the extra time, this course is meant to be a simpler Rust course in my own words, after going through that book, other learning resources and building my own projects, I've whittled the key skills down from that to make this a much simpler course.

Next, ensure you're command line is all good to go and that rustup is in your PATH. Open a fresh command window (i.e. the Terminal app on macOS or any terminal on Linux or for Windows, WSL, Powershell or Command Prompt) and ensure you can run rustup update. You can run this at any time to update your version of Rust.

One of the nice features of Rust is that new versions are available at least every 6 weeks (for the stable channel), with small features being introduced all the time. Check out releases.rs for more info.

Step 2 of 3: using Cargo

Cargo is Rust's go-to build and package management tool.

Traditionally, we can build a Rust project using Rust's compiler, rustc which you get out of the box with Rust. Though this is typically a lower level tool, offering build options that you typically will not need.

The most common way to build a Rust project, which we will do in a moment, is to use Cargo.

So first off, let's create a new Rust project. There are two types, binaries and libraries. (You can also create a project that is both but that's another topic. A binary is just a stand alone program. A library is a bit of code that others can use in their Rust projects and that can optionally be published as a "Crate" on crates.io.

So let's create a new Rust binary and cd to that directory:

cargo new project-name
cd project-name

Note that for this course, we will use Linux based command line tools, such as cd (as opposed to dir on Windows) as these are the most popular tools among developers.

This will create a new directory for a Rust binary with a skeleton Rust project, including all the necessary files to start. This is the same as running cargo new project-name --bin. If you wanted to create a new library, you'd run cargo new project-name --lib.

Now, let's run our generated Rust binary:

cargo run

Note that we can re-build by running cargo build and if we wanted to build for production, creating a more slimmed down binary, we'd run cargo build --release

cargo run or cargo build here will, as you can see, creates a new directory target. target may contain debug and/or release binaries. When we run our binary, the binary in either of these directories is run.

Now, based on the platform we're on (macOS, Linux, Windows), the appropriate binary will be built based on that platform's architecture (i.e. arm, x86, etc).

Note: you typically do not need to worry about this if you'll be using a cloud based platform to say, build and ship a Rust based web API (i.e. railway.app), because when you push your code to that platform, it will build, deploy and run that Rust app based on the architecture the cloud service is using. Overall, it's good to be aware of this concept of "cross-platform" builds.

Congrats, you've run your first Rust program!

Step 3 of 3: installing packages

In this course, we'll be using some real-world, common packages. That's why I feel this course will be quite useful to students vs reading say the aforementioned Rust book alone.

Let's start off with a very common package, dotenv. This package will allow us to include a .env file in our project, containing a list of environment variables and access them easily in our code.

Let's add the package:

cargo add dotenv

Open Cargo.toml, you'll see under the [dependencies] section, that log is now included.

Cargo.toml is a configuration file for any Rust project which contains information about a binary or library project, the list of dependencies it needs and other useful meta information. If you're familiar with Javascript based projects, this file is more or less equivalent to package.json.

Now let's open src/main.rs. Don't worry about understanding the code, we'll cover main.rs in the next lesson.

Update main.rs to include an example use of our package:

use std::env;

fn main() {
    dotenv::dotenv().ok();

    let message = env::var("MESSAGE").unwrap();

    println!("Hello, {}", message);
}

Now, create a new file. .env (don't forget the '.'!) containing:

MESSAGE=world

Now run:

cargo run

You should see the output:

Hello, world

Let's break down the code:

1. use std::env;: import the env crate (a Rust "crate" is essentially a library) offered by Rust's standard library, std.
2. dotenv::dotenv().ok();: initialize the dotenv package, per the instructions cited in the crate's page.
3. let message = env::var("MESSAGE").unwrap();: create a new message variable, grabbing the MESSAGE environment variable. Don't worry about unwrap() here. That is for an upcoming lesson.
4. println!("Hello, {}", message);: print a formatted string to STDOUT.

Now, do we need this package? Not at all, we can simply run the program, setting the environment variable on the command line, MESSAGE=world cargo run.

But dotenv gives us some helpful features:

1. We can easily switch between different .env files per environment (debug, staging, prod, etc). Normally, if we wanted to consume an entire .env file, setting the environment, we'd need to run something cryptic like export $(cat .env | xargs) && cargo run.
2. The program will deliberately crash if the environment variable is not found. This is super useful when we need to read a number of environment variables at program start and ensure they exist. When we typically deploy a Rust app using a cloud service, we want to know early if there is some environment configuration missing.

Now, we've gone over a number of Rust features in this code, which we will cover in detail in the subsequent lessons, but what you should understand coming away from this lesson is how to install a Rust crate.

If you wanted to specify an exact version of the crate to use, or enable specific add on features of a particular crate, the cargo add command will have optional flags allowing you to do this. Just run cargo help add to check out those features. Alternatively, you can simply edit Cargo.toml.

That's it for this lesson.

Remember to check out https://github.com/seenickcode/rustcrashcourse-lessons for the complete source code for this lesson.