axe-os/README.md

Axe OS

Axe OS is a from-scratch operating system, driven by Linux From Scratch and others like it.

Instead of creating a full-fledged desktop system, it is more about simplicity and a lightweight module-based approach. It is intended for use with my C/C++, and Go code bases. Simplicity and control have been prioritised over completeness in this.

With the Docker runtime, any additional dependencies or utilities required in the future by the system can be built or downloaded inside Docker containers. This way, the host system is left clean; no need to install any dependencies.

Project Structure

The project is structured to keep configurations, utilities, and package builds clearly separated and easy to maintain.

configs/
	global.env
	global.chroot.env
	utilities.bash

build/
	{package}/
		package.env
		build.bash
	...

Configuration

• configs/global.env

  • Environment variables specific to the bootstrap and toolchain build environment stage.

• configs/global.chroot.env

  • Environment variables specific to the setup and final build environment stage.

• configs/utilities.bash

  • Common helper functions used by build scripts.

Build System

Each package lives in its own directory under build/ and defines:

• package.env — package-specific configuration and versioning

• build.bash — the build logic for that package, include logic for all build stage support by package

Build Stages

Packages are built in four distinct stages, following a progressive bootstrapping model:

1. Bootstrap

Minimal components required to bring up a usable base toolchain:

• binutils

• GCC

• Linux headers

• glibc

• libstdc++

2. Toolchain

Core Unix tools and a more complete compiler toolchain:

• m4, ncurses

• coreutils, diffutils, file, findutils

• gawk, grep, gzip, make, patch, sed, tar, xz

• binutils, gcc

3. Setup

Tools required for building more complex software:

• bison

• Perl

• Python

• texinfo

• util-linux

4. Final

Rebuilds most of the previous components in their final form and installs higher-level software, including:

• Docker and graphics stack support

• Development tools such as git

• Networking and utility dependencies (e.g curl)

• Additional packages required by the target C/C++ and Go codebases

Sources, Sysroot, and Mounts

All package source archives are downloaded into a shared sources/ directory.

The build uses multiple sysroots depending on the stage:

• sysroot/cross
  Used during the bootstrap and toolchain stages to build an isolated cross-compilation environment.

• sysroot/
  Represents the final target system and is used during the setup and final stages.

During the setup and final stages, the following directories are mounted into the chroot environment to make them accessible during the build:

• sources/
• build/

This approach keeps source archives and build scripts outside the target filesystem while still allowing full visibility inside the chroot when needed.

Contributing

Contributions are welcome.

This project is experimental and intentionally minimal, so clarity and simplicity are preferred over feature expansion. If you plan to contribute:

• Keep changes focused and well-scoped
• Follow the existing project structure and build stages
• Avoid introducing unnecessary dependencies
• Document any non-obvious behavior or design decisions

Before submitting large or architectural changes, consider opening an issue to discuss the approach first.

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

License

Axe OS is licensed under the MIT License.

This license applies only to the Axe OS build scripts, configuration files, and documentation contained in this repository. It does not override or alter the licenses of third-party software built by the system (such as the Linux kernel, GCC, glibc, or other packages), which remain under their respective upstream licenses.