updated README.md, added .gitignore, created initial project structure

2026-02-06 22:12:38 +02:00
parent f822ebcb04
commit e698e1f3b4
5 changed files with 160 additions and 4 deletions
--- a/README.md
+++ b/README.md
@@ -1,10 +1,143 @@
-# Axe OS
+# **Axe OS**

-Axe OS is a minimal, from-scratch operating system inspired by Linux From Scratch (LFS) and similar projects.
+**Axe OS** is a from-scratch operating system, driven by Linux From Scratch and others like it.

-Rather than building a full blown desktop system, the focus is on a lightweight and modular approach using Docker as the build environment. Any additional dependencies or tools required by the system are built or fetched inside Docker containers. This approach ensures the host system remains clean, with no direct installation of build-time or runtime dependencies.
+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. 

-The system is tailored specifically for my C/C++ and Go codebases, prioritising simplicity, control, and reproducibility over completeness.
+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.