The Manifest Format
The 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:
[package]
The first section in a Scarb.toml
is [package]
.
[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 only required fields are name
and version
. If publishing to a registry, it's recommended to fill in additional fields:
It would also be a good idea to include some keywords
and categories
, though they are not required.
If package is not intended to be published, it is recommended to set publish
field to false.
name
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 (_
).
version
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.
edition
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_10"
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.
publish
The publish field is an optional key that determines whether the package can be published to a registry. Setting this field to false will prevent the package from being published. By default, this field is set to true
.
[package]
publish = true
cairo-version
The 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"
Setting the 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.
authors
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"]
description
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."
documentation
This field specifies a URL to a website hosting the crate's documentation.
[package]
documentation = "https://john.github.io/cairo-package"
readme
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.md
, README.txt
or 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.txt
or README
exists in the package root, in which case it will be used instead.
homepage
This field should be a URL to a site that is the home page for your package.
[package]
homepage = "https://example.com/"
repository
This field should be a URL to the source repository for your package.
[package]
repository = "https://github.com/software-mansion/scarb"
license
and license-file
The 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 Scarb.toml
).
Package registries must interpret the license
field as an SPDX 2 license expression. The license name must be a known license from the SPDX license list.
SPDX license expressions support AND and OR operators to combine multiple licenses.
[package]
license = "MIT OR Apache-2.0"
Using 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 license
field.
[package]
license-file = "LICENSE.txt"
keywords
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.
urls
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/"
experimental-features
This field is responsible for setting experimental flags to be used on the package for the compiler.
[package]
experimental-features = ["negative_impls"]
[dependencies]
See Specifying Dependencies page.
[dev-dependencies]
See Specifying Dependencies page.
Target tables: [lib]
and [[target]]
See Targets page.
[cairo]
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.
sierra-replace-ids
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 [6]
, with this flag turned on it might be:
- For libfuncs:
felt252_const<2>
orunbox<Box<Box<felt252>>>
. - For types:
felt252
orBox<Box<felt252>>
. - For user functions:
test::foo
.
By default, this flag is set to false
.
[cairo]
sierra-replace-ids = false
allow-warnings
If enabled, Scarb will not exit with error on compiler warnings. By default, this flag is set to true
.
[cairo]
allow-warnings = true
enable-gas
If enabled, during the project compilation Scarb will not add any instructions related to gas usage calculation. By default, this flag is set to true
.
[cairo]
enable-gas = true
This flag cannot be set to false
while compiling the starknet-contract
target.
inlining-strategy
This field is responsible for setting the inlining strategy to be used by compiler when building the package. The possible values are default
or avoid
. If avoid
strategy is set, the compiler will only inline function annotated with #[inline(always)]
attribute.
WARNING
Using the avoid
strategy may result in a slower execution of the compiled code and significantly larger artefacts size. Please use with caution, only if your tooling requires that. You can use profile settings overwriting, for more granular control of which builds use the avoid strategy.
add-redeposit-gas
WARNING
This is experimental and unstable flag intended to be used for Cairo compiler research. It is advised not to use it for other purposes than that.
If enabled, during the project compilation Scarb will add redeposit gas libfunc calls in some locations. By default, this flag is set to false
.
[cairo]
add-redeposit-gas = false
unstable-add-statements-functions-debug-info
WARNING
This is highly experimental and unstable feature intended to be used by cairo-profiler. It may slow down the compilation - it is advised not to use it for other purposes than running cairo-profiler.
If enabled, during the project compilation Scarb will a add mapping between Sierra statement indexes and vectors of fully qualified paths of Cairo functions to debug info. A statement index maps to a vector consisting of a function which caused the statement to be generated and all functions that were inlined or generated along the way. By default, this flag is set to false
.
[cairo]
unstable-add-statements-functions-debug-info = false
unstable-add-statements-code-locations-debug-info
WARNING
This is highly experimental and unstable feature intended to be used by cairo-coverage. It may slow down the compilation - it is advised not to use it for other purposes than running cairo-coverage.
If enabled, during the project compilation Scarb will add a mapping between Sierra statement indexes and locations in the code to debug info. A statement index maps to a vector consisting of code fragment which caused the statement to be generated and all code fragments that were inlined or generated along the way. By default, this flag is set to false
.
[cairo]
unstable-add-statements-code-locations-debug-info = false
[profile]
See Profiles page.
[scripts]
See Scripts page.
[tool]
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.
[workspace]
See Workspaces page.
[features]
See Features page.