t5os is a small hobby operating system written in C.
This project supports native and cross-platform compilation with Docker. To build the project on your system (the build machine), you will need the following tools for your platform:
- Project compilation tools:
- GRUB tools (optional)1:
xorrisogrub-commongrub-pc-bin
- Emulation software:
qemu-system-i386
This is the recommended method if you would like to contribute to the project.
-
Clone the repository:
git clone https://github.com/ta5een/t5os.git
-
Build the GCC Cross-Compiler toolchain:
make toolchain
This build step will download the source code for the GNU GCC 14.1.0 compiler and the GNU Binutils 2.42 binary tools. It will then compile these tools, with settings tweaked so that it can build programs for the
$ARCHtarget from the build machine. By default,$ARCHis set toi686(i.e., x86 32-bit).The resulting binaries, headers, and archives will be placed inside the
toolchaindirectory.NOTE: This process will take a while to complete, depending on your machine's specifications. Once complete, the resulting build artifacts will take up around 3GB of disk space. Make sure you have enough disk space (and patience) for this step :)
-
Set up a
builddirectory withmeson:meson setup build --cross-file ./meson/cross/i686-elf.ini
Meson works by building projects out-of-source. This means that all files generated during the build are placed in a separate directory. It is thus possible to have multiple build directories, each with their own configurations.
With the above command, we request Meson to set up a build directory (aptly named
build) that is configured to target an i686 host machine. The provided cross build definition file informs Meson of the compiler and tools to be used when building for the selected architecture. Currently, only the i686 architecture is supported. -
Build the kernel with
meson:meson compile -C build
Running the command above will start the build process with the new
builddirectory we created in the previous step. If you named the build directory differently, make sure to change the name after the-Cflag.To provide editor support with
clangd, you must have built the kernel at least once. This is because Meson will generate acompile_commands.jsonfile in the provided build folder, which is essential forclangdto work properly. Note thatclangdsearches for this file in specific locations, so you may need to configureclangdif it can't find the file. -
Build the
.isoimage:make iso
This build step requires
xorriso,grub-common, andgrub-pc-binto be available on your system. Alternatively, follow the Docker instructions below to build the.isoimage without needing to install these tools locally. -
Run the OS in
qemu:make qemu
Note
If you previously compiled the toolchain on a non-Linux system that doesn't
natively produce ELF binaries, the toolchain will NOT be compatible with
the Debian environment in Docker. This would certainly be the case if you ran
make toolchain on macOS or Windows. If you would like to primarily build
the kernel in a Docker container, please rebuild the toolchain as instructed
in the steps below.
This is the recommended method if you would like to play around with the project and don't want to install all the required dependencies. It is also possible to first build the kernel natively and then create the ISO with Docker (which has access to the legacy GRUB tools), thanks to the power of bind mounts.
-
Clone the repository:
git clone https://github.com/ta5een/t5os.git
-
Build the Docker image:
bash ./scripts/docker-build-image.sh
-
Build the toolchain in a Debian environment:
bash ./scripts/docker-make-toolchain.sh
This command will spawn an ephemeral Docker container, bind the current working directory as a volume, and run the toolchain build process. By binding the current working directory, the container will have direct access to only this directory in your system and can make changes to it in a way that will be visible to you.
This is important to note as if your system is NOT a Linux environment similar to Debian 12.5, the toolchain binaries that will be built will NOT be compatible with your system. This may not be a concern if you don't plan on using the toolchain outside the container, but if you do, consider building the toolchain natively by following steps 1, 2, and 3.
In any case, the resulting binaries, headers, and archives will be placed inside the
toolchaindirectory.NOTE: This process will take a while to complete, depending on your machine's specifications. Once complete, the resulting build artifacts will take up around 3GB of disk space. Make sure you have enough disk space (and patience) for this step :)
-
Build the
.isoimage:bash ./scripts/docker-make-iso.sh
Like the step before, this will build the
.isoimage inside (a different instance of) an ephemeral Docker container. Once completed,./build/kernel/t5os.isowill be available in your local filesystem. -
Run the OS in
qemu:make qemu
- QEMU: Run
make qemu - VMware/VirtualBox/etc.: Build the
.isowithmake isoand boot the virtual machine with this disk image (via USB or CD/DVD).
Here is a non-exhaustive list of online resources that have helped me immensely in this project (in no particular order):
This project is licensed under the GNU General Public License v3.0. See License for more details.
Additionally, many parts of this project, from its implementation to its behavior, have been derived from multiple open-source projects. Wherever possible, I've added an attribution comment on top of the relevant file/function/line in the source code. For reference, here is a list of projects I've taken inspiration from (in alphabetical order):
If for any reason you believe I have used your work and haven't credited you and/or abided by your license(s), please feel free to reach out to me :)
Footnotes
-
It is possible to run these tools with the provided Docker configuration. ↩