# Butter Churn

[![License](https://img.shields.io/badge/License-BSD_3--Clause-orange.svg)](https://opensource.org/licenses/BSD-3-Clause)

Tool for building Butter Box disk images.

## Host prerequisites

The build host needs `vmdb2` and, for the amd64 image, the `syslinux-common`
package — the amd64 recipe writes GPT protective-MBR boot code
(`/usr/lib/syslinux/mbr/gptmbr.bin`) directly to the output image from the host
filesystem, so this package must be present on the build machine (not just
inside the target image):

```sh
sudo apt install syslinux-common
```

## Usage

To build a butter image, run:

```sh
vmdb2 --rootfs-tarball=my_image.tar.gz --output my_image.img --log my_image.log
```

## Advanced Documentation

* [Creating an upgrade content pack for the Butter Box](./docs/upgrade_pack.md)
* [Set up DeltaChat messaging between multiple boxes](./docs/multibox.md)
* [Extending Butter Box connectivity with WiFi HaLow and LoRa](./docs/wireless_connectivity.md)

## Copyright and Licence

&copy; 2017, Michael Stapelberg and contributors<br>
&copy; 2021, guardianproject<br>
&copy; 2025-2026, SR2 Communications Limited

See [LICENCE](./LICENCE) for details of the BSD-3 clause licence.

This project is a derivative work of:

* [Butter Box for Raspberry Pi](https://gitlab.com/likebutter/butterbox-rpi)
  licensed under the MIT licence.
* [Raspberry Pi Image Specs](https://salsa.debian.org/raspi-team/image-specs)
  licensed under the 3-clause BSD licence.