Skip to content

Commit 2c4f615

Browse files
mkaputmkaput
committed
Write docs useful for extension authors
1 parent 89302c6 commit 2c4f615

File tree

5 files changed

+112
-4
lines changed

5 files changed

+112
-4
lines changed

‎website/pages/docs/extensions/json-output.mdx

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: JSON Output
3+
---
4+
5+
# JSON Output
6+
7+
When passing `--json` argument, Scarb will output all messages in newline-delimited JSON format.
8+
This is useful, when running Scarb from scripts or other programs.
9+
This format is guaranteed to be more stable than human-readable output.
10+
11+
Example output for compilation:
12+
13+
```json filename="scarb --json build"
14+
{"status":"compiling","message":"hello v0.1.0 ([..]Scarb.toml)"}
15+
{"type":"diagnostic","message":"error: Skipped tokens. Expected: Module/Use/FreeFunction/ExternFunction/ExternType/Trait/Impl/Struct/Enum or an attribute./n --> lib.cairo:1:1/nnot_a_keyword/n^***********^/n/n"}
16+
{"type":"error","message":"could not compile `hello` due to previous error"}
17+
```
18+
19+
Scarb outputs all JSON messages as fast as possible.
20+
It is fine to rely on message appearance times for computing timings of command execution.

‎website/pages/docs/extensions/scarb-metadata.mdx

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Scarb Metadata Command
2+
3+
You can use the `scarb metadata` command to get information about package structure and dependencies.
4+
The format is stable and versioned.
5+
When calling `scarb metadata`, you are required to pass `--format-version` flag explicitly.
6+
7+
See `scarb metadata --help` for more information about accepted arguments.

‎website/pages/docs/extensions/subcommands.mdx

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Custom Subcommands
2+
3+
Scarb is designed to be extensible with new subcommands without having to modify Scarb itself.
4+
This is achieved by translating a Scarb invocation of the form `scarb (?<command>[^ ]+)` into an invocation of an external tool `scarb-${command}`.
5+
The external tool must be present in (preferably) the `bin` directory in Scarb's [local data directory][dirs], or in any other of the user's `$PATH` directories.
6+
7+
When Scarb invokes a custom subcommand, the first argument to the subcommand will be the filename of the custom subcommand, as usual.
8+
The second argument will be the subcommand name itself.
9+
For example, the second argument would be `${command}` when invoking `scarb-${command}`.
10+
Any additional arguments on the command line after `${command}` will be forwarded unchanged.
11+
12+
## Environment variables
13+
14+
Additionally, Scarb passes more contextual information via environment variables:
15+
16+
| Environment variable | Description |
17+
| --------------------- | ------------------------------------------------------------------------------------------ |
18+
| `SCARB` | Path to Scarb executable. |
19+
| `PATH` | System `$PATH` but augmented with `bin` directory in Scarb's [local data directory][dirs]. |
20+
| `SCARB_CACHE` | Path to Scarb's [cache][dirs] directory. |
21+
| `SCARB_CONFIG` | Path to Scarb's [config][dirs] directory. |
22+
| `SCARB_TARGET_DIR` | Path to the current target directory. |
23+
| `SCARB_MANIFEST_PATH` | Absolute path to current `Scarb.toml`. |
24+
| `SCARB_UI_VERBOSITY` | Scarb's messages verbosity, possible values: `quiet`, `normal`, `verbose`. |
25+
| `SCARB_LOG` | Scarb's logger directives, follows [`tracing`'s `EnvFilter` syntax][tracing-env-filter]. |
26+
27+
## Implementation recommendations
28+
29+
Custom subcommands may use the `SCARB` environment variable to call back to Scarb.
30+
Alternatively, they can link to the [`scarb` crate](./scarb-crate) as a library, but this approach has drawbacks, described in the linked page.
31+
Instead, it is encouraged wo use the CLI interface to drive Scarb.
32+
The [`scarb metadata`](./scarb-metadata) command can be used to obtain information about the current project,
33+
whereas the [`--json`](./json-output) flag make Scarb output machine-readable messages on standard output.
34+
35+
[dirs]: ../reference/global-directories
36+
[tracing-env-filter]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html#directives

‎website/pages/docs/reference/global-directories.mdx

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Global Directories
2+
3+
Scarb uses several directories stored in operating system's conventional locations for different purposes, such as storing global configuration or download and source cache.
4+
This page list outlines all global directories, their default paths and information how to override them if possible.
5+
6+
## Cache directory
7+
8+
This is a location where Scarb will store a downloads, Git checkouts and package sources.
9+
10+
| Platform | Default Path |
11+
| -------- | ----------------------------------------------- |
12+
| Linux | `$XDG_CACHE_HOME/scarb` or `$HOME/.cache/scarb` |
13+
| macOS | `$HOME/Library/Caches/com.swmansion.Scarb` |
14+
| Windows | `%LocalAppData%\swmansion\Scarb\cache` |
15+
16+
This path can be overriden via `SCARB_CACHE` environment variable.
17+
18+
## Config directory
19+
20+
This is a location where Scarb will look for global configuration in the future.
21+
22+
| Platform | Default Path |
23+
| -------- | ------------------------------------------------------- |
24+
| Linux | `$XDG_CONFIG_HOME/scarb` or `$HOME/.config/scarb` |
25+
| macOS | `$HOME/Library/Application Support/com.swmansion/Scarb` |
26+
| Windows | `%LocalAppData%\swmansion\Scarb\config` |
27+
28+
This path can be overriden via `SCARB_CONFIG` environment variable.
29+
30+
## Local data directory
31+
32+
This is a location, where users can put some additional data files for use by Scarb.
33+
Scarb will look for [subcommands] in the `bin` subdirectory.
34+
35+
| Platform | Default Path |
36+
| -------- | ------------------------------------------------------- |
37+
| Linux | `$XDG_DATA_HOME/scarb` or `$HOME/.local/share/scarb` |
38+
| macOS | `$HOME/Library/Application Support/com.swmansion.Scarb` |
39+
| Windows | `%LocalAppData%\swmansion\Scarb\data` |
40+
41+
This path cannot be overriden.
42+
43+
[subcommands]: ../extensions/subcommands

‎website/pages/docs/reference/targets.mdx

+6-4
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,8 @@ Such targets are called _external_ and are defined in a `[[target.*]]{:toml}` ar
3636
This is not fully implemented, and we track this work in [#111](https://github.com/software-mansion/scarb/issues/111).
3737
As for now, Scarb only supports internally hardcoded targets:
3838

39-
- [`starknet-contract`](../starknet/contract-target)
39+
- [`starknet-contract`](../starknet/contract-target)
40+
4041
</Callout>
4142

4243
If multiple targets of the same kind are defined in the package, they all must specify unique [names](#name).
@@ -52,9 +53,10 @@ name = "foo" # The name of the target.
5253
```
5354

5455
<Callout type="warning">
55-
Scarb reserves itself a right to introduce new global configuration fields in future versions.
56-
Potentially, new parameters may end up being conflicting with ones accepted by external targets.
57-
Introducing new parameters will always be done in major Scarb version bump, and will be loudly communicated earlier.
56+
Scarb reserves itself a right to introduce new global configuration fields in
57+
future versions. Potentially, new parameters may end up being conflicting with
58+
ones accepted by external targets. Introducing new parameters will always be
59+
done in major Scarb version bump, and will be loudly communicated earlier.
5860
</Callout>
5961

6062
### `name`

0 commit comments

Comments
 (0)