0.5.0-alpha.1

Scarb 0.5.0-alpha.1

Welcome to the release notes for Scarb v0.5.0-alpha.1!

Note: This version is not yet supported on Starknet! If you want to develop contracts deployable to current Starknet v0.11, please stick with Scarb v0.4.

---

This is a quick release that comes with support for the latest Cairo v2.0.0-rc3 release!

Cairo version

This version of Scarb comes with Cairo v2.0.0-rc3.

What's Changed

• Improve building experience for packagers by @fracek in #421
• Prepare release 0.5.0-alpha.1 by @maciektr in #424

New Contributors

• @fracek made their first contribution in #421

Full Changelog: v0.5.0-alpha.0...v0.5.0-alpha.1

0.5.0-alpha.0

Scarb 0.5.0-alpha.0

Welcome to the release notes for Scarb v0.5.0-alpha.0!

Note: This version is not yet supported on Starknet! If you want to develop contracts deployable to current Starknet v0.11, please stick with Scarb v0.4.

---

This is a quick release that comes with support for the latest Cairo v2.0.0-rc2 release!

Cairo version

This version of Scarb comes with Cairo v2.0.0-rc2.

What's Changed

• Introduce internal::serdex module and RelativeUtf8PathBuf to solve TOML paths issues by @mkaput in #407
• docs: fix typo by @tserg in #409
• Update Cairo to 2.0.0-rc2 by @maciektr in #412
• Prepare release 0.5.0-alpha.0 by @maciektr in #418

New Contributors

• @tserg made their first contribution in #409

Full Changelog: v0.4.0...v0.5.0-alpha.0

0.4.0

Scarb 0.4.0

Welcome to release notes for Scarb v0.4.0! This is a significant release, bringing two new highly requested features.

NOTE: This release has not been published to crates.io, because we had to backport a few commits to Cairo 1.1.0. We're sorry for the inconvenience.

scarb test

The scarb test command executes all unit and integration tests of a local package. It is not a test runner by itself, but rather delegates work to a testing solution of choice. Scarb comes with preinstalled scarb cairo-test extension, which bundles Cairo's native test runner. It is the default test runner used by scarb test.

Our examples in the repository now contain several tests, and you can check out this feature by quickly running scarb test over them:

$ cd examples/starknet_hello_world
$ scarb test
testing starknet_hello_world ...
running 1 tests
test starknet_hello_world::tests::test_flow ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 filtered out;

The behaviour of the scarb test command can be changed by developers. To do so, provide a script named explicitly test in the current workspace Scarb.toml:

[scripts]
test = "protostar test"

For more information, check out the dedicated Testing documentation page.

Allowed libfuncs validation for Starknet contracts

Not all Sierra libfuncs emitted by the Cairo compiler can be deployed to Starknet, as some are not audited yet, or others are meant for development use and would be unsafe when run in contract context. The Starknet contract target runs now a pass after compilation that checks if every emitted libfunc is present in a provided allowed libfuncs list. By default, this pass emits compilation warnings when it spots unexpected libfuncs.

$ scarb build
   Compiling starknet_hello_world v0.1.0 [..]
warn: libfunc `bool_eq` is not allowed in the libfuncs list `Default libfunc list`
 --> contract: Balance
help: try compiling with the `experimental_v0.1.0` list
 --> Scarb.toml
    [[target.starknet-contract]]
    allowed-libfuncs-list.name = "experimental_v0.1.0"

    Finished release target(s) in 8 seconds

For more information, check out relevant documentation.

Cairo version

This version of Scarb comes with Cairo v1.1.0 with patches kept on this branch, commit 0e81e72.

What's Changed

