Skip to content

cli.md

Latest commit

 

History

History
55 lines (40 loc) · 2.59 KB

cli.md

File metadata and controls

55 lines (40 loc) · 2.59 KB
Raw

CLI — qltool and qltui

Goal

Give users a no-code way to run emulations: qltool run executes a binary against a rootfs, qltool code runs shellcode (hex/asm/bin), qltool examples prints usage samples, and qltool qltui launches an interactive TUI that gathers the same options. Mature released infrastructure; maturity-based status.

Status

done — covered by tests/test_qltool.py, which shells out to qltool for run/code subcommands and coverage output. InstalledQltool_Test checks the installed command, shellcode exit status, bundled profiles, and TUI import outside the checkout.

Code Structure

File Role
qltool Checkout launcher for qiling.cli.run
qiling/cli.py Argparse CLI; installed as qltool, builds kwargs and drives Qiling
qltui.py questionary/pyfx/termcolor TUI; collects options, returned to qltool

Key Types and Entry Points

  • qiling/cli.py:189 - run() - argparse setup with subcommands run, code, examples, qltui; enum-mapping actions translate --arch/--os/--endian/--verbose strings to QL_ARCH/QL_OS enums (qiling/cli.py:59-75).
  • qiling/cli.py:129 - handle_run(options) - builds {'argv': [file]+args, 'rootfs': ...}.
  • qiling/cli.py:78 - handle_code(options) - reads hex/asm/bin shellcode, assembling asm via qiling.arch.utils.assembler (qiling/cli.py:104).
  • qiling/cli.py:276 - ql = Qiling(**ql_args) - the single construction point; then optional Qdb (:279), gdbserver (:285), coverage-wrapped ql.run() (:306-310), JSON report (:312), exit with ql.os.exit_code (:321).

Interactions

  • Thin client of core.md: constructs Qiling and calls run().
  • Attaches debugger.md via --gdb host:port / --qdb [--rr].
  • Uses extensions.md for --coverage-file (drcov) and --json report output.
  • qltool examples mirrors scripts documented in examples/README.md.

How to Test

python3 -m pip install .
cd tests && python3 test_qltool.py   # pass = unittest "OK", exit 0
  • Packaging regression checks, from the repository root after installing the built wheel: python3 -I tests/test_qltool.py InstalledQltool_Test -v.
  • Manual smoke test: ./qltool run -f examples/rootfs/x8664_linux/bin/x8664_hello --rootfs examples/rootfs/x8664_linux — pass = prints Hello, World!.

Open Gaps / Roadmap

  • qltui.py has an installed import smoke test; its interactive flows are not covered by automated tests.
  • qltool predates subcommand-style config files; complex setups (fs mappers, custom hooks) still require the Python API.