vystem/docs/build.md

Build process

Introduction

In this file, we will see how you can build and boot successfully into a VM containing a Vystem disk image. It's recommanded to read the whole documentation for better understanding of why certains parts are necessary.

Prerequisites

You should have cloned the full repository on your device. Please keep in mind that Vystem hasn't been tested on real hardware yet, so the only way to test it is through a virtual machine.

Vystem has been designed to be build and run from a standard Linux system. Any Linux distro should work. A WSL environnement can also work but the VM might be very slow, because of KVM unavailability. Make sure you have KVM enable and accessible before starting, or else remove the --enable-kvm argument at the end of the build script.

Before starting, please make sure that you have the following binary reachable in your terminal path:

python3 python nasm g++ gcc iasl git make sed wget unzip fallocate parted mkfs.fat sgdisk partprobe losesetup qemu-system-x86_64 

Finally, please make sure that you have an internet connexion (required for downloading additionnal assets like EDK II and Argon2) as well as root access/sudo permissions, as it is recommanded for running keygen and required for creating the disk image. Root permissions is only obtained as soon as it's needed. If you don't want to give root permissions, you can also run the commands inside the build script one by one just to be sure.

Build and run

Once you are ready, run the following command while being in the root folder:

./build.sh

This will download, compile, and assemble every asset together. This can take a while depending on your internet connexion, since EDK II is quite heavy and will be downloaded from it's source repository and locally compiled, with OVMF. For the moment, using packaged versions of EDK II and/or OVMF provided by packages managers isn't supported.

The VM will automatically be launched with 4 gigabytes of RAM (you can obviously raise or lower that amount depending on your device), KVM enabled and serial port output redirected inside the terminal.

Detailled build process

The folder used for InitFS base is named initfs_dir and is placed in the root folder of the repository. The build process is as follow:

1. Checking virtual memory layout
2. Generating payloads for TAB subsystem
3. Compiling Keycard and putting it into initfs_dir
4. Compiling Vyld
5. Compiling Shelter and putting it into initfs_dir
6. Cloning EDK II, building required tools and OVMF
7. Compiling bootanim and generating boot animation
8. Compiling fontgen and generating font
9. Compiling initfsgen and generating InitFS and SignSyst
10. Patching bootloader configuration template to insert random partition GUID and fixed partition type GUID
11. Cloning and building Argon2, compiling keygen and generating required files for SPFIE
12. Compiling bootloader
13. Generating disk image
14. Launching virtual machine

Troubleshooting

If anything goes wrong, the script will stop and show you the error. Sometimes it's just a dependency that isn't reachable. Carefully analyse the error message and try to install the missing dependencies, also check that the required dependencies listed above are all installed.

If it's related to EDK II (which occur the majority of the time), it could be that a new update in EDK II has broken something. Don't hesitate to open an issue, and this should be fix fairly quickly.