• Truncate when overwriting artifacts by @tarrencev in #388
• Scarb Test Runner 🚀 by @mkaput in #382
• Bump fs4 from 0.6.4 to 0.6.5 by @dependabot in #396
• Bump proc-macro2 from 1.0.58 to 1.0.59 by @dependabot in #392
• Bump once_cell from 1.17.1 to 1.17.2 by @dependabot in #393
• Bump tokio from 1.28.1 to 1.28.2 by @dependabot in #395
• Bump quote from 1.0.27 to 1.0.28 by @dependabot in #394
• Replace deprecated Rust's SipHasher with XXH3 by @mkaput in #397
• Replace manual Default impls with derive for UI enums by @mkaput in #399
• Rename starknet_artifacts.json to <package>.starknet_artifacts.json to avoid collisions in workspaces by @mkaput in #398
• Add logging initialization in cairo-ls binary by @maciektr in #400
• Add a short notice about Scarb's LS to docs by @mkaput in #404
• Add missing diagnostics reporting to the test runner by @mkaput in #405
• Validate libfuncs in contracts compiler by @mkaput in #402

Full Changelog: v0.3.0...v0.4.0

0.3.0

Scarb 0.3.0

Welcome to the release notes for Scarb v0.3.0!

The starknet package

BREAKING CHANGE: This package is now a mandatory dependency for contract packages in order to successfully build.

The new starknet package, is meant to become the core package, but for Starknet development. Currently, it is limited to encapsulating the Starknet compiler plugins, but in the future we plan to move the starknet module from core to this new package. starknet is currently magically implemented in Scarb itself, but we plan eventually to publish it as a regular package, when all the work on compiler plugins will settle down.

Scarb does not load the Starknet plugin by default now. This change means, that in order to make a contract package the whole snipped to include in Scarb.toml looks like this now:

[dependencies]
starknet = ">=1.0.0"
 
[[target.starknet-contract]]

Scarb will produce warnings if you compile a Starknet contract, but forgot to declare dependency on starknet. Note that this is a soft warning: Scarb will proceed with compilation, and it will highly probably abort with compilation errors.

For more information about this package, check out its dedicated documentation page.

scarb-metadata updates

We have released a sizeable update to the scarb-metadata package: 1.4.2. It includes several new fields that Scarb 0.3 is now populating, removes deprecated ones, plus includes a new PackagesFilter struct for shared implementation of the frequently needed --package argument for use by extensions.

For all changes, we recommend checking out comparison between scarb-metadata 1.3.0 and 1.4.2 on diff.rs.

Examples

We pushed some minimal examples of Scarb projects to our repository. We hope this will bring a new dimension to Scarb's documentation and will be a great help for newcomers. In the future, new examples will definitely appear, and we are happy to get any ideas what could we include (or: PRs are welcome!).

Minor changes

• We updated MRSV for all crates to 1.69.
• Scarb now generates minified JSON files for Starknet contracts files.
• The Starknet compiler now outputs a starknet_artifacts.json file which contains a summary describing all generated files, which primary includes a mapping from (package, contract name) to generated class files.

Cairo version

This version of Scarb comes with Cairo v1.1.0.

What's Changed

• Create ManifestBuilder and move checks inside by @mkaput in #360
• Change occurences of quaireaux to alexandria by @mkaput in #365
• Create Scarb vs Cargo page in docs by @mkaput in #334
• Documentation updates for starknet package by @mkaput in #368
• Make scarb clean not error if target directory is not present by @mkaput in #371
• Remove unnecessary metadata from scarb-cairo-language-server Cargo.… by @mkaput in #375
• Fix list-binaries.sh to list exts in separate lines by @mkaput in #377
• Update Cairo to 1.1.0 by @mkaput in #381
• New scarb-metadata features by @mkaput in #379

Full Changelog: v0.2.1...v0.3.0

0.2.1

Scarb 0.2.1

Welcome to the release notes for Scarb v0.2.1!
This is a quick release that fixes the scarb-metadata crate version used by the Language Server. We are sorry for any inconveniences.

Cairo version

This version of Scarb comes with Cairo v1.0.0.

What's Changed

