|
| 1 | +<script setup> |
| 2 | +import { data as rel } from "../../github.data"; |
| 3 | +</script> |
| 4 | + |
| 5 | +# Scarb execute |
| 6 | + |
| 7 | +The `scarb execute` command executes a function from a local package. |
| 8 | +It does automatically compile the Cairo code within the package so using `scarb build` beforehand is not necessary. |
| 9 | +If `scarb build` or `scarb execute` has been previously used and the package hasn't changed since, |
| 10 | +this automatic build can be optionally skipped with the `--no-build` flag. |
| 11 | +Only packages defining the [executable target](../reference/targets#executable-target) can be executed. |
| 12 | + |
| 13 | +## Choosing a function to run |
| 14 | + |
| 15 | +If your package defines multiple main functions (see [choosing the main function](../reference/targets#choosing-the-main-function)), |
| 16 | +you need to specify which executable target should be run. |
| 17 | + |
| 18 | +This can be achieved through one of two flags: |
| 19 | + |
| 20 | +- `--executable-name` to choose the target by its name. |
| 21 | +- `--executable-function` to choose the target by the main function it defines. |
| 22 | + |
| 23 | +Those flags are mutually exclusive. |
| 24 | + |
| 25 | +## Saving the execution information |
| 26 | + |
| 27 | +The execution will be carried out for one of two execution targets: `standalone` or `bootloader`. |
| 28 | +You can choose the target with the `--target` flag: |
| 29 | + |
| 30 | +- **Standalone**: executes program as-is, execution is intended to be directly proven with `scarb prove`. |
| 31 | +- **Bootloader**: program’s execution is expected to be wrapped by |
| 32 | + the [bootloader’s](https://github.com/Moonsong-Labs/cairo-bootloader?tab=readme-ov-file#cairo-bootloader) execution, |
| 33 | + which itself will be proven via Stwo. |
| 34 | + |
| 35 | +See more on [proving and verifying execution](./prove-and-verify.md) page. |
| 36 | + |
| 37 | +## Resource usage and program output |
| 38 | + |
| 39 | +To print the Cairo program output, you can use the `--print-program-output` flag. |
| 40 | +Otherwise, the output will be discarded. |
| 41 | + |
| 42 | +To print detailed execution resources usage, you can use the `--print-resource-usage` flag. |
| 43 | +This will show information about: |
| 44 | + |
| 45 | +- `n_steps` |
| 46 | +- `n_memory_holes` |
| 47 | +- `builtin_instance_counter` |
| 48 | +- `syscalls` |
| 49 | + |
| 50 | +In case your Cairo program panics, the panic reason will be shown on the output, and the program will exit with a |
| 51 | +non-zero exit code. |
| 52 | + |
| 53 | +## Program arguments |
| 54 | + |
| 55 | +The executable function may accept arguments. |
| 56 | +They can be passed to the `scarb execute` command via either `--arguments` or `--arguments-file` flag. |
| 57 | + |
| 58 | +The expected input with `--arguments` is a comma-separated list of integers. |
| 59 | +This list should correspond to the Cairo’s Serde of main’s arguments, for example: |
| 60 | + |
| 61 | +| main’s signature | valid arguments example | valid arguments file contents example | |
| 62 | +| :------------------------------------- | :---------------------- | :------------------------------------ | |
| 63 | +| `fn main(num: u8)` | 1 | ["0x1"] | |
| 64 | +| `fn main(num1: u8, num2: u16)` | 1,27 | ["0x1", "0x1b"] | |
| 65 | +| `fn main(num1: u8, tuple: (u16, u16))` | 1,2,27 | ["0x1", "0x2", "0x1b"] | |
| 66 | +| `fn main(num1: u8, num2: u256)` | 1,2,27 | ["0x1", "0x2", "0x1b"] | |
| 67 | +| `fn main(num1: u8, arr: Array<u8>)` | 1,2,1,2 | ["0x1", "0x2", "0x1", "0x2"] | |
| 68 | + |
| 69 | +Note that when using `--arguments-file`, the expected input is an array of felts represented as hex string. |
| 70 | +See the [documentation](https://docs.starknet.io/architecture-and-concepts/smart-contracts/serialization-of-cairo-types/) for more information about Cairo’s Serde. |
0 commit comments