Rust Programming By Example: Enter the world of Rust by building engaging, concurrent, reactive, and robust applications

In Rust, packages (both binaries and libraries) are named crates. You can find a lot of them on crates.io. Today, we'll use the SDL2 crate in order to make our tetris, but before even thinking about this, we need to install the SDL2library that is used by the SDL2 crate!

Before going any further, we need to install the SDL library.

$ sudo apt-get install libsdl2-dev

$ sudo dnf install SDL2-devel

$ yum install SDL2-devel

$ brew install sdl2

        gnu-mingw\dll\32
       ...

The Rust package manager, cargo, allows us to create a new project very easily with just one command, cargo new. Let's run it as follow:

  cargo new tetris --bin

You should have a new folder tetris containing the following:

     tetris/
     |
     |- Cargo.toml
     |- src/
         |
         |- main.rs

Note that if you ran cargo new without the --bin flag, then you will have a lib.rs file instead of main.rs.

Now write this into your Cargo.toml file:

    [package]
    name = "tetris"
    version = "0.0.1"

    [dependencies]
    sdl2 = "0.30.0"

Here, we declare that our project's name is tetris, its version is 0.0.1 (it isn't really important at the moment), and that it has a dependency on the sdl2 crate.

For the versioning, Cargo follows SemVer (Semantic Versioning). It works as follows:

[major].[minor].[path]

So here's exactly what every part means:

Before going any further, we need to talk about how file hierarchy works in Rust through its modules.

The first thing to know is that files and folders are handled as modules in Rust. Consider the following:

|- src/
    |
    |- main.rs
    |- another_file.rs

If you want to declare that a module is in the another_file.rs file, you'll need to add to your main.rs file:

    mod another_file;

You will now have access to everything contained in another_file.rs (as long as it's public).

Another thing to know: you can only declare modules whose files are on the same level as your current module/file. Here's a short example to sum this up:

|- src/
    |
    |- main.rs
    |- subfolder/
        |- another_file.rs

If you try to declare a module referring to another_file.rs directly into main.rs, as shown preceding, it'll fail because there are no another_file.rs in src/. In this case, you'll need to do three things:

Okay, we're now ready to start writing down our tetris!

First, let's fulfill our main.rs file in order to check whether everything is working as expected:

    extern crate sdl2;

    use sdl2::pixels::Color;
    use sdl2::event::Event;
    use sdl2::keyboard::Keycode;
    use std::time::Duration;
    use std::thread::sleep;

    pub fn main() {
      let sdl_context = sdl2::init().expect("SDL initialization   
      failed");
      let video_subsystem = sdl_context.video().expect("Couldn't get 
       SDL video subsystem");

      let window = video_subsystem.window("rust-sdl2 demo: Video", 800,
            600)
        .position_centered()
        .opengl()
        .build()
        .expect("Failed to create window");

      let mut canvas = window.into_canvas().build().expect("Failed to
        convert window into canvas");

      canvas.set_draw_color(Color::RGB(255, 0, 0));
      canvas.clear();
      canvas.present();
      let mut event_pump = sdl_context.event_pump().expect("Failed...

The previous example created a window and drew into it. Now let's see how it did that!

Before going any further, we need to import the SDL2 crate, as follows:

    extern crate sdl2;

With this, we now have access to everything it contains.

Now that we've imported sdl2, we need to initialize an SDL context:

    let sdl_context = sdl2::init().expect("SDL initialization failed");

Once done, we need to get the video subsystem:

    let video_subsystem = sdl_context.video().expect("Couldn't get SDL 
      video subsystem");

We can now create the window:

    let window = video_subsystem.window("Tetris", 800, 600)
                            .position_centered()
                            .opengl()
                            .build()
                            .expect("Failed to create window");

A few notes on these methods:

We now have a working window; it'd be nice to draw into it. First, we need to get the window's canvas before starting the main loop:

    let mut canvas = window.into_canvas()
                       .target_texture()
                       .present_vsync()
                       .build()
                       .expect("Couldn't get window's canvas");

A few explanations for the preceding code:

Then we'll create a texture that we'll paste onto the window's canvas. First, let's get the texture creator, but before that, add this include at the top of the file:

    use sdl2::render::{Canvas, Texture, TextureCreator};

Now we can get the texture creator:

    let texture_creator: TextureCreator<_> = canvas.texture_creator...

Let's start with the basics. First, let's open and write into a file:

    use std::fs::File;
    use std::io::{self, Write};

    fn write_into_file(content: &str, file_name: &str) -> io::Result<()> {
      let mut f = File::create(file_name)?;
      f.write_all(content.as_bytes())
    }

Now let's explain this code:

    use std::fs::File;

Nothing fancy, we just import the File type:

   use std::io::{self, Write};

This set of imports is more interesting: we import the io module (self) and the Write trait. For the second, if we didn't import it, we wouldn't be able to use the write_all method (because you need to import a trait to use its methods):

   fn write_into_file(content: &str, file_name: &str) -> io::Result<()> {

We declared a function named write_into_file that takes a filename and the content you want to write into the file as arguments. (Note that the file will be overwritten by this content!) It returns an io::Result type. It is an alias...

In this chapter, we saw a lot of important things like how to use Cargo (through the Cargo.toml file), how to import new crates into a project, thanks to Cargo, and the basics for Rust modules handling. We even covered how to use iterators and read and write files, SDL2 basics like how to create a window and fill it with colors, and loading/creating new textures and images (thanks to the SDL2-image library!).

In Chapter 3, Events and Basic Game Mechanisms, we'll start the implementation of the tetris game, so be sure to master everything explained in this chapter before starting the next one!