• Port sub_dependencies test from hex_solver by @mkaput in #338
• Minor imports reformat by @mkaput in #339
• Reorder code by @mkaput in #340
• Fix scarb metadata version by @maciektr in #347
• Document cairo-version field in manifest reference by @mkaput in #336
• Parse [cairo-plugin] in Scarb.toml by @mkaput in #355

Full Changelog: v0.2.0...v0.2.1

0.2.0

Scarb 0.2.0

Welcome to the release notes for Scarb v0.2.0! This release brings several improvements coming from the recent iteration:

• Cairo 1.0.0
• macOS and Linux installer
• cairo-version field in Scarb.toml
• Globs in scripts

Cairo 1.0.0

In preparation for the upcoming upgrades of Starknet, Cairo 1.0.0 has been released. This version of Scarb includes it now.

New installation flow for macOS and Linux

We have released the new install script-based method of installing Scarb on Unix-like platforms: macOS and Linux. Here's what you see on Scarb's website, when running these systems:

The download page also lists all downloadable files for current stable and preview releases. In the future, we also aim to publish these release notes directly on Scarb's website. What the installer does, its internals and our future plans have been outlined in detail in this Twitter thread.

cairo-version field in Scarb.toml

The cairo-version field is an optional key that tells Scarb what version of the Cairo compiler your package can be compiled with. If the currently selected version of the Cairo compiler is older than the stated version, Scarb will exit with an error. This field is analogous to Rust's rust-version.

[package]
name = "example"
version = "1.0.0"
cairo-version = "1.0.0"

Updated deno_task_shell to 0.12.0

Upgraded deno_task_shell brings support for globs in Scarb scripts! This means you can now write in your Scarb.toml:

[scripts]
example = "cp test/* other"

scarb-metadata deprecated code removal

The CompilationUnitMetadata.components_legacy field has been removed in scarb-metadata v1.3.0 as significant time has passed since deprecation. In future Scarb release, we will proceed with renaming the current components field underlying field components_data back to components.

Experimental: Linux MUSL builds

This release brings builds for two new platforms: x86_64-unknown-linux-musl and aarch64-unknown-linux-musl. These binaries have statically linked-in MUSL instead of Glibc, which theoretically makes them runnable on any Linux distributions running a reasonably modern kernel, such as Alpine or Nix OS. These builds are experimental and Scarb team is not serving support for them though, as we are unsure how MUSL will play with our plan for supporting compiler plugins as packages.

Cairo version

This version of Scarb comes with Cairo v1.0.0.

What's Changed

• Compilation Model docs by @maciektr in #303
• Bump clap from 4.2.5 to 4.2.7 by @dependabot in #306
• Bump serde from 1.0.160 to 1.0.162 by @dependabot in #308
• Bump fs4 from 0.6.3 to 0.6.4 by @dependabot in #309
• Bump libc from 0.2.142 to 0.2.143 by @dependabot in #307
• Bump serde_test from 1.0.160 to 1.0.162 by @dependabot in #311
• Create Unix installer by @mkaput in #312
• Make install.sh not crash if $SHELL is not present by @mkaput in #316
• New download flow on the website by @mkaput in #315
• Make install.sh follow XDG_DATA_HOME by @mkaput in #317
• Update architecture docs by @maciektr in #305
• Bump tokio from 1.28.0 to 1.28.1 by @dependabot in #320
• Bump serde from 1.0.162 to 1.0.163 by @dependabot in #321
• Fix copy button for Unix install command on the frontpage by @mkaput in #319
• Bump serde_test from 1.0.162 to 1.0.163 by @dependabot in #323
• Bump libc from 0.2.143 to 0.2.144 by @dependabot in #322
• Update Cairo to 1.0.0 and deno_task_shell to 0.12.0 by @mkaput in #327
• Use Bash instead of Python in scripts tests by @mkaput in #328
• Fix download tables scrolling by @mkaput in #331
• Docs: Use Scarb installer in CI workflows example by @maciektr in #329
• Publish MUSL builds by @mkaput in #332
• Add cairo-version to Scarb.toml and comparing it with current cairo version by @4rgorok in #290
• Remove deprecated CompilationUnitMetadata.components_legacy by @mkaput in #333
• Bump zip from 0.6.4 to 0.6.6 by @dependabot in #335

