diff --git a/www/docs/bakery/advanced/_category_.json b/www/docs/bakery/advanced/_category_.json index 642efa5..7378d24 100644 --- a/www/docs/bakery/advanced/_category_.json +++ b/www/docs/bakery/advanced/_category_.json @@ -1,6 +1,6 @@ { "label": "Advanced Topics", - "position": 100, + "position": 10, "link": { "type": "doc", "id": "index" diff --git a/www/docs/bakery/advanced/caching.md b/www/docs/bakery/advanced/caching.md index aba788a..094f45e 100644 --- a/www/docs/bakery/advanced/caching.md +++ b/www/docs/bakery/advanced/caching.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 1 --- # Caching diff --git a/www/docs/bakery/advanced/index.md b/www/docs/bakery/advanced/index.md index feca3c3..5ea52e4 100644 --- a/www/docs/bakery/advanced/index.md +++ b/www/docs/bakery/advanced/index.md @@ -1 +1,3 @@ -# Advanced Topics \ No newline at end of file +# Advanced Topics + +This part of the documentation covers more advanced topics related to Rugix Bakery. \ No newline at end of file diff --git a/www/docs/bakery/images.md b/www/docs/bakery/images.md index f7bcbd0..f8a38d0 100644 --- a/www/docs/bakery/images.md +++ b/www/docs/bakery/images.md @@ -4,61 +4,37 @@ sidebar_position: 5 # Images -The configuration file `rugpi-bakery.toml` contains a declaration for each image that can be built. - -An *image declaration* has the following structure: - -```typescript -type Image = { - layer: string; - architecture: "amd64" | "arm64" | "armv7" | "armhf" | "arm"; - target: "generic-grub-efi" | "rpi-tryboot" | "rpi-uboot"; - size?: string; - layout?: ImageLayout; -} -``` - -Each image configuration has a mandatory `layer` property specifying the name of the layer containing the filesystems for the image, in particular, the root filesystem. -For further details on layers, checkout the [user guide's section on System Customization](./system-customization.md). -In addition, the configuration must specify an architecture and a target and may specify a size and an image layout. +As part of the project configuration you can define _system images_. A system image is a binary blob containing a partition table together with the required partitions and filesystems to boot a fully-functioning system. Images are typically used to provision new systems by flashing them onto a system's storage, e.g., integrated eMMC flash memory or an SSD. -## Architectures +Images are defined in the `images` section of the project configuration. Here is an example taken from the [Debian template](https://github.com/silitics/rugpi/tree/main/bakery/templates/debian-grub-efi): -Rugpi supports the following CPU architectures. - -| Architecture | Description | Alpine | Debian | Raspberry Pi OS | -| ------------ | ----------- | ------ | ------ | --------------- | -| `amd64` | 64-bit x86 | `x86_64` | `amd64` | – | -| `arm64` | 64-bit ARMv8 | `aarch64` | `arm64` | `arm64` | -| `armv7` | 32-bit ARMv7 | `armv7` | `armhf` | – | -| `armhf` | 32-bit ARMv6 (Hard-Float) | `armhf` | – | `armhf` | -| `arm` | 32Tbit ARMv6 | – | `armel` | – | +```toml +[images.customized-arm64] +layer = "customized" +architecture = "arm64" +target = "generic-grub-efi" +``` -Note that different distributions have different and sometimes inconsistent names for different CPU families. -For instance, what Debian calls `armhf` is called `armv7` for Alpine Linux and not the same as `armhf` for Raspberry Pi OS. +This will instruct Rugix Bakery to build an image named `customized-arm64` based on the `customized` layer for `arm64` and using `generic-grub-efi` as a _device target_ (the image will work on any EFI-compatible hardware). -When building images the architecture reported by `uname -m` may not match the actual CPU and architecture of the device the image is intended for. -For instance, when building an `armhf` image based on Rasbperry Pi OS, the architecture reported by `uname -m` during the build process is `armv7l`, however, when running the image later on a non-ARMv7 board (e.g., Pi Zero or Pi 1), then the architecture will be `armv6l`. -We recommend always using the Rugpi architecture instead of `uname -m`. +Every image is based on a layer providing, among other things, the root filesystem for the image. In addition, an [architecture](./#architectures) must be specified. The `target` setting is optional and used to select some defaults for supported devices. ## Targets -When building a system image with Rugpi, you need to specify a *target* that is appropriate for your device. -Targets typically support a whole family of devices and are categorized into *generic*, *specific*, and *unknown* targets. +When building a system image with Rugix Bakery, you can specify a *target* that is appropriate for your device. Targets typically support a whole family of devices and are categorized into *generic*, *specific*, and *unknown* targets. - **Generic targets** are based on some standardized booting mechanism, such as [UEFI](https://en.wikipedia.org/wiki/UEFI) or [EBBR](https://github.com/ARM-software/ebbr). Generic targets are suitable for any device that supports the respective booting mechanism. - **Specific targets**, on the other hand, are limited to a certain family of devices. They come with all necessary device-specific configurations resulting in a bootable image that works out-of-the-box. -- **Unknown targets** are for devices that do not conform to a standardized booting mechanism and are not specifically supported by Rugpi. -Using unknown targets allows building images for unsupported devices; however, these images usually require additional device-specific modifications to become bootable. +- **Unknown targets** are for devices that do not conform to a standardized booting mechanism and are not specifically supported by Rugix Bakery. Using unknown targets allows building images for unsupported devices; however, these images may require additional device-specific modifications to become bootable. The target for an image is set by the `target` property in the image declaration. For supported devices and the required targets, checkout the documentation on [Supported Devices](/devices). -Currently, Rugpi supports the following targets: +Currently, Rugix Bakery supports the following targets: - `generic-grub-efi`: A generic target that uses Grub as the bootloader and produces an image bootable on any EFI-compatible system. This is the right target for commodity AMD64 and ARM64 hardware or VMs. @@ -77,28 +53,25 @@ To this end, the following recipes can be used: - `core/rpi-alpine-setup`: For Alpine with `rpi-tryboot`. - `core/rpi-raspios-setup`: For Raspberry Pi OS with `rpi-tryboot` or `rpi-uboot`. -## Image Layout (Experimental) - -You can also specify an image layout. +## Layouts (Experimental) :::warning - -**This is an experimental feature. We may make breaking changes in minor versions.** - +**This is an experimental feature. We may introduce breaking changes in minor versions.** ::: -Usually, you do not need to worry about image layouts as Rugpi automatically selects a suitable layout based on the target. -For advanced use cases or to adapt Rugpi to a device that is not officially supported, Rugpi also gives you the flexibility to configure how exactly the image should be built. -Currently, this is limited to creating partitions with an optional filesystem based on some root directory. +Usually, you do not need to worry about image layouts as Rugix Bakery automatically selects a suitable layout based on the device target. +For advanced use cases or devices that are not officially supported, Rugix Bakery also gives you the flexibility to configure how exactly the image should be built. +Currently, this is limited to creating partitions with optional filesystems. #### Image Creation Process The process of creating an image roughly works as follows: -1. Compute a partition table based on the specified image layout. -2. Create an image and partition it according to the computed table. -3. Patch the boot configuration based on the target. -4. Create the filesystems based on the specified root directories. +1. Create the required filesystems from the layer. +2. Compute a partition table based on the specified image layout and filesystems. +3. Create an image and partition it according to the computed table. +4. Copy the prepared filesystems into the image. +5. Patch the boot configuration based on the target. Supported partition tables: - `gpt`: [GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table) (modern partition table, part of the UEFI standard) @@ -108,18 +81,4 @@ Supported filesystems: - `ext4`: [Ext4 Filesystem](https://en.wikipedia.org/wiki/Ext4) - `fat32`: [FAT32 Filesystem](https://en.wikipedia.org/wiki/File_Allocation_Table) -The image layout is specified within the `layout` section of the image configuration has the following structure: - -```typescript -type Layout = { - type: "gpt" | "mbr"; - partitions: Partition[]; -} - -type Partition = { - type?: string; - size?: string; - filesystem?: "ext4" | "fat32"; - root?: string; -} -``` \ No newline at end of file +The image layout is specified in the `layout` section. For details, we refer to the [project configuration reference](./projects.mdx#project-configuration). \ No newline at end of file diff --git a/www/docs/bakery/index.md b/www/docs/bakery/index.md index 45bce25..ca944c6 100644 --- a/www/docs/bakery/index.md +++ b/www/docs/bakery/index.md @@ -36,6 +36,22 @@ Rugix Bakery currently requires the container to run in privileged mode such tha [^privileges]: Existing tools use different approaches to set up an environment that looks like the final system without requiring privileges. For instance, Yocto uses a tool called [Pseudo](https://git.yoctoproject.org/pseudo/about/) (an alternative to the better-known tool [Fakeroot](https://manpages.debian.org/bookworm/pseudo/fakeroot.1.en.html)), to intercepts calls to system APIs via `LD_PRELOAD` and thereby fake a root environment. This approach has limitations, for instance, it does not work with statically-linked binaries and also does not allow starting services binding sockets to ports below 1024. Rugix Bakery strives to provide a container-like environment by using Linux namespaces and process isolation which does not suffer from the same limitations as existing approaches and thereby mimics a real system more closely. +## Architectures + +Rugix Bakery supports the following CPU architectures:[^architecture-plans] + +[^architecture-plans]: We plan to support more architectures in the future. Feel free to [open an issue on GitHub](https://github.com/silitics/rugpi/issues/new). + +| Architecture | Description | Alpine | Debian | Raspberry Pi OS | +| ------------ | ----------- | ------ | ------ | --------------- | +| `amd64` | 64-bit x86 | `x86_64` | `amd64` | – | +| `arm64` | 64-bit ARMv8 | `aarch64` | `arm64` | `arm64` | +| `armv7` | 32-bit ARMv7 | `armv7` | `armhf` | – | +| `armhf` | 32-bit ARMv6 (Hard-Float) | `armhf` | – | `armhf` | +| `arm` | 32Tbit ARMv6 | – | `armel` | – | + +Note that different distributions have different and sometimes inconsistent names for different CPU families. +For instance, what Debian calls `armhf` is called `armv7` for Alpine Linux and not the same as `armhf` for Raspberry Pi OS. ## Build Process: High-Level Introduction diff --git a/www/docs/bakery/recipes.mdx b/www/docs/bakery/recipes.mdx index 1bde9b9..b013746 100644 --- a/www/docs/bakery/recipes.mdx +++ b/www/docs/bakery/recipes.mdx @@ -109,6 +109,10 @@ Rugix Bakery will set up a semi-isolated environment (similar to a container) th You can use `install` steps to customize a system in the same way you normally would when you set up a system and perform customizations manually via a local shell. For instance, you can install packages or enable certain system services. Note that services will not run when executing a `run` step, you can, however, [start them as part of the step](./advanced/services.md). ::: +Note that the architecture reported by `uname -m` during an `install` step may not match the actual CPU and architecture of the device the system is intended for. +For instance, when building an `armhf` system based on Rasbperry Pi OS, the architecture reported by `uname -m` during the build process is `armv7l`, however, when running the system later on a non-ARMv7 board (e.g., Pi Zero or Pi 1), then the architecture will be `armv6l`. +We recommend always using the Rugix architecture instead of `uname -m`. + ### Environment Variables Rugix Bakery will expose the following environment variables when running steps: