limine/README.md

229 lines
8.1 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?
2022-03-22 06:48:24 +03:00
Limine is a modern, advanced x86/x86_64 BIOS/UEFI multiprotocol bootloader, used
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")
2022-03-11 06:57:47 +03:00
[Photo by Martin Damboldt from Pexels](https://www.pexels.com/photo/gray-bridge-and-trees-814499/)
2020-11-09 16:29:53 +03:00
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
### Supported filesystems
2020-09-21 15:08:45 +03:00
* ext2/3/4
2021-05-11 07:46:42 +03:00
* FAT12/16/32
2022-01-22 06:10:48 +03:00
* NTFS
2021-02-25 08:44:41 +03:00
* ISO9660 (CDs/DVDs)
2020-04-20 13:39:24 +03:00
### Supported partitioning schemes
* MBR
* GPT
2021-02-25 08:44:41 +03:00
* Unpartitioned media
2020-04-20 13:39:24 +03:00
2022-03-02 20:08:06 +03:00
### Minimum system requirements
While Limine is made with modern, 64-bit, PCs in mind, it supports 32-bit
ones as well, starting with PCs with Pentium Pro class CPUs.
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)).
2022-03-22 06:48:24 +03:00
For example, to clone the latest binary release of the `v3.x` branch one can do
```bash
2022-03-22 06:48:24 +03:00
git clone https://github.com/limine-bootloader/limine.git --branch=v3.0-branch-binary --depth=1
```
2022-05-22 07:17:36 +03:00
or, to clone a specific binary point release (for example `v3.5`)
```bash
2022-05-22 07:17:36 +03:00
git clone https://github.com/limine-bootloader/limine.git --branch=v3.5-binary --depth=1
```
2021-03-21 11:16:06 +03:00
2022-04-02 10:31:19 +03:00
`limine-deploy` binaries are provided for Windows.
2022-04-02 10:31:19 +03:00
In order to rebuild `limine-deploy`, simply run `make` in the binary
2022-01-22 06:10:48 +03:00
release directory.
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".*
### Building the toolchain
2020-09-13 16:47:43 +03:00
This step can take a long time, but it will ensure that the toolchain will work
2022-01-22 06:10:48 +03:00
with Limine. If on an x86_64 host, with GCC or Clang installed, it is possible
that the host toolchain will suffice. You can skip to the next paragraph in order
to use the system's toolchain instead. If that fails, you can still come back here
2022-02-02 18:24:13 +03:00
later (remember to `make clean` and re-run `./configure` after building the toolchain).
2022-03-02 20:08:06 +03:00
The toolchain's build process depends on the following packages: `GNU make`,
`GNU tar`, `texinfo`, `curl`, `gzip`, `bzip2`, `gcc/clang`, `g++/clang++`.
Building the toolchain can be accomplished by running:
2020-09-13 16:47:43 +03:00
```bash
./make_toolchain.sh
2020-09-13 16:47:43 +03:00
```
### Prerequisites
2022-03-02 20:08:06 +03:00
In order to build Limine, the following programs have to be installed:
`GNU make`, `grep`, `sed`, `find`, `awk`, `gzip`, `nasm`, `mtools`
(optional, necessary to build `limine-cd-efi.bin`).
Furthermore, either the toolchain must have been built in the previous
2022-01-16 08:09:36 +03:00
paragraph, or `gcc` or `llvm/clang` must also be installed, alongside
the respective binutils. `nasm` is optional if the toolchain was built in the previous
2022-03-02 20:08:06 +03:00
paragraph as it is built as part of it.
### 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`.
To build using the LLVM toolchain, pass `TOOLCHAIN=llvm` to `./configure`.
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
```
2022-03-02 20:19:40 +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
release directory just fine. This step will only install them to a `share` and
2022-01-16 08:09:36 +03:00
`bin` directories in the specified prefix (default is `/usr/local`, see
2022-01-22 06:10:48 +03:00
`./configure --help`, or the `PREFIX` variable if installing 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 `BOOTX64.EFI` file is a vaild EFI application that can be simply copied to
the `/EFI/BOOT` directory of a FAT formatted EFI system partition. This file 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.
The boot device must to contain the `limine.cfg` file in
either the root or the `boot` directory of one of the partitions, formatted
with a supported file system (the ESP partition is recommended).
### BIOS/MBR
In order to install Limine on a MBR device (which can just be a raw image file),
2022-04-02 10:31:19 +03:00
run `limine-deploy` as such:
2020-04-07 08:24:19 +03:00
```bash
2022-04-02 10:31:19 +03:00
limine-deploy <path to device/image>
2020-04-07 08:24:19 +03:00
```
2021-02-26 02:32:02 +03:00
The boot device must to contain the `limine.sys` and `limine.cfg` files in
either the root or the `boot` 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.
2022-04-02 10:31:19 +03:00
* Letting `limine-deploy` 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
2022-04-02 10:31:19 +03:00
to `limine-deploy` as a second argument; such as:
2020-04-20 13:39:24 +03:00
```bash
2022-04-02 10:31:19 +03:00
limine-deploy <path to device/image> <1-based stage 2 partition number>
2020-04-20 13:39:24 +03:00
```
2022-04-02 10:31:19 +03:00
In case one wants to let `limine-deploy` embed stage 2 within GPT's structures,
simply omit the partition number, and invoke `limine-deploy` the same as one
would do for an MBR partitioned device.
2021-02-26 02:32:02 +03:00
The boot device must to contain the `limine.sys` and `limine.cfg` files in
either the root or the `boot` 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.
2021-02-26 02:32:02 +03:00
(`limine.sys` and `limine.cfg` must either be in the root or inside a `boot`
subdirectory; `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
2022-04-02 10:31:19 +03:00
And do not forget to also run `limine-deploy` on the generated image:
```
2022-04-02 10:31:19 +03:00
limine-deploy 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.
### 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).
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.