Say hello to Scarb, a Cairo package manager

TL;DR

1. Scarb is a new package manager and build tool for Cairo 1.0.
2. Scarb is open source and the first alpha release is already available to download!
3. Scarb has been created by Software Mansion in close collaboration with StarkWare.
4. Its goal is to be a tool for developing any Cairo projects, not only StarkNet contracts.
5. Scarb takes a big inspiration from Cargo and should be familiar to its users.
6. Scarb will feature an extensibility system, allowing users to augment its behaviours and feature set to suit particular projects’ use cases.
7. We plan to repurpose Protostar as a Scarb extension for developing StarkNet contracts.

Introduction

We are pleased to announce the first alpha release of Scarb, a build toolchain and package manager for everything Cairo 1.0!

1. Scarb provides easy means to scaffold new Cairo projects.
2. Scarb nicely wraps Cairo compiler and allows building these projects easily.
3. Scarb enables adding external dependencies to Cairo projects, and it automatically picks the most compatible versions and downloads all packages from remote sources.
4. Scarb is modelled after Rust’s Cargo, and we want it to be familiar to Cargo’s daily users.
5. Finally, Scarb is meant to be the platform for building Cairo tooling. It will feature an extensibility system, allowing users to extend its feature set (for example by adding a test runner or profile) and augment its behaviours (for example by teaching it how to compile StarkNet contracts).

Scarb is being developed by a team at Software Mansion, spun off the Protostar team, and we are closely collaborating with StarkWare while working on this project.

FYI: The “Scarb” name is not random: it’s a play on the very Egyptian word “scarab”, “skarb” means “treasure” in Polish, but with “c” you can easily type it with one hand on most keyboard layouts.

First taste

Installation

Installation archives are available to download from our GitHub releases page.

Scarb supports all three major platforms and official builds are provided for Windows, macOS (both Apple Silicon and Intel) and Linux.

Currently, Scarb is just a single executable binary. Upon extracting the downloaded archive suited for your machine, simply move the scarb (or scarb.exe for Windows) file to a directory that is listed in your PATH environment variable (or make a new one and add it to PATH).

You can run scarb --help or scarb --version to check that everything works. Note that some commands listed by the help may panic with TODO messages, as this is still in alpha state.

Creating a new project

The scarb new command allows you to scaffold a basic project template. It works just like cargo new thus should be familiar to you if you used to code in Rust.

The Scarb.toml file (just like Cargo.toml) is called a manifest file and will be the root of information about your project. The scaffolding command populates the package name here and inserts hints on how to add new dependencies to the project.

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

# See more keys and their definitions at https://github.com/software-mansion/scarb/blob/main/scarb/src/core/manifest/toml.rs

[dependencies]
# foo = { path = "vendor/foo" }

Building code

Run the scarb build command to get the Sierra code of your package. Output artifacts will be located in the target/release directory.

Adding new dependencies

The initial version supports only one dependency type: via a path to a local directory. The syntax is identical to Cargo’s one, and like in Cargo, you can pass full SemVer version requirements to ensure compatibility with your code.

package_name = { version = "X.Y.Z", path = "../path/to/package" }

Note: Unlike Cargo, Scarb will not support dashes in package names.

Like Cargo, Scarb will automatically pull new dependencies when building code. There will be no scarb install like it is in Poetry or NPM.

What is already working?

Apart from what has been already described — not a lot.

The simpleclean and init commands are working as intended.

The scarb metadata command outputs a JSON description of Scarb’s knowledge about the project. Its purpose is to be consumed by external tooling, primarily IDEs and editors. Thanks to this command, we will be able to add Scarb support in CairoLS.

Finally, we implemented the first step towards extensibility: external subcommands. This pattern should be familiar if you have ever used Git external commands, or you cargo install‘ed commands like cargo bloat. If Scarb is run with an unknown command (let’s say thecommand), it will try to find an executable named scarb-thecommand in PATH (or scarb-thecommand.exe in the case of Windows).

Future plans

We maintain a public roadmap here.

In the near future, we aim to support pulling dependencies from Git repositories.

We have not yet decided how we will solve indexing public general-use Cairo packages, whether this will mean building a centralized package registry, or looking for other solutions. This is a subject of active brainstorming internally. We encourage external contributors to participate in the discussion and post thoughts here. We expect the mix of local & Git dependencies to be sufficient in a few months term.

The next big milestone is to support developing StarkNet contracts with Scarb. First iterations will certainly be based on hardcoded behaviours, but in the future we foresee providing a system of extensible build targets, supplied by the already existing external subcommands. Deeper details are still murky here.

Finally, we also want to make installation of the Cairo toolchain and several important extensions (like the future StarkNet one) straightforward. For this purpose, we plan to create an installation manager similar to rustup or asdf.

What about Protostar?

Protostar is a toolchain for developing and testing with Cairo contracts for StarkNet. While it does not focus on package management, it has a powerful testing framework, Cairo profiler and a toolkit for deploying contracts.

Scarb and Protostar seem to cover the same problem spaces. This is quite true as both function as a toolchain and handle Cairo compilation, but there is a significant difference between these two tools in their current forms: Protostar is focused on StarkNet contracts development only, and is developed in Python, making great use of the cairo-lang package.

The Protostar team has embarked on a journey and are making great progress to port it to Cairo 1.0 and make its test runner StarkNet agnostic. In the meantime, with Scarb we are laying solid foundations for generic Cairo project management. There is a meeting point in these stories: in the future we plan to make Protostar an extension to Scarb for developing everything StarkNet, and probably:

1. protostar test may become scarb protostar or even scarb test, and it will also contain Protostar’s fuzzer and profiler.
2. Analogically, protostar declare/deploy/invoke commands family will become scarb starknet declare/deploy/invoke.
3. Protostar will entirely be implemented in Rust.

We invite the Cairo and StarkNet community to experiment with Scarb and provide us feedback on this tool. We will be glad to be in touch on our Issues and general Discussions sites.

Make sure to stay tuned, track Scarb progress, and we wish you happy coding!