Hello, Scarb

Scarb is the Cairo package manager and heavily inspired by Cargo, Rust’s build system and package manager.

Scarb handles a lot of tasks for you, such as building your code (either pure Cairo or Starknet contracts), downloading the libraries your code depends on, and building those libraries.

If we were to build the 'Hello, world!' project using Scarb, only the part of Scarb that handles building the code would be utilized, since the program doesn't require any external dependencies. As you write more complex Cairo programs, you’ll add dependencies, and if you start a project using Scarb, adding dependencies will be much easier to do.

Let's start by installing Scarb.

Installing Scarb

Requirements

Scarb requires a Git executable to be available in the PATH environment variable.

Installation

As for now, Scarb needs manual installation with the following steps:

  • Download the release archive matching your operating system and CPU architecture, from Scarb releases on GitHub

  • Extract it to a location where you would like to have Scarb installed, e.g. ~/scarb

  • Add path to the scarb/bin directory to your PATH environment variable.

    This depend on what shell you are using. Let’s take the example of zsh and you have extracted Scarb to ~/scarb:

    • Open ~/.zshrc file in your favorite editor
    • Add the following line to the end of the file: export PATH="$PATH:~/scarb/bin"

  • Verify installation by running the following command in new terminal session, it should print both Scarb and Cairo language versions, e.g:

    $ scarb --version
scarb 0.1.0 (289137c24 2023-03-28)
cairo: 1.0.0-alpha.6

Creating a Project with Scarb

Let’s create a new project using Scarb and look at how it differs from our original “Hello, world!” project.

Navigate back to your projects directory (or wherever you decided to store your code). Then run the following:

$ scarb new hello_scarb

It creates a new directory and project called hello_scarb. We’ve named our project hello_scarb, and Scarb creates its files in a directory of the same name.

Go into the hello_scarb directory with the command cd hello_scarb. You’ll see that Scarb has generated two files and one directory for us: a Scarb.toml file and a src directory with a lib.cairo file inside.

It has also initialized a new Git repository along with a .gitignore file

Note: Git is a common version control system. You can stop using version control system by using the --vcs flag. Run scarb new -help to see the available options.

Open Scarb.toml in your text editor of choice. It should look similar to the code in Listing 1-2.

Filename: Scarb.toml 
[package]
name = "hello_scarb"
version = "0.1.0"

# See more keys and their definitions at https://docs.swmansion.com/scarb/docs/reference/manifest

[dependencies]
# foo = { path = "vendor/foo" }
Listing 1-2: Contents of Scarb.toml generated by scarb new

This file is in the TOML (Tom’s Obvious, Minimal Language) format, which is Scarb’s configuration format.

The first line, [package], is a section heading that indicates that the following statements are configuring a package. As we add more information to this file, we’ll add other sections.

The next two lines set the configuration information Scarb needs to compile your program: the name and the version of Scarb to use.

The last line, [dependencies], is the start of a section for you to list any of your project’s dependencies. In Cairo, packages of code are referred to as crates. We won’t need any other crates for this project.

The other file created by Scarb is src/lib.cairo, let's delete all the content and put in the following content, we will explain the reason later.

mod hello_scarb;

Then create a new file called src/hello_scarb.cairo and put the following code in it:

Filename: src/hello_scarb.cairo 
use debug::PrintTrait;
fn main() {
    'Hello, Scarb!'.print();
}

We have just created a file called lib.cairo, which contains a module declaration referencing another module named "hello_scarb", as well as the file hello_scarb.cairo,containing the implementation details of the "hello_scarb" module.

Scarb requires your source files to be located within the src directory.

The top-level project directory is reserved for README files, license information, configuration files, and any other non-code-related content. Scarb ensures a designated location for all project components, maintaining a structured organization.

If you started a project that doesn’t use Scarb, as we did with the “Hello, world!” project, you can convert it to a project that does use Scarb. Move the project code into the src directory and create an appropriate Scarb.toml file.

Building a Scarb Project

From your hello_scarb directory, build your project by entering the following command:

$ scarb build
   Compiling hello_scarb v0.1.0 (file:///projects/Scarb.toml)
    Finished release target(s) in 0 seconds

This command creates a sierra file in target/release, let's ignore the sierra file for now.

If you have installed Cairo correctly, you should be able to run and see the following output:

$ cairo-run src/lib.cairo
[DEBUG] Hello, Scarb!                   (raw: 5735816763073854913753904210465)

Run completed successfully, returning []

Note: You will notice here that we didn't use a Scarb command, but rather a command from the Cairo binaries directly. As Scarb doesn't have a command to execute Cairo code yet, we have to use the cairo-run command directly. We will use this command in the rest of the tutorial, but we will also use Scarb commands to initialize projects.

Defining Custom Scripts

We can define Scarb scripts in Scarb.toml file, which can be used to execute custom shell scripts. Add the following line to your Scarb.toml file:

[scripts]
run-lib = "cairo-run src/lib.cairo"

Now you can run the following command to run the project:

$ scarb run run-lib
[DEBUG] Hello, Scarb!                   (raw: 5735816763073854913753904210465)

Run completed successfully, returning []

Using scarb run is a convenient way to run custom shell scripts that can be useful to run files and test your project.

Let’s recap what we’ve learned so far about Scarb:

  • We can create a project using scarb new.
  • We can build a project using scarb build to generate the compiled Sierra code.
  • We can define custom scripts in Scarb.toml and call them with the scarb run command.

An additional advantage of using Scarb is that the commands are the same no matter which operating system you’re working on. So, at this point, we’ll no longer provide specific instructions for Linux and macOS versus Windows.

Summary

You’re already off to a great start on your Cairo journey! In this chapter, you’ve learned how to:

  • Install the latest stable version of Cairo
  • Write and run a “Hello, world!” program using cairo-run directly
  • Create and run a new project using the conventions of Scarb

This is a great time to build a more substantial program to get used to reading and writing Cairo code.