diff --git a/README.md b/README.md
index 1f5037c..0c88b6c 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,17 @@
# Malcolm-Test
-## Package source layout (under `src/malcolm_test`)
+[![Latest Version](https://img.shields.io/pypi/v/malcolm-test)](https://pypi.python.org/pypi/malcolm-test/)
+
+**Malcolm-Test** serves to run an instance of [Malcolm](https://idaholab.github.io/Malcolm/) and verifying the results of system tests executed against it. It consists mostly of a [control script](#MalcolmVMInitScript), TOML files containing provisioning steps for virtual machine creation, and the test files themselves. See [this issue](https://github.com/idaholab/Malcolm/issues/11) in the Malcolm repository for the discussion leading up to its creation.
+
+This project makes use of:
+
+* [Virter](https://github.com/LINBIT/virter) for the creation and execution of libvirt-based virtual machines running Malcolm
+* [pytest](https://docs.pytest.org/en/stable/) for the testing framework
+
+## Package source highlights (under `src/malcolm_test`)
* 🐍 [`malcolm_test.py`](#MalcolmVMInitScript) - A Python script for running Malcolm in a VM with virter (see below)
-* 🐍 `__init__.py` - Python package definition file
* 🗁 `virter/` - A directory structure containing TOML files for [provisioning](https://github.com/LINBIT/virter/blob/master/doc/provisioning.md) the virter VMs in which Malcolm will run. Its subdirectories are arranged thusly:
- 🗁 `debian-12/` - A directory matching the name of the virter image (supplied to [`malcolm_test.py`](#MalcolmVMInitScript) with the `-i`/`--image` argument)
+ 🗁 `init/` - TOML files for the initial steps of provisioning the OS (before setting up and starting Malcolm)
@@ -12,16 +20,36 @@
- 🗁 `malcolm-fini/` - Distribution-agnostic provisioning TOML files for tearing down Malcolm after tests are complete
* 🗁 `tests/` - A directory structure containing the test definitions, built using the [pytest](https://docs.pytest.org/en/stable/) framework
-## malcolm_test.py
+## Installation
+
+Using `pip`, to install the latest [release from PyPI](https://pypi.org/project/malcolm-test/):
+
+```
+python3 -m pip install -U malcolm-test
+```
+
+Or to install directly from GitHub:
+
+
+```
+python3 -m pip install -U 'git+https://github.com/idaholab/Malcolm-Test'
+```
+
+## The `malcolm-test` script
-`malcolm_test.py` is a Python script for Linux that uses [virter](https://github.com/LINBIT/virter) (a command line tool for simple creation and cloning of virtual machines) to run an instance of [Malcolm](https://github.com/idaholab/malcolm/) against which automated system tests can be run.
+`malcolm_test.py` is a Python script for Linux that uses [virter](https://github.com/LINBIT/virter) (a command line tool for simple creation and cloning of virtual machines) to run an instance of [Malcolm](https://idaholab.github.io/Malcolm/) against which automated system tests can be run.
+
+When [installed](#Installation) via pip, this script may be executed as `malcolm-test` from the Linux command line.
### Usage
```
usage: malcolm_test.py
+See README.md for usage details.
+
options:
+ -h, --help show this help message and exit
--verbose, -v Increase verbosity (e.g., -v, -vv, etc.)
-r [true|false], --rm [true|false]
Remove virtual Malcolm instance after execution is complete
@@ -49,8 +77,13 @@ Virtual machine specifications:
Name of an existing virter VM to use rather than starting up a new one
--vm-provision [true|false]
Perform VM provisioning
+ --vm-provision-malcolm [true|false]
+ Perform VM provisioning (Malcolm-specific)
--vm-provision-path
- Path containing subdirectories with TOML files for VM provisioning (e.g., /home/user/Malcolm-Test/virter)
+ Path containing subdirectories with TOML files for VM provisioning (e.g., /home/tlacuache/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/malcolm_test/virter)
+ --build-vm The name for a new VM image to build and commit instead of running one
+ --build-vm-keep-layers [true|false]
+ Don't remove intermediate layers when building a new VM image
Malcolm runtime configuration:
--container-image-file
@@ -68,7 +101,7 @@ Malcolm runtime configuration:
2024-10-25 12:42:51 INFO: /home/user/Malcolm-Test/malcolm_test.py
2024-10-25 12:42:51 INFO: Arguments: ['-vv', '--rm', '--github-url', 'https://github.com/idaholab/Malcolm', '--github-branch', 'main']
2024-10-25 12:42:51 INFO: Arguments: Namespace(verbose=20, removeAfterExec=True, repoUrl='https://github.com/idaholab/Malcolm', repoBranch='main', vmCpuCount=8, vmMemoryGigabytes=31, vmDiskGigabytes=64, vmImage='debian-12', vmImageUsername='debian', vmNamePrefix='malcolm', vmExistingName='', vmProvision=True, vmProvisionPath='/home/user/Malcolm-Test/virter', containerImageFile='', startMalcolm=True, postInitSleep=30)
-2024-10-25 12:42:51 INFO: ['virter', 'vm', 'run', 'debian-12', '--id', '126', '--name', 'malcolm-126', '--vcpus', '8', '--memory', '31GB', '--bootcapacity', '64GB', '--user', 'debian', '--wait-ssh']
+2024-10-25 12:42:51 INFO: ['virter', 'vm', 'run', 'debian-12', '--id', '0', '--name', 'malcolm-126', '--vcpus', '8', '--memory', '31GB', '--bootcapacity', '64GB', '--user', 'debian', '--wait-ssh']
2024-10-25 12:43:04 INFO: malcolm-126
2024-10-25 12:43:04 INFO: ['virter', 'vm', 'exec', 'malcolm-126', '--provision', '/home/user/Malcolm-Test/virter/debian-12/init/00-apt-init.toml', '--set', 'env.VERBOSE=false', '--set', 'env.REPO_URL=https://github.com/idaholab/Malcolm', '--set', 'env.REPO_BRANCH=main']
2024-10-25 12:44:27 INFO: malcolm-126 out: Linux malcolm-126 6.1.0-26-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.112-1 (2024-09-30) x86_64