# packer

The rustkrazy image generator.

# Supported hardware

The images created by this program should work on the following machines:

* Raspberry Pi 3 (any model)
* Raspberry Pi 4 (any model)
* x86_64 hardware supporting legacy boot

UEFI support (for x86_64) is not planned, but contributions are welcome.

# System package requirements

For the packer to work you need to install the following packages:

* nasm
* squashfs-tools-ng
* musl
* gcc
* ld
* (optional) clang
* (optional) kernel-headers-musl

If you want to build images for the Raspberry Pi, the aarch64 versions
of the musl related packages (musl itself and optionally clang and the kernel headers)
and the compiler and linker (gcc becomes aarch64-linux-musl, ld becomes aarch64-linux-gnu-binutils)
are required as well.

Clang and the kernel headers are needed for some small sys crates to compile.
Many crates will compile without them but there are a few that won't.

Then, add the musl targets:

```
rustup target add x86_64-unknown-linux-musl
rustup target add aarch64-unknown-linux-musl
```

# Supported crates

Most Rust crates should compile if the packer is set up correctly.
Larger sys crates that dynamically link to system libraries
cannot easily be supported. Most notably OpenSSL is not supported.
Check if your dependencies offer Cargo features to disable OpenSSL
and replace it with rustls.

In general simple crates are more likely to work
but more complex crates can be built if the correct dependencies are installed.

# Usage

Invoke the packer with `-h` or `--help` to view a list of all available options.

## --overwrite

The overwrite argument specifies where to write the image to.
It can be a device file (loop or real) as long as you have permission
to write to it.

To grant yourself write access to a device, use the following command (as root):

```
setfacl -m u:<USERNAME>:rw <DEVICE_FILE>
```

If the target file is a device this is sufficient. If it's an image file
you have to pass `-n` or `--size`. You can use a tool like `fdisk`
to get the size of your image file in bytes and use that number with the packer.
This is needed because the packer needs to know the size of the image
for partitioning but can't call ioctl on regular files to get it.

Alternatively you can create a loop device for your image
and write to it instead.

## --crates

This is a list of crate names to install from the crates.io registry.
To install more than one crate you can pass this argument multiple times.
Example:

```
rustkrazy_packer -o /dev/some_device -c crate1 -c crate2
```

The name is assumed to be the same as the name of the resulting binary.
As a result you may need to swap hyphens with underscores or vice versa.

## --git

This is similar to `--crates`, but allows you to install crates
from any git repository. Just like `--crates` it can be passed
multiple times. It expects the argument to be in the following format:

```
<REPO_URL>%<CRATE_NAME>
```

where `REPO_URL` is the location of the repository
and `CRATE_NAME` is the name of the crate defined in its Cargo.toml.

Like `--crates` this argument expects `CRATE_NAME` to match the binary file name.

Example:

```
rustkrazy_packer -o /dev/some_device -g https://github.com/rustkrazy/init%rustkrazy_init
```

## --init

Use this flag to tell the packer which one of the crates is the init system.
It will be moved to `/bin/init` in the image and start on boot.
It is responsible for starting the other binaries as needed.

The argument is the name of one of the crates listed in `--crates`
or `--git`.

The rustkrazy project comes with its own small init system
that oneshots all services and logs startup information
to the primary display. It also mounts essential file systems
like /boot or /proc.

You can however use your own init system if it's better for your use case.

If you're only installing a single crate an init may not be needed,
allowing you to set the init argument to that crate.
However this is not guruanteed to work since the program can fail
if it tries to access pseudo file systems that have not been mounted.

# Building the packer

Make sure you have `cargo-make` installed:

```
cargo install cargo-make
```

Since the packer requires the compiled MBR for the x86_64 architecture
it needs to be built by running:

```
cargo make
```

if you want to build x86_64 images.

This assembles the MBR and builds the packer.

You may skip this step if you're only interested in building images
for the Raspberry Pi.