|
| 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 |
0 commit comments