Rust: your first package

Next: An IDE for your project
Previous: Getting started

So, you’ve installed the tools and you’re ready to get started. What now? Hello world is satisfying but not very practical. It’s time to create your first package. Open the Visual Studio x64 command prompt. It’s important that the architecture (x64) matches what Rust assumes as its default. It should look something like this:

Now change to a directory where you can create a few projects. I tend to use a root directory called git for all my projects:

C:\git>

There are a few reasons for this. The obvious one being that I tend to use Git for version-control. The other is that a default installation of Windows does not include any other folder starting with a G in the root of the C drive, making it easy to switch to the git folder with tab completion, otherwise I might have gone with something like “projects” if not for the two or three folders that start with a P.

Last time I introduced the Cargo tool just enough to print out the Rust version. In a moment, we’re going to use it do something useful. As a Windows developer, you might fire up Visual Studio and use that to create a new project. There are numerous project templates for all manner of languages and applications. As a Rust developer, you’re going to use cargo to do that and much more.

But first, I want to dispel any mystery around what a Rust package is. If you’ve spent any time with Visual Studio, particularly as a C++ developer, you know that managing project configurations can be a nightmare. Fortunately, Rust packages are quite simple to the point where you can easily create them by hand. It helps to do this at least once so that you understand just what makes up a Rust package.

There are two main kinds of project or package types in Rust. I’ll talk about a third category a little later in this series. You can create a binary package or a library package. A binary package produces an executable that you can run, just like any Windows executable. A library package is similar to a C++ library.

Start by creating a folder for your package and switching to that folder:

C:\git>md hello

C:\git>cd hello

Now create a text file called cargo.toml in this folder:

C:\git\hello>notepad cargo.toml

A .toml file is similar to a .ini file with an actual specification, making for a very simple way to define key/value pairs for describing and configuring your Rust package and its dependencies. Unlike the horrendously complicated XML format used by Visual Studio, you can actually write your package’s cargo.toml file by hand without any difficulty. Here’s all you’ll need to get started:

[package]
name = "hello"
version = "0.1.0" 

That’ll do. Be sure to save that in the cargo.toml file in the root of the package folder. You’ll notice that it doesn’t say anything about what kind of package this is or how it ought to be built. Much of that will be inferred. Cargo will figure this out based on what Rust source files are present. Having created the cargo.toml file, you can now create a src subfolder for the package’s source code.

C:\git\hello>md src

Within the src folder, you can create one of two Rust source files. If you create a file named main.rs then cargo will assume you are creating a binary package. If on the other hand you create a file named lib.rs then cargo will assume you are creating a library package. Let’s start with a binary package.

C:\git\hello>notepad src\main.rs

A .rs file is where you write your Rust source code, much like .cs files for C# and .cpp/.h files for C++. Here again is the simple Hello World example we used last time:

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

Be sure to save that in the src\main.rs source file. And that’s it: you’ve created your first Rust package! You can now use Cargo to build the package as follows:

C:\git\hello>cargo build

You’ll notice that running the Cargo build command caused a few other artifacts to be created, but you should only consider the cargo.toml file along with any source files in the src subfolder to be the actual source code for your project that you might include in version control. You will notice that Cargo created a file called Cargo.lock in your package folder. This file is entirely managed by Cargo and you should not edit it yourself. There are reasons why you may or may not want to include this file in version control, but we’ll talk about that later. More importantly, the Cargo build command created an executable from your package:

C:\git\hello>dir /s /b hello.exe
C:\git\hello\target\debug\hello.exe

You can run this directly:

C:\git\hello>target\debug\hello.exe
Hello world!

And if it’s more convenient, you can have Cargo run it for you:

C:\git\hello>cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
     Running `target\debug\hello.exe`
Hello world!

The cargo tool also provides commands for creating packages so you can save yourself a few moments if so desired. You can ask Cargo to create a binary package as follows:

C:\git>cargo new hello
     Created binary (application) `hello` package

C:\git>cd hello

C:\git\hello>cargo build
   Compiling hello v0.1.0 (C:\git\hello)
    Finished dev [unoptimized + debuginfo] target(s) in 0.71s

Of course, you already know that there’s no magic here. It just created the cargo.toml file, the src subfolder, and a main.rs file with a simple main function to get you started. You can also have Cargo create a package in the current folder, rather than a subfolder, using the Cargo init command. Note that Cargo will also default to turning your package into a Git repo. If you’d rather not have it do that you can opt out as follows:

C:\git>cargo new hello --vcs none

OK, you’ve created your first Rust package. Wasn’t that easy! Now what about library packages? And where’s the IDE?! Join me next time for the adventures of a C++ developer learning Rust.

1 thought on “Rust: your first package

  1. Ryan

    Glad to see you are starting to write about Rust. Eventually I hope to see how to write Rust/WinRT applications! Any chance of making some more advanced Rust courses for Pluralsight?

    Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s