1  # ambient-build-vm - build an image for Ambient
 2  
 3  `ambient-build-vm` creates a virtual machine image for use with
 4  Ambient, the CI system.
 5  
 6  ## Dependencies
 7  
 8  On Debian, install some packages before proceeding:
 9  
10  ```console
11  sudo apt install zerofree vmdb2
12  ```
13  
14  ## Example
15  
16  A software developer would use this program to create an image for a
17  build virtual machine like this:
18  
19  ```sh
20  $ ./ambient-build-vm --image=my.qcow2 --data .
21  ```
22  
23  This will take several minutes to run, but will produce the file
24  `my.qcow2`, which can be used with `ambient-run` as a base image.
25  
26  ## Discussion
27  
28  See <https://ambient.liw.fi/> for more information about Ambient.
29  
30  ## Stakeholders
31  
32  * Ambient developers
33  
34  (More to be added)
35  
36  ## Requirements
37  
38  * MUST build a Debian VM with desired software installed.
39  * MUST run the `run-ci` script provided in a tar archive on
40    `/dev/vdb`.
41  
42  ## Architecture
43  
44  `ambient-build-vm` runs [vmdb2](https://vmdb2.liw.fi/) to build a
45  Debian image. Support for other operating systems will be added later.
46  
47  The built image itself is set up to run the `ambient-boot` script at
48  boot up, and then power off. The boot script output is redirected to
49  `/dev/ttyS1`, so that it can be captured. The script unpacks a tar
50  archive from `/dev/vdb` into a temporary directory, and runs
51  `./run-ci` in that directory. The `run-ci` executable does whatever is
52  needed to be done to run CI on a project.
53  
54  ## Building
55  
56  `ambient-build-vm` is a self-contained Python script that can be run
57  from the source tree. It doesn't need to be built.
58  
59  ## Testing
60  
61  To also test the built image, to ensure it works as expected for
62  Ambient CI, the `build-and-test.sh` script can be used:
63  
64  ~~~sh
65  $ ./build-and-test my.qcow2 /tmp
66  ~~~
67  
68  This builds the image, by running `ambient-build-vm`, and then runs it
69  under QEMU to make sure it works. The running should add about 10 or
70  20 seconds to the run time. You need `kvm` installed and configured.
71  
72  ## Deployment
73  
74  There is Debian packaging. You can build the `.deb` package and
75  install that.
76  
77  ## Contributing
78  
79  See <https://codeberg.org/ambient/ambient-build-vm> for the public git
80  repository. Patches and issues are welcome.
81  
82  ## Legalese
83  
84  Copyright 2023 Lars Wirzenius.
85  
86  This program is free software: you can redistribute it and/or modify
87  it under the terms of the GNU Affero General Public License as
88  published by the Free Software Foundation, either version 3 of the
89  License, or (at your option) any later version.
90  
91  This program is distributed in the hope that it will be useful,
92  but WITHOUT ANY WARRANTY; without even the implied warranty of
93  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
94  GNU Affero General Public License for more details.
95  
96  You should have received a copy of the GNU Affero General Public License
97  along with this program.  If not, see <https://www.gnu.org/licenses/>.