Many common problems are answered in the FAQ document, so if you experience problems please check whether the CRUX FAQ contains answers to your questions already.
If you have further questions, there's a dedicated mailing list for CRUX, and an IRC channel. Actual information about these can be found on the Community page.
If grub-mkconfig does not work (eg., because you saved the kernel image under a non-standard name), a grub.cfg file can be created manually. For more information see the GRUB manual at http://www.gnu.org/software/grub/manual/. A simple example configuration might look like the following:
# Display the menu for 10 seconds
set timeout=10
# Boot the first entry by default
set default=0
# Boot entries follow
# Default CRUX boot entry
menuentry "CRUX 3.7" {
linux (hd0,msdos2)/boot/vmlinuz-5.15.55 root=/dev/sda2 quiet
}
# Single-user recovery entry
menuentry "CRUX 3.7 single-user mode" {
linux (hd0,msdos2)/boot/vmlinuz-5.15.55 root=/dev/sda2 quiet single
}
# Memory test entry
menuentry "MemTest86+ 4.20" {
linux16 (hd0,msdos2)/boot/memtest86+-4.20.bin
}
Save the manual configuration file as /boot/grub/grub.cfg.
GRUB and SYSLINUX offer the most familiar experience for users coming from LILO. After a one-time interaction with the BIOS and the Master Boot Record, all subsequent updates to the GRUB or SYSLINUX configuration only involve editing a flat-text file. Although with LILO you had to run /sbin/lilo after editing its flat-text config, for GRUB and SYSLINUX you never have to touch the contents of the bootsector or the NVRAM after the initial installation; changes to their flat-text config files are automatically detected.
A third way to boot into your CRUX system involves direct interaction with the EFI variables, letting the Linux kernel image provide the required EFI bootloader code. This option has a workflow that might remind you of running /sbin/lilo after building and installing each new kernel.
As with GRUB and SYSLINUX, the kernel has to be told which device to use as a root filesystem. Most modern BIOSes allow you to append options like root=/dev/sda2 to the line that boots the kernel, but some buggy UEFI implementations do not honor such appended options. To be safe, you can customize the boot options during the kernel configuration process (the make menuconfig step), at the expense of making it harder to put the disk in an external enclosure and boot from USB (when you want to travel lightly). If you leave the boot options empty during kernel configuration, and the BIOS does not honor your appended options, you might have to boot from a rescue disk to get back into your system and fix things.
$ mkdir -p /boot/efi/BOOT $ cd /boot/efi/BOOT $ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55.efi
$ efibootmgr -c -d /dev/sda -L 'Linux 5.15.55' -l '\BOOT\vmlinuz-5.15.55.efi' -u 'root=/dev/sda2'
$ efibootmgr BootCurrent: 0000 Timeout: 1 seconds BootOrder: 0000,0001 Boot0000* Linux 5.15.26 HD(1,GPT,d5a44413-...,0x800,0x64000)/File(\BOOT\vmlinuz-5.15.26.efi)72006f006f0074... Boot0001* Linux 5.15.55 HD(1,GPT,d5a44413-...,0x800,0x64000)/File(\BOOT\vmlinuz-5.15.55.efi)72006f006f0074... $ efibootmgr -o 0001,0000
efibootmgr commands, since efibootmgr is agnostic about the mountpoint of your EFI system partition. The two most common ways to shorten what looks like an overly-verbose path to the kernel are:
mkdir and cd commands as needed).
efibootmgr invocation as needed).
A common scenario that prevents the usual practice of booting a slimmed-down kernel containing only the drivers for the root filesystem (and then loading modules to initialize other hardware) is that the root filesystem is not a physical volume, but rather a logical volume inside an encryption layer like LUKS. To handle this situation, you will need to go beyond the kernel building process outlined above, and also create a compressed filesystem image (called an initramfs) that contains the lvm2 and cryptsetup packages (and the drivers for usb input devices, if you chose not to compile them into the kernel). Creating such an initramfs was once an intricate procedure, but tools like dracut make it much simpler these days.
If running dracut, and saving the initramfs alongside the kernel in the EFI system partition, had been the only deviations from the usual CRUX installation procedure, then one section of the appendix would suffice to explain how to do full-disk encryption in CRUX. But preparation for this setup begins at the partitioning stage, when you need to call commands from the lvm2 and cryptsetup packages before creating and mounting your filesystems. So this section of the appendix just points to a separate document, where an outline for installing CRUX with full-disk encryption is given from beginning to end. Even if full-disk encryption is not your desired endpoint and you just want to learn more about highly-modular kernel configs, the need for an initramfs is easier to motivate by considering a specific use case like full-disk encryption. Studying the upstream documentation for any unfamiliar command in the linked outline (eg., cryptsetup, pvcreate, or dracut) is an excellent way to distinguish the functions performed at each step of the process.