Package: archadeptcli
archadeptcli- ArchAdept Command Line InterfaceCommand line interface for building, running, debugging, and disassembling the
ArchAdept training course example projects.IntroductionMany 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.InstallationTested as working on:Operating SystemVersionx86_64arm64MacmacOS Sonoma 14.1TODO🟢Windows 10Windows 10 Enterprise 22H2🟢N/AWindows 11TODOTODOTODOLinuxUbuntu 22.04 LTS🟢TODOSkip to installation instructions for:macOSWindowsLinuxOr skip tousage.macOSInstall Docker Desktop by following the instructions at:https://www.docker.com/products/docker-desktop/Install Homebrew by following the instructions at:https://brew.shInstall Python 3.8 or newer via Homebrew:$brewsearchpython3$brewinstallpython@3.12# Chosen from results of `brew search python3`Installpipxvia Homebrew:$brewinstallpipxLet pipx correctly update your$PATH:$pipxensurepathFrom a new terminal window, install the ArchAdept CLI viapipx:#Fromanewterminalwindow!$pipxinstallarchadeptcliEnsure the ArchAdept CLI is installed and accessible:$archadept--helpTo update the ArchAdept CLI in future:$pipxupgradearchadeptcli[!TIP]
Runarchadept pullnow to download the backend Docker image ahead of time; this may take a few minutes to complete.Skip tousage.WindowsInstall Docker Desktop by following the instructions at:https://www.docker.com/products/docker-desktop/Install Python 3.8 or newer fromhttps://www.python.org/downloads/windows/[!WARNING]
We strongly recommendnotusing 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.Installpipxviapip:PS> py -3 -m pip install --user pipxLetpipxcorrectly update your$PATH:PS> py -3 -m pipx ensurepathFrom a new terminal window, install the ArchAdept CLI viapipx:#Fromanewterminalwindow!PS> py -3 -m pipx install archadeptcliEnsure the ArchAdept CLI is installed and accessible:PS> archadept --helpTo update the ArchAdept CLI in future:PS> py -3 -m pipx upgrade archadeptcli[!TIP]
Runarchadept pullnow to download the backend Docker image ahead of time; this may take a few minutes to complete.Skip tousage.LinuxInstall Docker Desktop by following the instructions at:https://www.docker.com/products/docker-desktop/Use your distribution's package manager to check the installed version of
Python 3, for example on Ubuntu usingapt:$aptshowpython3|grepVersionVersion: 3.10.6-1~22.04If necessary, use your distribution's package manager to upgrade to Python 3.8
or newer, for example on Ubuntu usingapt:$sudoaptupgradepython3Installpipxviapip:$python3-mpipinstall--userpipxLetpipxcorrectly update your$PATH:$python3-mpipxensurepathFrom a new terminal window, install the ArchAdept CLI viapipx:#Fromanewterminalwindow!$python3-mpipxinstallarchadeptcliEnsure the ArchAdept CLI is installed and accessible:$archadept--helpTo update the ArchAdept CLI in future:$python3-mpipxupgradearchadeptcli[!TIP]
Runarchadept pullnow to download the backend Docker image ahead of time; this may take a few minutes to complete.Skip tousage.UsageThe following commands are available:CommandDescriptionmakeInvoke an ArchAdept project Makefile.runRun an ArchAdept project on a QEMU simulation of real hardware.debugAttach debugger to an ArchAdept project running on a live QEMU simulation.pullPull the latest backend Docker image.pruneCleanup any lingering Docker containers.makeusage: 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 messagescommand-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 levelcommand-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:allbuilds the project.cleandeletes all of a project's build artifacts.rebuildperforms a clean build, equivalent tocleanfollowed byall.disrebuilds the project, then disassembles it.symsrebuilds the project, then dumps its symbol table.sectsrebuilds the project, then dumps its section headers.Note: Thedistarget accepts the following optional flags:-Senables interleaving source code with the disassembly.runusage: 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 messagescommand-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 entrypointTo quit the QEMU simulation, pressCtrl-afollowed byx.debugusage: archadept debug [-h] [-v] CONTAINERAttaches a GDB debug session to a live QEMU simulation started by `archadept run`.options:-h, --help  show this help message and exit-v          enable logging verbose debug messagescommand-specific positional arguments:CONTAINER   container in which the QEMU simulation is running, as given by `archadept run`pullusage: 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 messagescommand-specific options:-i IMAGE    override Docker image repository (default: archadept/archadeptcli-backend)-t TAG      override Docker image tag (default: latest)pruneusage: 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