1  # Ambient - a CI engine
  2  
  3  See <https://ambient.liw.fi/> for more information.
  4  
  5  ## Feedback and contributions
  6  
  7  The Radicle repository (`rad:zwPaQSTBX8hktn22F6tHAZSFH2Fh`) is my
  8  preferred way to get feedback in the form of issue tickets or patches.
  9  However, the codeberg.org repository
 10  (<https://codeberg.org/ambient/ambient-ci>) is also OK. Or mention me
 11  on the fediverse (`@liw@toot.liw.fi`) or send me email.
 12  
 13  
 14  ## Build and run tests
 15  
 16  To build the code and to run the test suite:
 17  
 18  ~~~
 19  make
 20  ~~~
 21  
 22  The `Makefile` targets `build` and `test` can be used to do only part
 23  of that.
 24  
 25  
 26  ## Dependencies
 27  
 28  You'll need, at least, with package names as they're in Debian:
 29  
 30  * [Subplot](https://subplot.tech/) (not packaged in Debian)
 31  * `python`
 32  * `python3-yaml`
 33  * `qemu-utils` (specifically `qemu-img`)
 34  * `ovmf` (UEFI implementation for virtual machines)
 35  * `qemu-system-x86` (specifically `kvm`)
 36  * `rsync`
 37  
 38  
 39  ## On logging
 40  
 41  Logging is communication and has audiences. Communication needs to be suitable
 42  for what it tries to convey and what each audience needs. For Ambient, the
 43  audiences are, roughly:
 44  
 45  * the software developer whose project is being built and tested in CI
 46    - they mostly want to know if something failed under CI that was caused by their code
 47    - for example, if their code has a syntax error or a test failed
 48  * the sysadmin who runs Ambient
 49    - they mostly want to know if Ambient is misbehaving, such as a disk being
 50      full
 51  * the Ambient developers
 52    - they mostly want to know Ambient works as intended, e.g., in Ambient's own test suite
 53  
 54  These are served by different kinds of logging.
 55  
 56  * the developer needs the run log, with everything that Ambient did during the
 57    CI run for their project, and what the result was, with enough detail that
 58    they can usually figure out what the problem is, if an action fails
 59    - they also don't want to be overwhelmed by a lot of uninteresting detail
 60  * the sysadmin can also be served by the run log, although they may care about
 61    other parts and details than the developer
 62  * the Ambient developer needs some kind of log that the test suite can analyze
 63  
 64  Status quo for logging:
 65  
 66  * Ambient itself (`ambient`) produces a JSON Lines format run log (`run.log`
 67    in the project state directory). In the VM, the `ambient-execute-plan` does
 68    as well, but that output can be surrounded by non-JSON junk produced by,
 69    for example, the VM BIOS at boot. When the VM is shut down, `ambient` parses
 70    the output from the VM (captured via a serial port), and extracts the JSON
 71    parts, and outputs those to its own JSON log.
 72  
 73  * The JSON Lines log is postprocessed (`ambient log --html`) into an HTML
 74    page. This is what developers and sysadmins are meant to actually read. The
 75    HTML log will probably need to be customized for some audiences, but having
 76    the JSON Lines format available makes that tolerably easy.
 77  
 78  * The output captured from the VM serial port is stored in raw format
 79    (`raw.log` in the project state directory). This may be helpful in special
 80    cases.
 81  
 82  These should cover everything except the needs of the test suite.
 83  
 84  The test suite primarily needs to know what actions are run, including in pre-
 85  and post-plan. In principle that is captured in the JSON Lines log. There's
 86  also a need to see that `--dry-run` works. That doesn't end up in a run log:
 87  the log isn't created for a dry run. For that specific case, `ambient` will
 88  output a line to stderr.
 89  
 90  
 91  ## Legalese
 92  
 93  (See [`COPYING.md`](COPYING.md) for a copy of the license.)
 94  
 95  Any changes made in September, 2025, or later, by Lars Wirzenius, are
 96  copyright Better Internet Foundation.
 97  
 98  Copyright 2023  Lars Wirzenius, Better Internet Foundation, and others
 99  
100  This program is free software: you can redistribute it and/or modify
101  it under the terms of the GNU General Public License as published by
102  the Free Software Foundation, either version 3 of the License, or
103  (at your option) any later version.
104  
105  This program is distributed in the hope that it will be useful,
106  but WITHOUT ANY WARRANTY; without even the implied warranty of
107  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
108  GNU General Public License for more details.
109  
110  You should have received a copy of the GNU General Public License
111  along with this program.  If not, see <https://www.gnu.org/licenses/>.