The Manifest Format
Scarb.toml file, present in each package, is called its manifest. It is written in the TOML format. It contains metadata that is needed to compile the package. It has to be placed in the root of your project. Use the
scarb manifest-path command to locate the manifest used in current directory.
Every manifest file consists of the following sections:
The first section in a
[package] name = "hello_world" # the name of the package version = "0.1.0" # the current version, obeying semver authors = ["Alice <[email protected]>", "Bob <[email protected]>"]
The package name is a valid Cairo identifier used to refer to the package. It is used when listed as a dependency in another package, and as the default name of targets.
The name must use only ASCII lowercase alphanumeric characters or
_, and cannot be empty. It also must not be a valid Cairo keyword or a wildcard pattern (
Scarb bakes in the concept of Semantic Versioning, so make sure you follow some basic rules:
- Before you reach 1.0.0, anything goes, but if you make breaking changes, increment the minor version.
- After 1.0.0, only make breaking changes when you increment the major version. Do not break the build.
- After 1.0.0, don’t add any new public API in patch-level versions. Always increment the minor version if you add any new public structs, traits, fields, types, functions, methods, impls or anything else.
- Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
The edition key is an optional key that affects which Cairo edition your package is compiled with. The editions allow newer Cairo compiler versions to introduce opt-in features that may break existing code. Setting the edition key in
[package] will affect all targets in the package, including test suites etc.
[package] edition = '2023_01'
Most manifests have the edition field filled in automatically by
scarb new with the latest available edition. If the edition field is not present in Scarb.toml, then the default edition is assumed.
cairo-version field is an optional key that tells Scarb what version of the Cairo language and compiler your package can be compiled with. If the currently running version of the Scarb compiler does not match this requirement, Scarb will exit with an error, telling the user what version is required. This field takes a semver version requirement.
[package] cairo-version = "1.0.0"
cairo-version key in
[package] will affect all targets in the package. The value in this field will not affect the version of the compiler run by Scarb. Scarb always uses its built-in version of the Cairo compiler.
This optional field lists the people or organizations that are considered the "authors" of the package. The exact meaning is open to interpretation - it may list the original primary authors, current maintainers, or owners of the package. An optional email address may be included within angled brackets at the end of each author entry.
[package] authors = ["Software Mansion <[email protected]>", "Starkware"]
The description is a short blurb about the package. Package registries or indexers may display it with your package, some registries may even require it. This should be plain text (not Markdown).
[package] description = "A short description of my package."
This field specifies a URL to a website hosting the crate's documentation.
[package] documentation = "https://john.github.io/cairo-package"
This field should be the path to a file in the package root (relative to this
Scarb.toml) that contains general information about the package.
[package] readme = "README.md"
If no value is specified for this field, and a file named
README exists in the package root, then the name of that file will be used. You can suppress this behavior by setting this field to false. If the field is set to true, a default value of
README.md will be assumed, unless file named
README exists in the package root, in which case it will be used instead.
This field should be a URL to a site that is the home page for your package.
[package] homepage = "https://example.com/"
This field should be a URL to the source repository for your package.
[package] repository = "https://github.com/software-mansion/scarb"
license field contains the name of the software license that the package is released under. The
license-file field contains the path to a file containing the text of the license (relative to this
SPDX license expressions support AND and OR operators to combine multiple licenses.
[package] license = "MIT OR Apache-2.0"
OR indicates the user may choose either license. Using
AND indicates the user must comply with both licenses simultaneously. The
WITH operator indicates a license with a special exception. Some examples:
MIT OR Apache-2.0
LGPL-2.1-only AND MIT AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2
If a package is using a nonstandard license, then the
license-file field may be specified instead of the
[package] license-file = "LICENSE.txt"
This field is an array of strings that describe your package. This can help when searching for the package on a registry, and it is allowed to choose any words that would help someone find this package.
[package] keywords = ["account", "wallet", "erc-20"]
It is recommended that keywords are ASCII text, starting with a letter and only containing letters, numbers and
-. Additionally, keywords should have at most 20 characters, and single package should not provide more than 5 keywords.
This field is a map of additional internet links related to this package. Keys are human-readable link names, and values are URLs.
[package.urls] "We can help you build your project" = "https://swmansion.com/services/" "We're hiring" = "https://swmansion.com/careers/"
See Specifying Dependencies page.
See Targets page.
Adjust Cairo compiler configuration parameters when compiling this package. These options are not taken into consideration when this package is used as a dependency for another package.
Replace all names in generated Sierra code with dummy counterparts, representing the expanded information about the named items.
For libfuncs and types that would be recursively opening their generic arguments. For functions, that would be their original name in Cairo. For example, while the Sierra name be
, with this flag turned on it might be:
- For libfuncs:
- For types:
- For user functions:
[cairo] sierra-replace-ids = true
See Profiles page.
See Scripts page.
This section can be used for tools which would like to store package configuration in Scarb.toml. Scarb by default will warn about unused keys in Scarb.toml to assist in detecting typos and such. The
[tool] table, however, is completely ignored by Scarb and will not be warned about. For example:
[tool.snforge] exit-first = true
No fields in this section are required or defined by Scarb. Each field can accept any valid toml value including a table.
See Workspaces page.