Full Changelog: v0.2.0-alpha.2...v0.2.0

0.2.0-alpha.2

Scarb 0.2.0-alpha.2

This is a quick release that now really includes the Scarb's bundled CairoLS binary. We are sorry for any inconveniences.

What's Changed

• Clarify information about package names in docs by @mkaput in #296
• Update: CLI command in working-on-an-existing-package.mdx by @0xKubitus in #301
• Add scarb ci examples for circleci and gitlabci by @maciektr in #300
• Remove invalid sentence that package names cannot start with _ by @mkaput in #302

New Contributors

• @0xKubitus made their first contribution in #301

Full Changelog: v0.2.0-alpha.1...v0.2.0-alpha.2

0.2.0-alpha.1

Scarb 0.2.0-alpha.1

Note: This version is not yet supported on Starknet! Scarb v0.2 will target Starknet v0.12. If you want to develop contracts deployable to current Starknet v0.11, please stick with Scarb v0.1.

---

Welcome to the release notes for Scarb v0.2! Here's what has changed these two weeks:

• Cairo 1.0.0-rc0 - we have updated Cairo to the latest release
• Cairo LS now comes bundled with Scarb - editor plugins now get access to the always-working revision of the LSP
• Conditional compilation - #[cfg(target: 'starknet-contract')]
• Work towards compiler plugins
  • Breaking change: the Compiler interface has been redone

Cairo LS now comes bundled with Scarb

The cairo-lang-language-server crate from Starkware implements a language server (refered to as Cairo LS) used by the Cairo extension for Visual Studio Code.

Since this release, the Cairo LS comes bundled into Scarb as a subcommand under cairo-language-server name (see Subcommands for more information). The Cairo extension is now capable of detecting and using the bundled Cairo LS binary. This allows Scarb to ensure both the extension and itself work with the same version of Cairo language, providing more consistent developer experience to extension users. There is no longer need to install the language server separately from Scarb.

Conditional compilation

Conditionally compiled source code is source code that may or may not be considered a part of the source code depending on certain conditions. Source code can be conditionally compiled using the cfg attribute.

The cfg attribute conditionally includes the thing it is attached to based on a configuration predicate. If the predicate is true, the item is rewritten to not have the cfg attribute on it. Otherwise, the item is removed from the source code.

For example, this attribute can be used to provide different implementations of a function depending on current Scarb target:

#[cfg(target: 'lib')]
fn example() -> felt252 {
    42
}

#[cfg(target: 'starknet-contract')]
fn example() -> felt252 {
    512
}

Which configuration options are set is determined statically during the compilation of the compilation unit of the compiled package. It is not possible to set a configuration option from within the source code of the package being compiled.

See Conditional Compilation reference page for more information.

Work towards compiler plugins

As part of our roadmap, we plan to support user defined Cairo compiler plugins, ideally distributed outside of Scarb source code and required as package dependencies. While this feature is not fully implemented yet, this release includes some ground work required to make this goal achievable in the future.

Cairo plugin is a special Scarb package that defines a cairo-plugin target and provides additional interface for instantiating compiler Semantic plugins. When using Scarb as a library, Cairo plugins can now be defined with configuration builder. If not specified otherwise, Scarb comes with predefined StarkNet Cairo plugin. The mechanism for requiring Cairo plugins as package dependencies or compiling them in Scarb runtime is not implemented yet.

See RFC: Scarb compiler plugins for more information.

Minor changes

1. We have added a documentation page about using Scarb in CI workflows. It starts with a template usage for GitHub Actions, GitLab CI and CircleCI.
2. scarb --version will now explicitly tell you if you're running a published Cairo version pulled from crates.io.

