First commit, Vystem v0.1

docs/build.md

@@ -0,0 +1,54 @@
+# 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:
+``` bash
+./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.