archadeptcli - ArchAdept Command Line Interface

Command line interface for building, running, debugging, and disassembling the ArchAdept training course example projects.

Introduction

Many of the lessons on our training courses involve practical coding exercises for you to complete, or example code snippets for you to modify and run yourself on simulated hardware.

One challenge often faced by newcomers to bare metal ARM architecture development like this is getting all of the necessary tools installed and configured, especially when accounting for all the differences between the Mac, Linux, and Windows operating systems.

The ArchAdept CLI solves this issue by leveraging Docker containers "under-the-hood" to provide a consistent environment that is preloaded and preconfigured with all of the tools required to build, run, debug, and disassemble the ArchAdept training course example projects, while abstracting away all of the complexities of managing the actual Docker containers themselves.

Installation

Tested as working on:

Click to expand for your operating system:

$ brew search python3
$ brew install python@3.12  # Chosen from results of `brew search python3`

$ brew install pipx

$ pipx ensurepath

# From a new terminal window!
$ pipx install archadeptcli

$ archadept --help

$ pipx upgrade archadeptcli

PS> py -3 -m pip install --user pipx

PS> py -3 -m pipx ensurepath

# From a new terminal window!
PS> py -3 -m pipx install archadeptcli

PS> archadept --help

PS> py -3 -m pipx upgrade archadeptcli

$ apt show python3 | grep Version
Version: 3.10.6-1~22.04

$ sudo apt upgrade python3

$ python3 -m pip install --user pipx

$ python3 -m pipx ensurepath

# From a new terminal window!
$ python3 -m pipx install archadeptcli

$ archadept --help

$ python3 -m pipx upgrade archadeptcli

Usage

The following commands are available:

make

usage: archadept make [-h] [-v] [-p PROJECT] [-i IMAGE] [-t TAG] [TARGET]

Invokes an ArchAdept example project Makefile.

options:
  -h, --help  show this help message and exit
  -v          enable logging verbose debug messages

command-specific options:
  -p PROJECT    path to the ArchAdept project (default: current directory)
  -i IMAGE      override Docker image repository (default: archadept/archadeptcli-backend)
  -t TAG        override Docker image tag (default: latest)
  -S            interleave source with disassembly (only available for 'dis' target)
  -O {0,1,2,3}  override project's default optimization level

command-specific positional arguments:
  TARGET      Makefile target from {all,clean,rebuild,dis,syms} (default: all)

The following targets are defined by all ArchAdept training course example project Makefiles:

• all builds the project.
• clean deletes all of a project's build artifacts.
• rebuild performs a clean build, equivalent to clean followed by all.
• dis rebuilds the project, then disassembles it.
• syms rebuilds the project, then dumps its symbol table.
• sects rebuilds the project, then dumps its section headers.

Note: The dis target accepts the following optional flags:

• -S enables interleaving source code with the disassembly.

run

usage: archadept run [-h] [-v] [-p PROJECT] [-i IMAGE] [-t TAG] [-s]

Runs an ArchAdept example project on a simulated Raspberry Pi 3b using QEMU.

options:
  -h, --help  show this help message and exit
  -v          enable logging verbose debug messages

command-specific options:
  -p PROJECT  path to the ArchAdept project (default: current directory)
  -i IMAGE    override Docker image repository (default: archadept/archadeptcli-backend)
  -t TAG      override Docker image tag (default: latest)
  -s          spawn GDB debug server and pause simulation at kernel entrypoint

To quit the QEMU simulation, press Ctrl-a followed by x.

debug

usage: archadept debug [-h] [-v] CONTAINER

Attaches an LLDB debug session to a live QEMU simulation started by `archadept run -s`.

options:
  -h, --help  show this help message and exit
  -v          enable logging verbose debug messages

command-specific positional arguments:
  CONTAINER   container in which the QEMU simulation is running, as given by `archadept run`

pull

usage: archadept pull [-h] [--version] [-v] [-i IMAGE] [-t TAG]

Pulls the latest ArchAdept CLI backend Docker image from DockerHub.

options:
  -h, --help  show this help message and exit
  --version   display archadeptcli version info
  -v          enable logging verbose debug messages

command-specific options:
  -i IMAGE    override Docker image repository (default: archadept/archadeptcli-backend)
  -t TAG      override Docker image tag (default: latest)

prune

usage: archadept prune [-h] [-v]

Cleans up any lingering Docker containers from previous ArchAdept CLI invocations.

options:
  -h, --help  show this help message and exit
  -v          enable logging verbose debug messages