Contributor's Environment Setup Guide

This document is here in case you mess up your environment set-up very badly. For Debian-based Linux, the set-up instructions are as follows:

1. Ensure you have CMake >= 3.22 installed. The best way to ensure you install the up-to-date version is to follow this guide: Install CMake from Kitware's APT Repository
2. Ensure you have LLVM/Clang == 15 installed. The best way is to use the LLVM install script:

   wget https://apt.llvm.org/llvm.sh
   chmod +x llvm.sh
   sudo ./llvm.sh 15

   Remember to confirm that they're installed by checking if clang-15 exists under /usr/bin
3. Ensure you have QEMU >= 9 installed. On Linux, I find that building from scratch is the only way to go. On Windows (WSL) and Mac please just download the binaries.
   • Build on Linux with the switch:

     ./configure --enable-lto --disable-debug-info --target-list=aarch64-softmmu

     Then run make -j$(nproc) and sudo make install. See the official build guide here.
   • We want version >= 9 for Raspberry Pi 4b support.
4. We use Visual Studio Code as the de-facto IDE. All the user-independent configuration options for the language server is already provided in the .vscode/ directory. As well as any build tasks.
   • First, install all the workplace recommended extensions (we've pre-configured this, the configuration lives in .vscode/extensions.json)
   • Then, bring up the command palette (^⇧P or ⌘⇧P on Mac), run > Run Task and then run the (Re)-Configure CMake project task.
   • Finally, you can build by running the default build task, or by pressing ^⇧B or ⌘⇧B on Mac.
5. In the command line, you can run the following commands from the root of the project to build, if you want:

   $ rm -rf build
   $ cmake \
      -DCMAKE_C_COMPILER=/usr/bin/clang-15 \
      -DCMAKE_CXX_COMPILER=/usr/bin/clang++-15 \
      -DCMAKE_ASM_COMPILER=/usr/bin/llvm-mc-15 \
      . -B build
   $ make -C build all

6. To run the program, I use the command. This may not be the most recommended way in future, but it works for now.

   $ qemu-system-aarch64 -M raspi4b -kernel build/kernel8.img -serial stdio

   and you should see the serial UART0 output in the terminal.

Some important things to note:

• If you add new files, you should definitely re-run CMake. This allows CMake to re-generate the Makefiles. It shouldn't take long.
• If you want to see the build commands, run Make with the VERBOSE=1 setting. You can also review build/compile_commands.json to see the compilation database.