Cairo version

This version of Scarb comes with Cairo v1.0.0-rc0.

What's Changed

• Update various sub-dependencies by @mkaput in #256
• Change references to quirenox in our website to quaireaux_math by @4rgorok in #257
• Fix invalid regex for package names in docs by @mkaput in #259
• Bump snapbox from 0.4.10 to 0.4.11 by @dependabot in #262
• Bump clap from 4.2.1 to 4.2.2 by @dependabot in #263
• Bump assert_fs from 1.0.12 to 1.0.13 by @dependabot in #264
• Bump predicates from 3.0.2 to 3.0.3 by @dependabot in #261
• Conditional compilation by @mkaput in #266
• Docs: Add section about ignoring files in fmt by @maciektr in #267
• Fix recent CI issues by @mkaput in #275
• Add link to Cairo compiler crate if commit hash is unknown by @mkaput in #276
• Search directory containing Scarb binary for subcommands by @maciektr in #277
• Add github actions example to docs by @maciektr in #279
• Bump dunce from 1.0.3 to 1.0.4 by @dependabot in #281
• Bump libc from 0.2.141 to 0.2.142 by @dependabot in #282
• Bump tracing-subscriber from 0.3.16 to 0.3.17 by @dependabot in #283
• Bump clap from 4.2.2 to 4.2.4 by @dependabot in #284
• Add cairo-language-server binary by @maciektr in #260
• List subcommands from Scarb exe dir by @maciektr in #289
• Bump clap from 4.2.4 to 4.2.5 by @dependabot in #291
• Bump anyhow from 1.0.70 to 1.0.71 by @dependabot in #293
• Bump directories from 5.0.0 to 5.0.1 by @dependabot in #294
• Bump tokio from 1.27.0 to 1.28.0 by @dependabot in #292
• Prepare for compiler plugins packages by @mkaput in #297
• Update Cairo to 1.0.0-rc0 by @mkaput in #298

New Contributors

• @4rgorok made their first contribution in #257

Full Changelog: v0.2.0-alpha.0...v0.2.0-alpha.1

0.2.0-alpha.0

Scarb 0.2.0-alpha.0

Note: This version is not yet supported on Starknet! Scarb v0.2 will target Starknet v0.12. If you want to develop contracts deployable to current Starknet v0.11, please stick with Scarb v0.1.

Note: Compilation outputs will now land in target/dev/ directory by default. This is a result of introducing profiles to Scarb, and our decision to set dev as the default one instead of release.

---

Welcome to the release notes for Scarb v0.2.0-alpha.0! This is the first preview release in Scarb v0.2 release cycle. The main focus was to quickly deliver Cairo Alpha 7 to our users, but it already includes several features that we work on for the next version of Scarb:

• Profiles - Profiles provide a way to alter the compiler settings.
• CASM contract classes - Everything is awesome.
• Starknet compiler plugin enabled for [lib] target

Profiles

Profiles provide a way to alter the compiler settings, influencing things like optimizations and debugging information. When running Scarb commands, like scarb build, you can specify a profile to use with the --profile (-P) flag. Scarb has now 2 built-in profiles: dev and release. The profile defaults to dev if a profile is not specified on the command-line. In addition to the built-in profiles, custom user-defined profiles can also be specified.

For example, to replace all names in generated Sierra code with dummy counterparts, but only in dev profile, you can now write in your Scarb.toml:

[profile.dev.cairo]
sierra-replace-ids = true

See Defining Custom Profiles guide and Profiles reference page for more information.

CASM contract classes

Historically, contract classes have been defined in terms of Cairo assembly, or CASM for short (the class definition also included more information needed for execution, e.g., hint data). The novelty of Cairo 1.0 is the introduction of Sierra, an intermediate layer between Cairo 1.0 and CASM.

