rulimine/README.md

239 lines
8.6 KiB
Markdown
Raw Normal View History

2020-08-29 21:02:16 +03:00
# Limine
2020-09-18 21:08:19 +03:00
2020-09-21 15:08:45 +03:00
### What is Limine?
Limine is a modern, advanced, portable, multiprotocol bootloader, also used
2022-03-22 06:48:24 +03:00
as the reference implementation for the [Limine boot protocol](/PROTOCOL.md).
2020-09-21 15:08:45 +03:00
2020-09-25 23:39:14 +03:00
### Limine's boot menu
2020-04-07 08:24:19 +03:00
2020-08-05 01:08:40 +03:00
![Reference screenshot](/screenshot.png?raw=true "Reference screenshot")
2023-03-07 00:22:58 +03:00
[Photo by Rostislav Uzunov](https://www.pexels.com/photo/purple-and-pink-diamond-on-blue-background-5011647/)
2020-11-09 16:29:53 +03:00
### Supported architectures
* IA-32 (32-bit x86)
* x86_64
* aarch64 (arm64)
2020-04-20 13:39:24 +03:00
### Supported boot protocols
* Linux
2022-03-22 06:48:24 +03:00
* [Limine](/PROTOCOL.md)
* Multiboot 1
* Multiboot 2
2021-07-06 04:17:28 +03:00
* Chainloading
2020-04-20 13:39:24 +03:00
2023-02-06 22:24:57 +03:00
### Supported partitioning schemes
* MBR
* GPT
* Unpartitioned media
2020-04-20 13:39:24 +03:00
### Supported filesystems
* ext2/3/4
2021-05-11 07:46:42 +03:00
* FAT12/16/32
2021-02-25 08:44:41 +03:00
* ISO9660 (CDs/DVDs)
2020-04-20 13:39:24 +03:00
2023-02-06 22:24:57 +03:00
If your filesystem isn't listed here, please read [the philosophy](/PHILOSOPHY.md) first, especially before
opening issues or pull requests related to this.
2020-04-20 13:39:24 +03:00
2022-03-02 20:08:06 +03:00
### Minimum system requirements
For 32-bit x86 systems, support is only ensured starting with those with
Pentium Pro (i686) class CPUs.
All x86_64 and aarch64 (UEFI) systems are supported.
2022-03-02 20:08:06 +03:00
2023-02-07 02:42:13 +03:00
## Packaging status
[![Packaging status](https://repology.org/badge/vertical-allrepos/limine.svg)](https://repology.org/project/limine/versions)
2021-03-21 11:16:06 +03:00
## Binary releases
For convenience, for point releases, binaries are distributed. These binaries
are shipped in the `-binary` branches and tags of this repository
(see [branches](https://github.com/limine-bootloader/limine/branches/all) and
[tags](https://github.com/limine-bootloader/limine/tags)).
For example, to clone the latest binary release of the `v4.x` branch one can do
```bash
git clone https://github.com/limine-bootloader/limine.git --branch=v4.x-branch-binary --depth=1
```
2023-02-07 02:42:13 +03:00
or, to clone a specific binary point release (for example `v4.20230120.0`)
```bash
2023-02-07 02:42:13 +03:00
git clone https://github.com/limine-bootloader/limine.git --branch=v4.20230120.0-binary --depth=1
```
2021-03-21 11:16:06 +03:00
In order to rebuild host utilities like `limine`, simply run `make` in the binary
2022-01-22 06:10:48 +03:00
release directory.
2021-03-21 11:16:06 +03:00
2023-02-07 02:42:13 +03:00
Host utility binaries are provided for Windows.
2022-07-05 17:19:00 +03:00
2021-03-21 11:16:06 +03:00
## Building the bootloader
2022-01-22 06:10:48 +03:00
*The following steps are not necessary if cloning a binary release. If so, skip to*
*"Installing Limine binaries".*
### Prerequisites
2022-03-02 20:08:06 +03:00
In order to build Limine, the following programs have to be installed:
common UNIX tools (also known as `coreutils`),
2022-03-02 20:08:06 +03:00
`GNU make`, `grep`, `sed`, `find`, `awk`, `gzip`, `nasm`, `mtools`
(optional, necessary to build `limine-cd-efi.bin`).
Furthermore, `gcc` or `llvm/clang` must also be installed, alongside
the respective binutils.
### Configure
2022-01-22 06:10:48 +03:00
If using a release tarball (recommended, see https://github.com/limine-bootloader/limine/releases),
run `./configure` directly.
2022-06-15 01:35:16 +03:00
If checking out from the repository, run `./bootstrap` first in order to download the
necessary dependencies and generate the configure script (`GNU autoconf` and `GNU automake` required).
2022-06-15 01:35:16 +03:00
`./configure` takes arguments and environment variables; for more information on
these, run `./configure --help`.
**`./configure` by default does not build any Limine port. Make sure to read the**
**output of `./configure --help` and enable any or all ports!**
2022-01-22 06:10:48 +03:00
Limine supports both in-tree and out-of-tree builds. Simply run the `configure`
script from the directory you wish to execute the build in. The following `make`
commands are supposed to be ran inside the build directory.
### Building Limine
To build Limine, run:
2020-09-13 16:47:43 +03:00
```bash
make # (or gmake where applicable)
2020-09-13 16:47:43 +03:00
```
The generated bootloader files are going to be in `./bin`.
2021-03-21 11:16:06 +03:00
## Installing Limine binaries
This step is optional as the bootloader binaries can be used from the `./bin` or
2022-07-05 22:04:18 +03:00
release directory just fine. This step will only install them to `share`, `include`, and
2022-01-16 08:09:36 +03:00
`bin` directories in the specified prefix (default is `/usr/local`, see
2022-07-05 22:04:18 +03:00
`./configure --help`, or the `PREFIX` variable if installing from a binary release).
2021-02-25 10:18:43 +03:00
2022-01-16 08:09:36 +03:00
To install Limine, run:
```bash
2022-01-22 05:10:25 +03:00
make install # (or gmake where applicable)
2022-01-16 08:09:36 +03:00
```
## How to use
### UEFI
The `BOOT{IA32,X64,AA64}.EFI` files are valid EFI applications that can be simply copied to
the `/EFI/BOOT` directory of a FAT formatted EFI system partition. These files can
be installed there and coexist with a BIOS installation of Limine (see below) so
that the disk will be bootable on both BIOS and UEFI systems.
2023-02-07 02:42:13 +03:00
The boot device must contain the `limine.cfg` files in
either the root, `limine`, `boot`, or `boot/limine` directory of one of the
partitions, formatted with a supported file system (the ESP partition is recommended).
### Secure Boot
Limine can be booted with secure boot using shim. This will also allow one to enroll
the BLAKE2B hash of the Limine config file into the Limine EFI executable image itself for
verification purposes.
For more information see the `limine enroll-config` program and [the philosophy](/PHILOSOPHY.md).
### BIOS/MBR
In order to install Limine on a MBR device (which can just be a raw image file),
run `limine bios-install` as such:
2020-04-07 08:24:19 +03:00
```bash
limine bios-install <path to device/image>
2020-04-07 08:24:19 +03:00
```
2023-02-07 02:42:13 +03:00
The boot device must contain the `limine.sys` and `limine.cfg` files in
either the root, `limine`, `boot`, or `boot/limine` directory of one of the
partitions, formatted with a supported file system.
2021-02-25 10:18:43 +03:00
### BIOS/GPT
If using a GPT formatted device, there are 2 options one can follow for
installation:
* Specifying a dedicated stage 2 partition.
* Letting `limine bios-install` attempt to embed stage 2 within GPT structures.
In case one wants to specify a stage 2 partition, create a partition on the GPT
device of at least 32KiB in size, and pass the 1-based number of the partition
to `limine bios-install` as a second argument; such as:
2020-04-20 13:39:24 +03:00
```bash
limine bios-install <path to device/image> <1-based stage 2 partition number>
2020-04-20 13:39:24 +03:00
```
In case one wants to let `limine bios-install` embed stage 2 within GPT's structures,
simply omit the partition number, and invoke `limine bios-install` the same as one
would do for an MBR partitioned device.
2023-02-07 02:42:13 +03:00
The boot device must contain the `limine.sys` and `limine.cfg` files in
either the root, `limine`, `boot`, or `boot/limine` directory of one of the
partitions, formatted with a supported file system.
2021-02-25 10:18:43 +03:00
### BIOS/UEFI hybrid ISO creation
In order to create a hybrid ISO with Limine, place the
`limine-cd-efi.bin`, `limine-cd.bin`, `limine.sys`, and `limine.cfg` files
into a directory which will serve as the root of the created ISO.
(`limine.sys` and `limine.cfg` must either be in the root, `limine`, `boot`, or
`boot/limine` directory; `limine-cd-efi.bin` and `limine-cd.bin` can reside
anywhere).
2021-02-25 08:44:41 +03:00
Place any other file you want to be on the final ISO in said directory, then
run:
2021-02-25 08:44:41 +03:00
```
xorriso -as mkisofs -b <relative path of limine-cd.bin> \
-no-emul-boot -boot-load-size 4 -boot-info-table \
--efi-boot <relative path of limine-cd-efi.bin> \
-efi-boot-part --efi-boot-image --protective-msdos-label \
<root directory> -o image.iso
2021-02-25 08:44:41 +03:00
```
*Note: `xorriso` is required.*
2021-02-25 08:44:41 +03:00
And do not forget to also run `limine bios-install` on the generated image:
```
limine bios-install image.iso
```
`<relative path of limine-cd.bin>` is the relative path of
`limine-cd.bin` inside the root directory.
For example, if it was copied in `<root directory>/boot/limine-cd.bin`,
it would be `boot/limine-cd.bin`.
`<relative path of limine-cd-efi.bin>` is the relative path of
`limine-cd-efi.bin` inside the root directory.
For example, if it was copied in
`<root directory>/boot/limine-cd-efi.bin`, it would be
`boot/limine-cd-efi.bin`.
### BIOS/PXE boot
2021-02-26 02:32:02 +03:00
The `limine-pxe.bin` binary is a valid PXE boot image.
In order to boot Limine from PXE it is necessary to setup a DHCP server with
support for PXE booting. This can either be accomplished using a single DHCP
server or your existing DHCP server and a proxy DHCP server such as dnsmasq.
2021-02-26 02:32:02 +03:00
`limine.cfg` and `limine.sys` are expected to be on the server used for boot.
### UEFI/PXE boot
The `BOOT{IA32,X64,AA64}.EFI` files are compatible with UEFI PXE.
The steps needed to boot Limine are the same as with BIOS PXE,
except that you don't need `limine.sys` in the server.
### Configuration
2021-02-26 02:32:02 +03:00
The `limine.cfg` file contains Limine's configuration.
2020-04-07 08:24:19 +03:00
2021-08-26 04:16:54 +03:00
An example `limine.cfg` file can be found in [`test/limine.cfg`](https://github.com/limine-bootloader/limine/blob/trunk/test/limine.cfg).
2020-04-07 08:24:19 +03:00
2021-08-26 04:11:52 +03:00
More info on the format of `limine.cfg` can be found in [`CONFIG.md`](https://github.com/limine-bootloader/limine/blob/trunk/CONFIG.md).
2020-04-21 20:18:13 +03:00
2020-09-13 16:47:43 +03:00
## Acknowledgments
Limine uses a stripped-down version of [tinf](https://github.com/jibsen/tinf) for GZIP decompression.
2023-03-05 10:01:41 +03:00
Limine relies on [stb_image](https://github.com/nothings/stb/blob/master/stb_image.h) for wallpaper image loading.
2020-05-02 18:02:05 +03:00
## Discord server
We have a [Discord server](https://discord.gg/QEeZMz4) if you need support,
info, or you just want to hang out with us.