Update scarb docs (#1630)

fixes  #1512

website/docs/guides/dependencies.md

@@ -6,56 +6,62 @@ 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.
 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,24 +71,30 @@ 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`
 
 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 [email protected]
 ```
 
 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 [email protected]
+```
+
+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
 ```

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/