archadeptcli

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:

Operating System	Version	x86_64	arm64
Mac	macOS Sonoma 14.1	TODO	🟢
Windows 10	Windows 10 Enterprise 22H2	🟢	N/A
Windows 11	TODO	TODO	TODO
Linux	Ubuntu 22.04 LTS	🟢	TODO

Click to expand for your operating system:

macOS instructions

1. Install Docker Desktop by following the instructions at: https://www.docker.com/products/docker-desktop/

2. Install Homebrew by following the instructions at: https://brew.sh

3. Install Python 3.8 or newer via Homebrew:

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

1. Install pipx via Homebrew:

$ brew install pipx

1. Let pipx correctly update your $PATH:

$ pipx ensurepath

1. From a new terminal window, install the ArchAdept CLI via pipx:

# From a new terminal window!
$ pipx install archadeptcli

1. Ensure the ArchAdept CLI is installed and accessible:

$ archadept --help

1. To update the ArchAdept CLI in future:

$ pipx upgrade archadeptcli

[!TIP] Run archadept pull now to download the backend Docker image ahead of time; this may take a few minutes to complete.

Proceed to usage.

Windows instructions

1. Install Docker Desktop by following the instructions at: https://www.docker.com/products/docker-desktop/

2. Install Python 3.8 or newer from https://www.python.org/downloads/windows/

[!WARNING] We strongly recommend not using the Microsoft Store to install Python 3; please download and install from the official Python website.

Furthermore, during installation, please ensure you tick the checkbox to add Python to your $PATH.

1. Install pipx via pip:

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

1. Let pipx correctly update your $PATH:

PS> py -3 -m pipx ensurepath

1. From a new terminal window, install the ArchAdept CLI via pipx:

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

1. Ensure the ArchAdept CLI is installed and accessible:

PS> archadept --help

1. To update the ArchAdept CLI in future:

PS> py -3 -m pipx upgrade archadeptcli

[!TIP] Run archadept pull now to download the backend Docker image ahead of time; this may take a few minutes to complete.

Proceed to usage.

Linux instructions

1. Install Docker Desktop by following the instructions at: https://www.docker.com/products/docker-desktop/

2. Use your distribution's package manager to check the installed version of Python 3, for example on Ubuntu using apt:

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

1. If necessary, use your distribution's package manager to upgrade to Python 3.8 or newer, for example on Ubuntu using apt:

$ sudo apt upgrade python3

1. Install pipx via pip:

$ python3 -m pip install --user pipx

1. Let pipx correctly update your $PATH:

$ python3 -m pipx ensurepath

1. From a new terminal window, install the ArchAdept CLI via pipx:

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

1. Ensure the ArchAdept CLI is installed and accessible:

$ archadept --help

1. To update the ArchAdept CLI in future:

$ python3 -m pipx upgrade archadeptcli

[!TIP] Run archadept pull now to download the backend Docker image ahead of time; this may take a few minutes to complete.

Proceed to usage.

Usage

The following commands are available:

Command	Description
make	Invoke an ArchAdept project Makefile.
run	Run an ArchAdept project on a QEMU simulation of real hardware.
debug	Attach debugger to an ArchAdept project running on a live QEMU simulation.
pull	Pull the latest backend Docker image.
prune	Cleanup any lingering Docker containers.

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