Skip to content

Commit b07bd03

Browse files
committed
Add some more nice guides
1 parent 00cbd14 commit b07bd03

File tree

4 files changed

+122
-1
lines changed

4 files changed

+122
-1
lines changed

website/pages/docs/guides/_meta.json

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
{
2-
"creating-a-new-package": ""
2+
"creating-a-new-package": "",
3+
"working-on-an-existing-package": "",
4+
"dependencies": "",
5+
"formatting": ""
36
}
+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import { Callout } from "nextra-theme-docs";
2+
3+
# Managing dependencies
4+
5+
Scarb manages dependencies by cloning packages from their Git repositories.
6+
To add a dependency, simply declare it in your `Scarb.toml`.
7+
8+
<Callout type="info">
9+
Using Git submodules as a foundation for package management is not an ideal
10+
approach. Therefore, we plan to create a proper package registry in long term.
11+
</Callout>
12+
13+
## Adding a dependency
14+
15+
If your `Scarb.toml` doesn't already have a `[dependencies]{:toml}` section, add it, then list the package name and the URL to its Git repository.
16+
This example adds a dependency on the [`quaireaux`](https://github.com/keep-starknet-strange/quaireaux) package:
17+
18+
```toml copy filename="Scarb.toml"
19+
[dependencies]
20+
quaireaux = { git = "https://github.com/keep-starknet-strange/quaireaux.git" }
21+
```
22+
23+
In fact, it is always good to pin Git dependencies to concrete commits, otherwise Scarb would try to update this dependency each time it is executed.
24+
You can achieve this using one of the following extra fields that you can pass along `git{:toml}`: `branch{:toml}`, `tag{:toml}` and `rev{:toml}`.
25+
For example, in this guide we will pin to a concrete commit hash:
26+
27+
```toml copy filename="Scarb.toml"
28+
[dependencies]
29+
quaireaux = { git = "https://github.com/keep-starknet-strange/quaireaux.git", rev = "041379c" }
30+
```
31+
32+
<Callout type="info">
33+
In the future this paragraph will be irrelevant, because Scarb will maintain a
34+
lockfile. We track this feature in this issue:
35+
[#126](https://github.com/software-mansion/scarb/issues/126).
36+
</Callout>
37+
38+
Note, that if you want to add more dependencies, you do not have to add `[dependencies]{:toml}` for each package separately.
39+
40+
Now, run `scarb build{:shell}`, and Scarb will fetch new dependencies and all of their dependencies.
41+
Then it will compile your package with all of these packages included:
42+
43+
```shell copy
44+
scarb build
45+
```
46+
47+
```text filename="Output"
48+
Updating git repository https://github.com/keep-starknet-strange/quaireaux
49+
Compiling hello_world v0.1.0 (/path/to/package/hello_world/Scarb.toml)
50+
Finished release target(s) in 4 seconds
51+
```
52+
53+
You can now use the `quaireaux` library in `lib.cairo`:
54+
55+
```cairo copy filename="src/lib.cairo"
56+
use quaireaux::math::fibonacci;
57+
fn hello_world() -> felt {
58+
fibonacci::fib(0, 1, 10)
59+
}
60+
```
61+
62+
## Adding a dependency via `scarb add`
63+
64+
If you prefer, you can also ask Scarb to edit `Scarb.toml` to add a dependency automagically for you.
65+
The `scarb add{:shell}` command accepts many parameters, matching all possibilities of expressing dependencies.
66+
It can also automatically keep the list sorted, if it already is.
67+
For example, the above example of dependency on `quaireaux`, can be also added like this:
68+
69+
```shell copy
70+
scarb add quaireaux --git https://github.com/keep-starknet-strange/quaireaux.git --rev 041379c
71+
```
72+
73+
## Removing a dependency
74+
75+
To remove a dependency, simply remove related lines from your `Scarb.toml`.
76+
77+
As a quick shortcut, the `scarb remove{:shell}` (also available in short `scarb rm{:shell}`) can clean the manifest automatically:
78+
79+
```shell copy
80+
scarb rm quaireaux
81+
```
+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Formatting
2+
3+
Scarb comes with a built-in Cairo source code formatter:
4+
5+
```shell copy
6+
scarb fmt
7+
```
8+
9+
If you use continuous integration workflows in your project, you can also add a step to ensure the Cairo code is properly formatted:
10+
11+
```shell copy
12+
scarb fmt --check
13+
```
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Working on an Existing Scarb Package
2+
3+
If you download an existing package that uses Scarb, it's really easy to get going.
4+
5+
First, get the package from somewhere. For example, the [`quaireaux`](https://github.com/keep-starknet-strange/quaireaux) package is hosted on GitHub, and we 'll clone its repository using Git.
6+
7+
```shell copy
8+
git clone https://github.com/keep-starknet-strange/quaireaux
9+
cd quaireaux
10+
cat Scarb.toml
11+
```
12+
13+
Then to build it, use `scarb build{:shell}`:
14+
15+
```shell copy
16+
scarb build
17+
```
18+
19+
```text filename="Output"
20+
Compiling quaireaux v0.1.0 (/path/to/package/quaireaux/Scarb.toml)
21+
Finished release target(s) in 4 seconds
22+
```
23+
24+
This will fetch all of the dependencies and then build them, along with the package.

0 commit comments

Comments
 (0)