Specifying Dependencies

Your packages can depend on other libraries from registries, Git repositories, or subdirectories on your local file system.

Specifying dependencies from registries

Scarb supports the official cairo package registry scarbs.xyz by default. You can see the list of available packages by visiting the website. To depend on a package located in the registry, you need to specify the package name and the version requirement:

[dependencies]
alexandria_math = "0.1.0"

Alternatively, you can specify the version requirement with the version key:

[dependencies]
alexandria_math = { version = "0.1.0" }

The two formats above are equivalent.

Unlike other dependency types, it is required to specify the version requirement for packages from the registry.

To use a custom, non-official registry you need to specify its url address as well:

[dependencies]
alexandria_math = { registry = "https://example.com/", version = "0.1.0" }

Security and audits

Scarb supports filtering packages from the registry based on whether they have been audited.

WARNING

Note: package version being audited does not mean there are no bugs or vulnerabilities in the package, just that the process has been undergone by the entity that is considered the authority in the registry.

You can enable this feature by specifying the require-audits key in the [workspace] section of the workspace root manifest:

[workspace]
require-audits = true

Setting this field to true will cause Scarb to ignore any versions of dependencies, including transitive ones, that are not marked as audited in the registry. If unable to resolve the dependency tree due to this, Scarb will exit with an error.

NOTE

This setting does not affect [dev-dependencies].

By default, this field is set to false. This policy applies to the entire workspace. This field is ignored in member packages manifest files, and only the one defined in the workspace root manifest is applied when compiling member packages.

You may whitelist specific packages to ignore the require-audits setting by specifying them in the allow-no-audits key:

[workspace]
allow-no-audits = ["alexandria_math"]

WARNING

This setting is not transitive, meaning that dependencies of the whitelisted packages will still be filtered based on the require-audits setting, unless they are also explicitly whitelisted.

Specifying dependencies from Git repositories

To depend on a package located in a Git repository, the minimum information needed to specify is the location of the repository with the git key:

[dependencies]
alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria.git" }

Scarb will fetch the git repository at this location and then look for a Scarb.toml for the requested package anywhere inside the Git repository (not necessarily at the root of it - for example, if repository contains multiple packages in subdirectories).

Since no other information has been specified, Scarb assumes that it is intended to use the latest commit on the main branch. You can combine the git key with branch, tag and rev keys to specify something else. Here is an example of specifying that you want to use the latest commit on a branch named next:

[dependencies]
alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria.git", branch = "next" }

Anything that is not a branch or tag falls under rev. This can be a commit (short) hash, like rev = "1f06df93", or a named reference exposed by the remote repository such as rev = "refs/pull/330/head". What references are available varies by where the repository is hosted; GitHub in particular exposes a reference to the most recent commit of every pull request as shown, but other Git hosts often provide something equivalent, possibly under a different naming scheme.

Specifying path dependencies

Scarb supports path dependencies, which are typically sub-packages that live within one repository. To depend on a package located in a local directory, you need to specify the path to it, relative to current Scarb.toml, with the path key:

[dependencies]
hello_utils = { path = "hello_utils" }

Scarb does not cache path dependencies, any changes made in them will be reflected immediately in builds of your package.

Development dependencies

In order to add development dependency, specify it under [dev-dependencies] section:

[dev-dependencies]
alexandria_math = "0.1.0"

Development dependencies are not used when compiling a package for building, but are used for compiling tests.

These dependencies are not propagated to other packages which depend on this package.

Version requirements

Scarb allows you to specify version requirements of dependencies with the version key:

[dependencies]
hello_utils = { version = "1.0.0", path = "hello_utils" }

The string "1.0.0" is a version requirement. Although it looks like a specific version of the hello_utils package, it actually specifies a range of versions and allows SemVer compatible updates. Scarb uses Rust's SemVer flavour, in a way implemented by the semver crate. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping.

Here are some more examples of version requirements and the versions that would be allowed with them:

1.2.3  :=  >=1.2.3, <2.0.0
1.2    :=  >=1.2.0, <2.0.0
1      :=  >=1.0.0, <2.0.0
0.2.3  :=  >=0.2.3, <0.3.0
0.2    :=  >=0.2.0, <0.3.0
0.0.3  :=  >=0.0.3, <0.0.4
0.0    :=  >=0.0.0, <0.1.0
0      :=  >=0.0.0, <1.0.0

This compatibility convention is different from SemVer in the way it treats versions before 1.0.0. While SemVer says there is no compatibility before 1.0.0, Scarb considers 0.x.y to be compatible with 0.x.z, where y ≥ z and x > 0.

It is possible to further tweak the logic for selecting compatible versions using special operators, though it shouldn't be necessary most of the time.

Caret requirements

Caret requirements are an alternative syntax for the default strategy, ^1.2.3 is exactly equivalent to 1.2.3.

Tilde requirements

Tilde requirements specify a minimal version with some ability to update. If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed. If you only specify a major version, then minor- and patch-level changes are allowed.

~1.2.3 is an example of a tilde requirement.

~1.2.3  := >=1.2.3, <1.3.0
~1.2    := >=1.2.0, <1.3.0
~1      := >=1.0.0, <2.0.0

Wildcard requirements

Wildcard requirements allow for any version where the wildcard is positioned.

*, 1.* and 1.2.* are examples of wildcard requirements.

*     := >=0.0.0
1.*   := >=1.0.0, <2.0.0
1.2.* := >=1.2.0, <1.3.0

Comparison requirements

Comparison requirements allow manually specifying a version range or an exact version to depend on.

Here are some examples of comparison requirements:

>= 1.2.0
> 1
< 2
= 1.2.3

Multiple requirements

As shown in the examples above, multiple version requirements can be separated with a comma, e.g., >= 1.2, < 1.5.