Build a system from scratch

This guide describes how to build an operating system from scratch. If you are just willing to quickly install a system, the best option is to use the installer.

An intermediate system (such as a Linux distribution) is required to perform the installation from scratch.

BIOS setup

While the kernel partially supports UEFI, it must boot using the legacy bios.

This is due to the fact that the only way the kernel currently uses to display information on the screen is via the VGA text mode, which is not supported under UEFI.

Make sure legacy boot is enabled in your BIOS, or the kernel will not show anything on screen.

Kernel compilation

First cd into the kernel’s crate with:

cd kernel/

Configuration

The configuration file located at build-config.toml allows to specify which features have to be enabled in the kernel.

A default configuration is available in the file default.build-config.toml. If build-config.toml does not exist, the default configuration is used instead.

Build

After creating the configuration, the kernel can be built using the following commands:

cargo build               # Debug mode
cargo build --release     # Release mode

The default architecture is x86_64. To specify another architecture, add the following parameter to the build command: --target arch/<arch>/<arch>.json, where <arch> is the selected architecture.

The list of available architecture can be retrieved by typing:

ls -1 arch/

Disk creation (QEMU)

This section is for QEMU only. If building for a physical machine, skip it.

A disk can be created using the command:

dd if=/dev/zero of=qemu_disk count=1G status=progress

The count option can be tweaked to modify the size of the disk.

Disk preparation

Create partition table

If you don’t plan to install a bootloader, this section can be skipped.

The partition table can be created using the fdisk command.

Example:

fdisk /dev/sdX

where X is the letter associated to the disk on which you want to install the system.

Be careful! This is a destructive operating. Selecting the wrong disk might corrupt your system

Either GPT (recommended) or MBR partition tables can be used.

It is recommended to create at least two partitions:

• a boot partition for GRUB (approximately 200MB)
• a main partition for the system

Create filesystems

For each partition, create a filesystem using the mkfs command.

If you don’t have a partition table, you can just create a filesystem on the whole disk.

Example:

mkfs.ext2 /dev/sdXX

Be careful! This is a destructive operating. Selecting the wrong disk or partition might corrupt your system

The only filesystem that is currently supported is ext2.

Build the system

Now comes the moment to populate the filesystem.

First, mount the main partition’s filesystem:

mkdir mnt
mount <device file> mnt

When building for QEMU, use the qemu_disk file as device file.

Files hierarchy

Create a UNIX system files hierarchy:

mkdir -pv mnt/{bin,boot,dev,etc,home,lib,media,mnt,opt,proc,root,run,sbin,srv,sys,tmp,usr,var}
mkdir -pv mnt/etc/{opt,sysconfig}
mkdir -pv mnt/lib/firmware
mkdir -pv mnt/media/{floppy,cdrom}
mkdir -pv mnt/run/{lock,log}
mkdir -pv mnt/usr/{bin,include,lib,local,sbin,share,src}
mkdir -pv mnt/usr/share/{color,dict,doc,info,locale,man,misc,terminfo,zoneinfo}
mkdir -pv mnt/usr/local/{bin,include,lib,sbin,share,src}
mkdir -pv mnt/usr/local/share/{color,dict,doc,info,locale,man,misc,terminfo,zoneinfo}
mkdir -pv mnt/var/{cache,lib,local,log,mail,opt,spool}
mkdir -pv mnt/var/lib/{color,misc,locate}

Install packages

You can decide to compile and install packages by hand, or you can use maestro’s package manager.

The minimum recommended packages are:

• bash: shell
• blimp: package manager
• coreutils: GNU coreutils
• maestro-ps2: keyboard driver
• maestro-utils: system utility commands
• solfege: the boot system

Make sure to cross compile packages so that they are compatible with the kernel.

Install the bootloader

You might skip this section if running the OS using QEMU at the condition that you run the kernel only using the cargo run command. This is because GRUB2 is already present in the ISO file that is generated by this command.

If this is not the case, it is recommended to install GRUB2 or any other Multiboot2-compatible bootloader.

First, mount the boot partition:

mount /dev/sdXX mnt/boot

Install GRUB:

grub-install --target=i386-pc --boot-directory=mnt/boot /dev/sdXX

Write the grub.cfg file:

cat <<EOF >mnt/boot/grub/grub.cfg
menuentry "Maestro" {
	multiboot2 /maestro -root 8 X
}
EOF

where X is the partition number of the main filesystem, starting at 1.

Then, copy the kernel you compiled before:

cp -v target/<arch>/<profile>/maestro mnt/boot/

Set hostname

Set the hostname of the machine my writing it into the /etc/hostname file.

echo "myhostname" >mnt/etc/hostname

Create users and groups

You must at least create the root user for the system to work correctly. It is also recommended to create at least one other user with the name of your choice.

TODO

The end

Finally, unmount the filesystem:

umount mnt

The OS is now ready to be used! Have fun!