From 78eaa282c995900afb2f4cc2c40e91e0f0f8de2b Mon Sep 17 00:00:00 2001 From: maciektr Date: Fri, 4 Oct 2024 10:39:14 -0700 Subject: [PATCH] Update scarb docs (#1630) fixes #1512 --- website/docs/guides/dependencies.md | 74 +++++++++++++++++------------ website/docs/troubleshooting.md | 16 +++++++ 2 files changed, 59 insertions(+), 31 deletions(-) diff --git a/website/docs/guides/dependencies.md b/website/docs/guides/dependencies.md index 6a0d07f7f..fd79208ab 100644 --- a/website/docs/guides/dependencies.md +++ b/website/docs/guides/dependencies.md @@ -6,37 +6,37 @@ To add a dependency, simply declare it in your `Scarb.toml`. > [!WARNING] > Using Git repositories as a foundation for package management is not the recommended approach anymore. > Instead, [registries](../registries/overview.md) are now the primary way to manage dependencies. -> This guide will be updated to reflect the new approach after official registry is out of beta and considered stable. -> For details on how to specify dependencies from the official registry, see [here](../reference/specifying-dependencies#specifying-dependencies-from-official-registry). +> For details on how to specify dependencies from the official registry, +> see [here](../reference/specifying-dependencies#specifying-dependencies-from-official-registry). +> If you want to rely on git dependencies instead of the recommended way, you can learn more +> [here](../reference/specifying-dependencies#specifying-dependencies-from-git-repositories). ## Adding a dependency -If your `Scarb.toml` doesn't already have a `[dependencies]` section, add it, then list the package name and the URL to -its Git repository. -This example adds a dependency on the [`alexandria`](https://github.com/keep-starknet-strange/alexandria) package (note -that Alexandria is a collection of multiple packages, and we will use `alexandria_math` as an example in this guide): +If your `Scarb.toml` doesn't already have a `[dependencies]` section, add it, then list the package name and the version +required. You can search for packages to use through the [scarbs.xyz registry website](https://scarbs.xyz/). +This example adds a dependency on the [`openzeppelin_merkle_tree`](https://github.com/OpenZeppelin/cairo-contracts) +package (note that OpenZeppelin is a collection of multiple packages, and we will use only one of them as an example in +this guide). To see all available versions of some package, you can see the versions pane on the package's +[registry page](https://scarbs.xyz/packages/openzeppelin_merkle_tree). At the time of writing this guide, the latest +version of the `openzeppelin_merkle_tree` package is `0.17.0`, which is the version we will use. ```toml [dependencies] -alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria.git" } +openzeppelin_merkle_tree = "0.17.0" ``` -You can pin a Git dependency to concrete commit, branch or a tag using one of the following extra fields that can be -passed along `git`: `branch`, `tag` and `rev`. +Using `"0.17.0"` as version requirement means, that you want to use a version `0.17.0` or newer, up until `0.18.0`. To +accept only a specific version, you can use `"=0.17.0"`. You can learn more about specifying version +requirements [here](../reference/specifying-dependencies#version-requirements) -Actually this is how the OpenZeppelin Contracts for Cairo library is released, since the `main` branch is not stable. +Note, that if you want to add more dependencies, you do not have to add `[dependencies]` for each package separately. +For example: ```toml [dependencies] -openzeppelin = { git = "https://github.com/OpenZeppelin/cairo-contracts.git", tag = "v0.7.0-rc.0" } -``` - -Note, that if you want to add more dependencies, you do not have to add `[dependencies]` for each package separately. For example: - -```toml -[dependencies] -alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria.git" } -openzeppelin = { git = "https://github.com/OpenZeppelin/cairo-contracts.git", tag = "v0.7.0-rc.0" } +openzeppelin_merkle_tree = "0.17.0" +openzeppelin_account = "0.17.0" ``` Now, run `scarb build`, and Scarb will fetch new dependencies and all of their dependencies. @@ -44,18 +44,24 @@ Then it will compile your package with all of these packages included: ```shell $ scarb build - Updating git repository https://github.com/keep-starknet-strange/alexandria - Updating git repository https://github.com/OpenZeppelin/cairo-contracts + Downloading openzeppelin_account v0.17.0 + Downloading openzeppelin_merkle_tree v0.17.0 + Downloading openzeppelin_utils v0.17.0 + Downloading openzeppelin_introspection v0.17.0 Compiling hello_world v0.1.0 (/path/to/package/hello_world/Scarb.toml) Finished `dev` profile target(s) in 4 seconds ``` -You can now use the `alexandria_math` package in `src/lib.cairo`: +Note that the dependencies of specified packages are also downloaded during the build process. + +You can now use the `openzeppelin_merkle_tree` package in `src/lib.cairo`: ```cairo -use alexandria_math::fibonacci; -fn main() -> felt252 { - fibonacci::fib(0, 1, 10) +use openzeppelin_merkle_tree::hashes::PedersenCHasher; +fn hash() { + let a = 'a'; + let b = 'b'; + let _hash = PedersenCHasher::commutative_hash(a, b); } ``` @@ -65,7 +71,7 @@ You can add a `[dev-dependencies]` section to your Scarb.toml whose format is eq ```toml [dev-dependencies] -alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria.git" } +openzeppelin_merkle_tree = "0.17.0" ``` ## Adding a dependency via `scarb add` @@ -73,16 +79,22 @@ alexandria_math = { git = "https://github.com/keep-starknet-strange/alexandria.g If you prefer, you can also ask Scarb to edit `Scarb.toml` to add a dependency automagically for you. The `scarb add` command accepts many parameters, matching all possibilities of expressing dependencies. It can also automatically keep the list sorted, if it already is. -For example, the above example of dependency on `alexandria_math`, can be also added like this: +For example, the above example of dependency on `openzeppelin_merkle_tree`, can be also added like this: ```shell -scarb add alexandria_math --git https://github.com/keep-starknet-strange/alexandria.git --rev 27fbf5b +scarb add openzeppelin_merkle_tree@0.17.0 ``` You can add development dependencies similarly by passing `--dev` flag: ```shell -scarb add --dev alexandria_math --git https://github.com/keep-starknet-strange/alexandria.git --rev 27fbf5b +scarb add --dev openzeppelin_merkle_tree@0.17.0 +``` + +You can also use it to add git commands if you wish: + +```shell +scarb add openzeppelin_merkle_tree --git https://github.com/OpenZeppelin/cairo-contracts.git --tag 0.17.0 ``` ## Removing a dependency @@ -92,11 +104,11 @@ To remove a dependency, simply remove related lines from your `Scarb.toml`. As a quick shortcut, the `scarb remove` (also available in short `scarb rm`) can clean the manifest automatically: ```shell -scarb rm alexandria_math +scarb rm openzeppelin_merkle_tree ``` Removing development dependencies, like in `scarb add`, requires passing `--dev` flag: ```shell -scarb rm --dev alexandria_math +scarb rm --dev openzeppelin_merkle_tree ``` diff --git a/website/docs/troubleshooting.md b/website/docs/troubleshooting.md index 1d7bddd05..1a6d1d15f 100644 --- a/website/docs/troubleshooting.md +++ b/website/docs/troubleshooting.md @@ -29,4 +29,20 @@ RUST_MIN_STACK=134217728 scarb build Please note that this is a workaround and not a permanent solution. If you encounter this issue, please report it to the compiler team at [Cairo issues]. +## Procedural macros undefined symbol + +When compiling a project that uses procedural macros, if you encounter an error message like this: + +``` +undefined symbol: __start_linkm2_MACRO_DEFINITIONS_SLICE +``` + +You can try following workarounds: + +1. Make sure that you have a stable Cargo release installed. You can check the installed version by + running `cargo --version`. +2. If the error still persists on stable Cargo release, please try running build with + either `RUSTFLAGS="-C link-dead-code"` or `RUSTFLAGS="-C link-args=-znostart-stop-gc"` flags. You can submit the + flags to the compiler by pasting them before the `scarb build` command in your terminal. + [Cairo issues]: https://github.com/starkware-libs/cairo/issues/