nixos/boot/external: init

This allows supporting external bootloader backends.
This commit is contained in:
Cole Helbling 2021-08-05 12:33:13 -07:00 committed by Cole Helbling
parent 942dcd238b
commit 83d06ce16d
5 changed files with 147 additions and 0 deletions

View File

@ -0,0 +1,41 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-bootloader-external">
<title>External Bootloader Backends</title>
<para>
NixOS has support for several bootloader backends by default:
systemd-boot, grub, uboot, etc. The built-in bootloader backend
support is generic and supports most use cases. Some users may
prefer to create advanced workflows around managing the bootloader
and bootable entries.
</para>
<para>
You can replace the built-in bootloader support with your own
tooling using the <quote>external</quote> bootloader option.
</para>
<para>
Imagine you have created a new packaged called FooBoot. FooBoot
provides a program at
<literal>${pkgs.fooboot}/bin/fooboot-install</literal> which takes
the system closures path as its only argument and configures the
systems bootloader.
</para>
<para>
You can enable FooBoot like this:
</para>
<programlisting language="bash">
{ pkgs, ... }: {
boot.loader.external = {
enable = true;
installHook = &quot;${pkgs.fooboot}/bin/fooboot-install&quot;;
};
}
</programlisting>
<section>
<title>Developing Custom Bootloader Backends</title>
<para>
Bootloaders should use
<link xlink:href="https://github.com/NixOS/rfcs/pull/125">RFC-0125</link>s
Bootspec format and synthesis tools to identify the key properties
for bootable system generations.
</para>
</section>
</section>

View File

@ -1256,6 +1256,7 @@
./system/boot/loader/grub/grub.nix
./system/boot/loader/grub/ipxe.nix
./system/boot/loader/grub/memtest.nix
./system/boot/loader/external/external.nix
./system/boot/loader/init-script/init-script.nix
./system/boot/loader/loader.nix
./system/boot/loader/raspberrypi/raspberrypi.nix

View File

@ -0,0 +1,26 @@
# External Bootloader Backends {#sec-bootloader-external}
NixOS has support for several bootloader backends by default: systemd-boot, grub, uboot, etc.
The built-in bootloader backend support is generic and supports most use cases.
Some users may prefer to create advanced workflows around managing the bootloader and bootable entries.
You can replace the built-in bootloader support with your own tooling using the "external" bootloader option.
Imagine you have created a new packaged called FooBoot.
FooBoot provides a program at `${pkgs.fooboot}/bin/fooboot-install` which takes the system closure's path as its only argument and configures the system's bootloader.
You can enable FooBoot like this:
```nix
{ pkgs, ... }: {
boot.loader.external = {
enable = true;
installHook = "${pkgs.fooboot}/bin/fooboot-install";
};
}
```
## Developing Custom Bootloader Backends
Bootloaders should use [RFC-0125](https://github.com/NixOS/rfcs/pull/125)'s Bootspec format and synthesis tools to identify the key properties for bootable system generations.

View File

@ -0,0 +1,38 @@
{ config, lib, pkgs, ... }:
with lib;
let
cfg = config.boot.loader.external;
in
{
meta = {
maintainers = with maintainers; [ cole-h grahamc ];
# Don't edit the docbook xml directly, edit the md and generate it:
# `pandoc external.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > external.xml`
doc = ./external.xml;
};
options.boot.loader.external = {
enable = mkEnableOption "use an external tool to install your bootloader";
installHook = mkOption {
type = with types; path;
description = ''
The full path to a program of your choosing which performs the bootloader installation process.
The program will be called with an argument pointing to the output of the system's toplevel.
'';
};
};
config = mkIf cfg.enable {
boot.loader = {
grub.enable = mkDefault false;
systemd-boot.enable = mkDefault false;
supportsInitrdSecrets = false;
};
system.build.installBootLoader = cfg.installHook;
};
}

View File

@ -0,0 +1,41 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-bootloader-external">
<title>External Bootloader Backends</title>
<para>
NixOS has support for several bootloader backends by default:
systemd-boot, grub, uboot, etc. The built-in bootloader backend
support is generic and supports most use cases. Some users may
prefer to create advanced workflows around managing the bootloader
and bootable entries.
</para>
<para>
You can replace the built-in bootloader support with your own
tooling using the <quote>external</quote> bootloader option.
</para>
<para>
Imagine you have created a new packaged called FooBoot. FooBoot
provides a program at
<literal>${pkgs.fooboot}/bin/fooboot-install</literal> which takes
the system closures path as its only argument and configures the
systems bootloader.
</para>
<para>
You can enable FooBoot like this:
</para>
<programlisting language="bash">
{ pkgs, ... }: {
boot.loader.external = {
enable = true;
installHook = &quot;${pkgs.fooboot}/bin/fooboot-install&quot;;
};
}
</programlisting>
<section xml:id="developing-custom-bootloader-backends">
<title>Developing Custom Bootloader Backends</title>
<para>
Bootloaders should use
<link xlink:href="https://github.com/NixOS/rfcs/pull/125">RFC-0125</link>s
Bootspec format and synthesis tools to identify the key properties
for bootable system generations.
</para>
</section>
</chapter>