Getting Started with “Hello, world!”

It seems the universally agreed-upon way to start learning a programming language is printing “Hello, world!” to the screen. Change to a temporary directory with cd /tmp to write this first program. We’re just messing around, so we don’t need a real directory yet. Then fire up a text editor and type the following code into a file called hello.rs:

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

Functions are defined using fn. The name of this function is main.

println! (print line) is a macro and will print text to STDOUT (pronounced standard out). The semicolon indicates the end of the statement.

The body of the function is enclosed in curly braces.

Rust will automatically start in the main function. Function arguments appear inside the parentheses that follow the name of the function. Because there are no arguments listed in main(), the function takes no arguments. The last thing I’ll point out here is that println! looks like a function but is actually a macro, which is essentially code that writes code. All the other macros I use in this book—such as assert! and vec!—also end with an exclamation point.

$ rustc hello.rs

> rustc.exe .\hello.rs

If all goes well, there will be no output from the preceding command, but you should now have a new file called hello on macOS and Linux or hello.exe on Windows. This is a binary-encoded file that can be directly executed by your operating system, so it’s common to call this an executable or a binary. On macOS, you can use the file command to see what kind of file this is:

$ file hello
hello: Mach-O 64-bit executable x86_64

$ ./hello 
Hello, world!

The dot (.) indicates the current directory.

> .\hello.exe
Hello, world!

Congratulations if that was your first Rust program. Next, I’ll show you how to better organize your code.

In your Rust projects, you will likely write many files of source code and will also use other people’s code from places like crates.io. It’s best to create a directory for each project, with a src subdirectory for the Rust source code files. On a Unix system, you’ll first need to remove the hello binary with the command rm hello because that is the name of the directory you will create. Then you can use the following command to make the directory structure:

$ mkdir -p hello/src 

The mkdir command will make a directory. The -p option says to create parent directories before creating child directories. PowerShell does not require this option.

$ mv hello.rs hello/src

Use the cd command to change into that directory and compile your program again:

$ cd hello
$ rustc src/hello.rs

You should now have a hello executable in the directory. I will use the tree command (which you might need to install) to show you the contents of my directory:

$ tree
.
├── hello
└── src
    └── hello.rs

An easier way to start a new Rust project is to use the Cargo tool. You can delete your temporary hello directory:

$ cd .. 
$ rm -rf hello 

Change into the parent directory, which is indicated with two dots (..).

The -r recursive option will remove the contents of a directory, and the -f force option will skip any errors.

$ cargo new hello
     Created binary (application) `hello` package

$ cd hello
$ tree
.
├── Cargo.toml 
└── src 
    └── main.rs 

Cargo.toml is a configuration file for the project. The extension .toml stands for Tom’s Obvious, Minimal Language.

The src directory is for Rust source code files.

main.rs is the default starting point for Rust programs.

You can use the following cat command (for concatenate) to see the contents of the one source file that Cargo created (in Chapter 3, you will write a Rust version of cat):

$ cat src/main.rs
fn main() {
    println!("Hello, world!");
}

Rather than using rustc to compile the program, this time use cargo run to compile the source code and run it in one command:

$ cargo run
   Compiling hello v0.1.0 (/private/tmp/hello) 
    Finished dev [unoptimized + debuginfo] target(s) in 1.26s
     Running `target/debug/hello`
Hello, world! 

The first three lines are information about what Cargo is doing.

This is the output from the program.

If you would like for Cargo to not print status messages about compiling and running the code, you can use the -q, or --quiet, option:

$ cargo run --quiet
Hello, world!

After running the program using Cargo, use the ls command to list the contents of the current working directory. (You will write a Rust version of ls in Chapter 14.) There should be a new directory called target. By default, Cargo will build a debug target, so you will see the directory target/debug that contains the build artifacts:

$ ls
Cargo.lock  Cargo.toml  src/        target/

You can use the tree command from earlier or the find command (you will write a Rust version of find in Chapter 7) to look at all the files that Cargo and Rust created. The executable file that ran should exist as target/debug/hello. You can execute this directly:

$ ./target/debug/hello
Hello, world!

$ cat Cargo.toml
[package]
name = "hello" 
version = "0.1.0" 
edition = "2021" 

# See more keys and their definitions at 
# https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies] 

This was the name of the project I created with Cargo, so it will also be the name of the executable.

This is the version of the program.

This is the edition of Rust that should be used to compile the program. Editions are how the Rust community introduces changes that are not backward compatible. I will use the 2021 edition for all the programs in this book.

This is a comment line that I will include only this one time. You can remove this line from your file, if you like.

This is where you will list any external crates your project uses. This project has none at this point, so this section is blank.

More than the act of testing, the act of designing tests is one of the best bug preventers known. The thinking that must be done to create a useful test can discover and eliminate bugs before they are coded—indeed, test-design thinking can discover and eliminate bugs at every stage in the creation of software, from conception to specification, to design, coding, and the rest.

Boris Beizer, Software Testing Techniques (Van Nostrand Reinhold)

Even though “Hello, world!” is quite simple, there are still things that could bear testing. There are two broad categories of tests I will show in this book. Inside-out or unit testing is when you write tests for the functions inside your program. I’ll introduce unit testing in Chapter 4. Outside-in or integration testing is when you write tests that run your programs as the user might, and that’s what we’ll do for this program. The convention in Rust projects is to create a tests directory parallel to the src directory for testing code, and you can use the command mkdir tests for this.

