xqcli 0.3.2

Unified CLI for the XQuad Toolchain
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

# xqcli

Unified CLI for the [XQuad Toolchain](https://gitlab.com/quip.network/xquad).

This crate is named `xqcli`; it builds the `xquad` binary. That is:
`cargo install xqcli` installs a command called `xquad`, not `xqcli`.
Running `xqcli --help` after installing will fail because no such binary
exists.

## Install

```sh
cargo install xqcli
xquad --help
```

## Subcommands

`xquad` has four subcommands, one per stage of the toolchain: `asm`,
`dism`, `run`, `verify`.

| Subcommand | Does |
|---|---|
| `xquad asm <INPUT>` | Assemble `.xqasm` source into `.xqb` bytecode |
| `xquad dism [FILE]` | Disassemble bytecode into a human-readable listing |
| `xquad run <FILE>` | Run bytecode (or assembly, with `--text`) on the interpreter |
| `xquad verify <FILE>` | Run the bytecode verifier (all phases) |

Run `xquad <subcommand> --help` for the full option list; the summaries
below are the parts most people need first.

- `xquad asm`: `-o, --output <OUTPUT>` (defaults to `<input>.xqb`), `--stdout` to write bytecode to stdout instead of a file.
- `xquad dism`: reads from stdin when `FILE` is omitted.
- `xquad run`: `--text` to treat `FILE` as assembly, `--calldata <CALLDATA>` (comma-separated integers), `--outputs <OUTPUTS>` (default 16), `--step-limit <STEP_LIMIT>` (default 10000000, 0 = unlimited), `--trace` with `--trace-format text|json` and `--trace-file <FILE>`.
- `xquad verify`: `--text` to treat `FILE` as assembly before verifying.

## Quick start

```sh
cat > add.xqasm <<'EOF'
; add.xqasm -- push two integers and add them
PUSH 10
PUSH 32
ADD
HALT
EOF

xquad asm add.xqasm -o add.xqb
xquad run add.xqb
xquad dism add.xqb
xquad verify add.xqb
```

`xquad run add.xqb` prints the residual stack:

```
stack (bottom to top):
  42
```

## Links out

- [`xqvm`](https://gitlab.com/quip.network/xquad/-/tree/main/xqvm) -- bytecode types and interpreter this CLI drives
- [`xqasm`](https://gitlab.com/quip.network/xquad/-/tree/main/xqasm) -- text assembler behind `xquad asm`
- [Normative VM spec](https://gitlab.com/quip.network/xquad/-/blob/main/spec/xqvm/SPEC.md)
- [Bytecode encoding spec](https://gitlab.com/quip.network/xquad/-/blob/main/spec/xqvm/ENCODING.md)
- [Repository](https://gitlab.com/quip.network/xquad)

## License

AGPL-3.0-or-later.