README.md.in

# The Cereus Linux live image/rootfs generator and installer

<a href="https://codeberg.org/cereus-linux/mklive">
    <img alt="Get it on Codeberg" src="https://get-it-on.codeberg.org/get-it-on-white-on-black.png" height="60">
</a>

This repository is based on [void-mklive](https://github.com/void-linux/void-mklive). 

Not all the utilities available here are actually used by us (hence, they aren't adapted for Cereus): *mkplatformfs.sh*, *mkimage.sh*, *mknet.sh*, and *release.sh*. The main reason is our distribution is currently only focused in desktop usage and that we aren't relying in CI at the moment. However, this might (or not) change in the future.

The source code is mainly hosted on [Codeberg](https://codeberg.org/cereus-linux/mklive) with a mirror available on [GitHub](https://github.com/CereusLinuxProject/cereus-mklive). **Issues and pull requests should be made in Codeberg**.

## Overview

This repository contains several utilities:

* [*mklive.sh*](#mklivesh) - The Cereus Linux live image generator for x86.
* [*build-x86-images.sh*](#build-x86-imagessh) - Wrapper script to generate bootable
  and installable live images for x86.
* [*mkrootfs.sh*](#mkrootfssh) - The Cereus Linux rootfs generator for all platforms.
* *installer.sh* - The Cereus Linux el-cheapo installer for x86.

The following utilities are inherited from *void-mklive* but are unused at the moment:

* [*mkplatformfs.sh*](#mkplatformfssh) - The Void Linux filesystem tool to produce
  a rootfs for a particular platform.
* [*mkimage.sh*](#mkimagesh) - The Void Linux image generator for ARM platforms.
* [*mknet.sh*](#mknetsh) - Script to generate netboot tarballs for Void.
* *release.sh* - interacts with GitHub CI to generate and sign images for releases.

### Workflow

#### Generating x86 live ISOs

To generate a live ISO like the officially-published ones, use
[*build-x86-images.sh*](#build-x86-imagessh). To generate a more basic live ISO
(which does not include things like `cereus-installer`), use [*mklive.sh*](#mklivesh).

#### Generating ROOTFS tarballs

ROOTFS tarballs contain a basic Cereus Linux root filesystem without a kernel.
These can be useful for doing a [chroot install](https://docs.voidlinux.org/installation/guides/chroot.html)
or for [chroots and containers](https://docs.voidlinux.org/config/containers-and-vms/chroot.html).

Use [*mkrootfs.sh*](#mkrootfssh) to generate a Cereus Linux ROOTFS.

## Dependencies

Note that *cereus-mklive* is not guaranteed to work on distributions other than Cereus/Void
Linux, or in containers.

* Compression type for the initramfs image (by default: liblz4 for lz4, xz)
* xbps>=0.45
* qemu-user-static binaries (for mkrootfs)
* bash

## Kernel Command-line Parameters

`cereus-mklive`-based live images support several kernel command-line arguments
that can change the behavior of the live system:

- `live.autologin` will skip the initial login screen on `tty1`.
- `live.user` will change the username of the non-root user from the default
  `cereus`. The password remains `cereus`.
- `live.shell` sets the default shell for the non-root user in the live environment.
- `live.accessibility` enables accessibility features like the console screenreader
  `espeakup` in the live environment.
- `console` can be set to `ttyS0`, `hvc0`, or `hvsi0` to enable `agetty` on that
  serial console.
- `locale.LANG` will set the `LANG` environment variable. Defaults to `en_US.UTF-8`.
- `vconsole.keymap` will set the console keymap. Defaults to `us`.

### Examples:

- `live.autologin live.user=foo live.shell=/bin/bash` would create the user `foo`
  with the default shell `/bin/bash` on boot, and log them in automatically on `tty1`
- `live.shell=/bin/bash` would set the default shell for the `anon` user to `/bin/bash`
- `console=ttyS0 vconsole.keymap=cf` would enable `ttyS0` and set the keymap in
  the console to `cf`
- `locale.LANG=fr_CA.UTF-8` would set the live system's language to `fr_CA.UTF-8`

## Usage