The goal is to test the hello program by running it on the command line as the user will do. Create the file tests/cli.rs for command-line interface (CLI) with the following code. Note that this function is meant to show the simplest possible test in Rust, but it doesn’t do anything useful yet:

#[test] 
fn works() {
    assert!(true); 
}

The #[test] attribute tells Rust to run this function when testing.

The assert! macro asserts that a Boolean expression is true.

$ tree -L 2
.
├── Cargo.lock 
├── Cargo.toml
├── src 
│   └── main.rs
├── target 
│   ├── CACHEDIR.TAG
│   ├── debug
│   └── tmp
└── tests 
    └── cli.rs

The Cargo.lock file records the exact versions of the dependencies used to build your program. You should not edit this file.

The src directory is for the Rust source code files to build the program.

The target directory holds the build artifacts.

The tests directory holds the Rust source code for testing the program.

All the tests in this book will use assert! to verify that some expectation is true, or assert_eq! to verify that something is an expected value. Since this test is evaluating the literal value true, it will always succeed. To see this test in action, execute cargo test. You should see these lines among the output:

running 1 test
test works ... ok

To observe a failing test, change true to false in the tests/cli.rs file:

#[test]
fn works() {
    assert!(false);
}

running 1 test
test works ... FAILED

Now, let’s create a more useful test that executes a command and checks the result. The ls command works on both Unix and Windows PowerShell, so we’ll start with that. Replace the contents of tests/cli.rs with the following code:

use std::process::Command; 

#[test]
fn runs() {
    let mut cmd = Command::new("ls"); 
    let res = cmd.output(); 
    assert!(res.is_ok()); 
}

Import std::process::Command. The std tells us this is in the standard library and is Rust code that is so universally useful it is included with the language.

Create a new Command to run ls. The let keyword will bind a value to a variable. The mut keyword will make this variable mutable so that it can change.

Run the command and capture the output, which will be a Result.

Verify that the result is an Ok variant.

running 1 test
test runs ... ok

Update tests/cli.rs with the following code so that the runs function executes hello instead of ls:

use std::process::Command;

#[test]
fn runs() {
    let mut cmd = Command::new("hello");
    let res = cmd.output();
    assert!(res.is_ok());
}

running 1 test
test runs ... FAILED

$ hello
-bash: hello: command not found

When you execute any command, your operating system will look in a predefined set of directories for something by that name.1 On Unix-type systems, you can inspect the PATH environment variable of your shell to see this list of directories, which are delimited by colons. (On Windows, this is $env:Path.) I can use tr (translate characters) to replace the colons (:) with newlines (\n) to show you my PATH:

$ echo $PATH | tr : '\n' 
/opt/homebrew/bin
/Users/kyclark/.cargo/bin
/Users/kyclark/.local/bin
/usr/local/bin
/usr/bin
/bin
/usr/sbin
/sbin

$PATH tells bash to interpolate the variable. Use a pipe (|) to feed this to tr.

$ cd target/debug/
$ hello
-bash: hello: command not found

$ ./hello
Hello, world!

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

[dependencies]

[dev-dependencies]
assert_cmd = "1"

use assert_cmd::Command; 

#[test]
fn runs() {
    let mut cmd = Command::cargo_bin("hello").unwrap(); 
    cmd.assert().success(); 
}

running 1 test
test runs ... ok

TRUE(1)                   BSD General Commands Manual                  TRUE(1)

NAME
     true -- Return true value.

SYNOPSIS
     true

DESCRIPTION
     The true utility always returns with exit code zero.

SEE ALSO
     csh(1), sh(1), false(1)

STANDARDS
     The true utility conforms to IEEE Std 1003.2-1992 (''POSIX.2'').

BSD                              June 27, 1991                             BSD

$ true
$ echo $?
0

$ false
$ echo $?
1

fn main() {
    std::process::exit(0); 
}

$ tree src/
src/
├── bin
│   └── true.rs
└── main.rs

$ cargo run --quiet --bin true 
$ echo $?
0

#[test]
fn true_ok() {
    let mut cmd = Command::cargo_bin("true").unwrap();
    cmd.assert().success();
}

running 2 tests
test true_ok ... ok
test runs ... ok

fn main() {}

fn main() {
    std::process::exit(1); 
}

$ cargo run --quiet --bin false
$ echo $?
1

#[test]
fn false_not_ok() {
    let mut cmd = Command::cargo_bin("false").unwrap();
    cmd.assert().failure(); 
}

running 3 tests
test runs ... ok
test true_ok ... ok
test false_not_ok ... ok

fn main() {
    std::process::abort();
}

#[test]
fn runs() {
    let mut cmd = Command::cargo_bin("hello").unwrap();
    cmd.assert().success().stdout("Hello, world!\n"); 
}

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

running 3 tests
test true_ok ... ok
test false_not_ok ... ok
test runs ... FAILED

failures:

---- runs stdout ----
thread 'runs' panicked at 'Unexpected stdout, failed diff var original
├── original: Hello, world!

├── diff:
--- value	expected
+++ value	actual
@@ -1 +1 @@
-Hello, world! 
+Hello, world!!! 

└── var as str: Hello, world!!!


command=`".../hello/target/debug/hello"` 
code=0  
stdout=```"Hello, world!!!\n"``` 
stderr=```""``` 

$ true && ls
Cargo.lock  Cargo.toml  src/        target/     tests/

$ false && ls
$ echo $?
1