Fennix/INSTALL.md

🚀 Installation Guide

This guide will help you install Fennix on your system.

🛠️ Preparing the Environment

There are two ways to build the project:

1. 🐳 Use Dev Container (Recommended)
   • This is the easiest way to prepare the environment for building the project. But firstly, you need to install Docker and Visual Studio Code.
   • After installing Docker and Visual Studio Code, you can open the project in Visual Studio Code and click on the "Reopen in Container" button.
   • This will open the project in a Dev Container with all the required tools installed.
   • If you encounter errors while the Dev Container is building, ensure the following are correctly configured:
     • /tmp/.X11-unix
     • Environment variable XAUTHORITY
     • /run/user/1000/pulse/native
     • Note: These configurations are only necessary if you plan to use QEMU inside the container.
2. 💻 Build the Project Locally
   • The instructions below will guide you through the process of building the project locally.

NOTE: You MUST have autoconf 2.69 and automake 1.15.1 versions installed on your system. A complete list of dependencies can be found in the .devcontainer/Dockerfile file.

Before building the project, you need to build the cross-compiler toolchain and QEMU.
You can do this by running the following command:

make setup

This will clone, patch, and build the required tools for you.

Alternatively, if you wish to skip building QEMU, you can run make setup-no-qemu.
However, in this case, you will need to manually specify the path to the QEMU binary in the config.mk file.

🏗️ Building the Project

To build the project, run:

make build

This will build the kernel, userspace, and drivers. The resulting ISO image will be Fennix.iso.

🚀 Running the OS

To run the OS, execute:

make run

The run target will automatically build the project if it hasn't been built yet.

⚙️ Additional Configuration

You can customize the project by editing the config.mk file.

🧪 Debugging

If you use Visual Studio Code, you can press F5 to start debugging the OS.
The configuration is already set up for you.

Alternatively, you can run the following command to start debugging:

make debug

This will start QEMU in debug mode, allowing you to connect to it using GDB.

The GDB FIFO file is located at /tmp/gdb-fennix.