A new project

In Getting Started with Rust, we will create a Markdown compiler called TinyMD, which will take a markdown file as input, convert the markdown to HTML, then write the HTML to a new file.

To start, let’s create a new project with cargo, the package manager and project building tool that comes from installing Rust.

We will scaffold this and all projects in Rust using the cargo tool, passing the new argument and specifying what we want:

$ cargo new tinymd --bin

The command cargo new builds a new project, and the --bin flag tells Cargo that you want this project built as an executable (called tinymd) instead of a library.

After running the command, you will get a confirmation that the project was scaffolded correctly. Go ahead and open the project’s root folder, tinymd.

# The structure of new Rust projects

Inside a newly created Rust project, you’ll find three things:

• A src folder, where your Rust code (Rust files end in .rs) lives
• A .gitignore file, because version control thinking is built-in
• A Cargo.toml file, which is the manifest file. This is the project configuration and dependencies script. This would be like the Gemfile in Ruby, or package.json in Node.

Anytime we create a new project like this, Rust sticks in some default code for us. Open up src/main.rs and let’s see what we can intuit about Rust’s syntax:

fn main() {
    println!("Hello, world!");
}

There’s so much we can infer from this tiny block of code:

• Functions are declared with fn;
• the printf equivalent is println!, which is a macro and not a function;
• this program does nothing more than print "Hello, world!" to the command line.

Before we get ahead of ourselves, let’s build this project. Open up your terminal (if you’re using VS Code, you can use the integrated terminal by typing Ctrl+`), and then type cargo build -q:

$ cargo build -q

The build command compiles your project and builds your executable. (This will be the last time I mention that the -q flag tells cargo to “be quiet” and not emit anything it doesn’t need to).

The executable is a “development” version. The main difference between a development and release version is that in a development version the code is not optimized and there are debug symbols (to help us track down issues) present that we would normally omit from a release version.

When Cargo is finished building your project, you’ll have a new folder named target in your project directory. Inside that folder is where you’ll find your executable.

We have covered two Cargo commands so far:

• cargo new, to create a new Rust project, and
• cargo build, to build a Rust project.

The third Cargo command we will often use is cargo run, which is how we will run the executable that our project builds.

Let’s try running our current project that we just built:

$ cargo run -q
Hello, world!

Note that we don’t need to pass the name of the project; Rust will infer that for us, by executing the appropriate binary based on the release target.

If you see “Hello, world!” in your terminal, then congratulations: you have built your first Rust program!

Let’s recap:

• Create a new Rust project with cargo new --bin my-neat-cli
• Build and run your project with cargo run

In the next section, we’ll dive into the Rust language and start customizing our markdown compiler to make it feel like an actual program.

“The best way out is always through.”

— Robert Frost