If there is a need to compile Sierra contract to CASM locally, Scarb can now do that by adding casm = true under [[targets.starknet-contract]]. Scarb will emit then the CASM Contract Class file in the target directory to a file named: [package name]_[contract name].casm.json.

See the expanded Starknet Contract Target reference page for more information.

Starknet compiler plugin enabled for [lib] target

As a temporary measure, Scarb v0.2 now explicitly enables the StarknetPlugin and Starknet specific implicits precedence for the generic [lib] target. This enables mixing lib and starknet-contract targets in a single package, which in Scarb v0.1 would almost always cause compilation errors, due to pure Cairo compiler not being able to expand the Starknet-specific #[contract] attribute.

In simpler words: it is now feasible to develop contract libraries!

Cairo version

This version of Scarb comes with Cairo v1.0.0-alpha.7.

Pull requests

• Enable StarknetPlugin on lib targets by @mkaput in #232
• Generate CasmContractClass in starknet-contract target by @mkaput in #235
• State how targets influence dependencies in docs by @mkaput in #243
• Add manifest profiles definition by @maciektr in #211
• Docs for manifest profiles by @maciektr in #246
• Allow tool metadata overriding with profiles by @maciektr in #253

Full Changelog: v0.1.0...v0.2.0-alpha.0

0.1.0

Scarb 0.1.0 goes Mainnet!

Welcome to the release notes for Scarb v0.1.0! To commemorate that, Cairo 1.0 is reaching Starknet Mainnet tomorrow, on Wednesday 26th March, we are happy to finally drop the prerelease tag from Scarb 🚀 In comparison with Scarb 0.1.0-rc.2, this release brings one new feature:

• Scripts - Packages can now define custom, cross-platform commands aiding in development.

Scripts

This feature should feel familiar to anyone who ever worked in JavaScript ecosystem. Since the popular Cairo 1.0 project template uses make for defining custom tasks, many projects started doing so. By introducing scripts, we hope to remove one extra dependency users need to have installed on their machines in order to work on Cairo 1.0 projects, and thus, make progress towards our goal of making Scarb the only software you have to install on your machine in order to write Cairo!

To get started, define your scripts in your codebase's Scarb.toml file under a [scripts] section:

[scripts]
foo = "echo 'Hello, world!'"

You can now run the foo script using the new scarb run command:

scarb run foo

Under the hood, we use deno_task_shell, which solves a big pain point of NPM scripts: Scarb scripts are cross-platform, and the same commands will run on Linux, macOS and Windows (no need for rimraf, rm just works).

See the guide and reference pages in Scarb documentation for more information.

What's next?

We are already working on Scarb 0.2. The main highlights of this release will be profiles (aka debug, release and custom ones) and first steps towards enabling packages to declare dependencies on Cairo compiler plugins. All of these are steps towards making Scarb integrate well with Protostar and other ecosystem tools.

As always, we keep our roadmap public here. Recently, it has undergone quite a sizeable refinement, and we hope you will like what we are cooking for Scarb!

Cairo version

This version of Scarb comes with Cairo v0.1.0-alpha.6.

Pull requests

• Update gix by @mkaput in #199
• Update directories by @mkaput in #200
• Update assert_fs and predicates by @mkaput in #197
• Migrate from Smol to Tokio by @maciektr in #176
• Minor docs improvements by @mkaput in #202
• Use SmolStr for tools manifest by @maciektr in #203
• Add scripts runner by @maciektr in #164
• Scarb branding by @mkaput in #204
• Write MAINTAINING.md by @mkaput in #210
• Add scripts docs by @maciektr in #209
• Bump toml_edit from 0.19.7 to 0.19.8 by @dependabot in #216
• Bump predicates from 3.0.1 to 3.0.2 by @dependabot in #217
• Bump async-trait from 0.1.67 to 0.1.68 by @dependabot in #218
• Prepare release 0.1.0 by @mkaput in #220

Full Changelog: v0.1.0-rc.2...v0.1.0