# ambient-build-vm - build an image for Ambient

`ambient-build-vm` creates a virtual machine image for use with
Ambient, the CI system.

## Example

A software developer would use this program to create an image for a
build virtual machine like this:

```sh
$ ./ambient-build-vm --image=my.qcow2
```

This will take several minutes to run, but will produce the file
`my.qcow2`, which can be used with `ambient-run` as a base image.

## Discussion

See <https://ambient.liw.fi/> for more information about Ambient.

## Stakeholders

* Ambient developers

(More to be added)

## Requirements

* MUST build a Debian VM with desired software installed.
* MUST run the `run-ci` script provided in a tar archive on
  `/dev/vdb`.

## Architecture

`ambient-build-vm` runs [vmdb2](https://vmdb2.liw.fi/) to build a
Debian image. Support for other operating systems will be added later.

The built image itself is set up to run the `ambient-boot` script at
boot up, and then power off. The boot script output is redirected to
`/dev/ttyS1`, so that it can be captured. The script unpacks a tar
archive from `/dev/vdb` into a temporary directory, and runs
`./run-ci` in that directory. The `run-ci` executable does whatever is
needed to be done to run CI on a project.

## Building

`ambient-build-vm` is a self-contained Python script that can be run
from the source tree. It doesn't need to be built.

## Testing

To also test the built image, to ensure it works as expected for
Ambient CI, the `build-and-test.sh` script can be used:

~~~sh
$ ./build-and-test my.qcow2 /tmp
~~~

This builds the image, by running `ambient-build-vm`, and then runs it
under QEMU to make sure it works. The running should add about 10 or
20 seconds to the run time. You need `kvm` installed and configured.

## Deployment

There is Debian packaging. You can build the `.deb` package and
install that.

## Contributing

See <https://codeberg.org/ambient/ambient-build-vm> for the public git
repository. Patches and issues are welcome.

## Legalese

Copyright 2023 Lars Wirzenius.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.