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:
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
-
cdinto the cloned directory and build the GCC Cross-Compiler toolchain:bash ./toolchain/build.sh
This build step will download the source code for GNU GCC 14.1.0 and GNU Binutils 2.42. It will then compile these tools, with customized settings 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 3 GB 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. -
Run the OS in
qemu:meson compile -C build qemu-run-image
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 the build step 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. Alternatively, you may want to build the kernel natively.
-
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-build-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 because if your build system is NOT a Linux environment compatible with Debian 12.5, the resulting toolchain binaries 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 instead of through Docker.
In any case, the toolchain 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 3 GB 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. -
Run the OS in
qemu:meson compile -C build qemu-run-image
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 :)