xqcli

Unified CLI for the XQuad Toolchain.

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

cargo install xqcli
xquad --help

Subcommands

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

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

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 -- bytecode types and interpreter this CLI drives
• xqasm -- text assembler behind xquad asm
• Normative VM spec
• Bytecode encoding spec
• Repository

License

AGPL-3.0-or-later.