MetalOS/docs/BUILD_SYSTEMS.md

MetalOS Build Systems Guide

MetalOS supports multiple build systems to accommodate different developer preferences and workflows.

Quick Start

Using Make (Traditional)

make all      # Build everything
make qemu     # Test in QEMU
make clean    # Clean build artifacts

Using CMake + Make

mkdir build && cd build
cmake ..
cmake --build .

Using CMake + Ninja (Fastest)

mkdir build && cd build
cmake -G Ninja ..
ninja

Using Conan + CMake

mkdir build && cd build
conan install .. --build=missing
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
cmake --build .

Build System Comparison

Build System	Speed	Features	Best For
Make	Medium	Simple, traditional	Quick builds, CI/CD
CMake	Medium	Cross-platform, modern	Complex projects, IDEs
Ninja	Fast	Parallel builds	Development, large projects
Conan	Medium	Dependency management	Projects with external deps

Detailed Usage

1. Make (Traditional Build System)

The original build system using GNU Make.

Build Commands

# Build all components
make all

# Build individually
make bootloader
make kernel
make test

# Create bootable image
make image

# Run in QEMU
make qemu                    # Headless mode
make qemu QEMU_DISPLAY=gtk   # With GUI
make qemu-debug              # With debug output
make qemu-gdb                # With GDB server

# Clean
make clean       # Clean build artifacts
make distclean   # Deep clean

Advantages

• ✅ Simple and straightforward
• ✅ No additional dependencies
• ✅ Works on all Unix-like systems
• ✅ Easy to understand and modify

Disadvantages

• ❌ Not cross-platform (Windows requires special setup)
• ❌ Can be slower for large projects
• ❌ Limited dependency tracking

---

2. CMake (Modern Build Generator)

CMake generates build files for various build systems (Make, Ninja, Visual Studio, etc.).

Build Commands

# Configure (generates build files)
mkdir build && cd build
cmake ..

# Configure with specific generator
cmake -G "Unix Makefiles" ..
cmake -G Ninja ..
cmake -G "Visual Studio 17 2022" ..  # Windows

# Configure with options
cmake -DBUILD_BOOTLOADER=ON -DBUILD_KERNEL=ON -DBUILD_TESTS=ON ..
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake -DCMAKE_BUILD_TYPE=Release ..

# Build
cmake --build .
cmake --build . --parallel 8  # Use 8 parallel jobs

# Build specific targets
cmake --build . --target bootloader_efi
cmake --build . --target kernel_bin
cmake --build . --target image

# Run custom targets
cmake --build . --target qemu
cmake --build . --target qemu-debug
cmake --build . --target qemu-gdb

# Test
ctest
ctest --output-on-failure
ctest -V  # Verbose

# Install
cmake --install .
cmake --install . --prefix /path/to/install

# Clean
cmake --build . --target clean
rm -rf build  # Complete clean

Advantages

• ✅ Cross-platform (Windows, Linux, macOS)
• ✅ IDE integration (CLion, Visual Studio, VS Code)
• ✅ Modern and widely adopted
• ✅ Better dependency tracking
• ✅ Supports multiple generators

Disadvantages

• ❌ More complex than Make
• ❌ Requires CMake to be installed
• ❌ Learning curve for CMakeLists.txt syntax

---

3. Ninja (Fast Build System)

Ninja is designed for speed and is often used with CMake.

Build Commands

# Configure with Ninja generator
mkdir build && cd build
cmake -G Ninja ..

# Build (much faster than Make)
ninja

# Build specific targets
ninja bootloader_efi
ninja kernel_bin
ninja image
ninja qemu

# Clean
ninja clean

Advantages

• ✅ Very fast - optimized for speed
• ✅ Better parallelization than Make
• ✅ Accurate dependency tracking
• ✅ Clean output format
• ✅ Works great with CMake

Disadvantages

• ❌ Requires Ninja to be installed
• ❌ Less familiar than Make
• ❌ Requires CMake to generate build files

---

4. Conan (Package Manager + Build System)

Conan manages dependencies and integrates with CMake.

Setup

# Install Conan (first time only)
pip install conan

# Initialize Conan profile (first time only)
conan profile detect --force

Build Commands

# Create build directory
mkdir build && cd build

# Install dependencies (currently none, but ready for future)
conan install .. --build=missing

# Alternative: Install with specific settings
conan install .. --build=missing -s build_type=Debug
conan install .. --build=missing -s build_type=Release

# Configure with Conan-generated toolchain
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake

# Build
cmake --build .

# Or use Conan to build directly
cd ..
conan build . --build-folder=build

Advantages

• ✅ Dependency management (for future QT6, Mesa, etc.)
• ✅ Reproducible builds
• ✅ Version management
• ✅ Cross-platform package management
• ✅ Integration with CMake and other build systems

Disadvantages

• ❌ Requires Python and Conan
• ❌ Additional complexity
• ❌ Currently overkill (we have no dependencies yet)
• ❌ Learning curve

---

Which Build System Should I Use?

For Quick Development

Use: Make or CMake + Ninja

# Make - simplest
make all && make qemu

# Or Ninja - fastest
cd build-ninja && ninja && ninja qemu

For IDE Integration

Use: CMake

• Works with CLion, Visual Studio Code, Visual Studio
• Configure your IDE to use the CMakeLists.txt

For CI/CD

Use: Make or CMake

# GitHub Actions, GitLab CI, etc.
make all && make test

# Or with CMake
cmake -B build -G Ninja
cmake --build build
ctest --test-dir build

For Cross-Platform Development

Use: CMake + Ninja

# Works on Linux, macOS, Windows
cmake -G Ninja -B build
cmake --build build

For Projects with Dependencies (Future)

Use: Conan + CMake

# When we add QT6, Mesa RADV, etc.
mkdir build && cd build
conan install .. --build=missing
cmake .. -DCMAKE_TOOLCHAIN_FILE=../build/Release/generators/conan_toolchain.cmake
cmake --build .

---

File Structure

MetalOS/
├── Makefile                  # Traditional Make build
├── CMakeLists.txt            # Root CMake configuration
├── conanfile.py              # Conan package definition
├── conanfile.txt             # Simple Conan configuration
├── bootloader/
│   ├── Makefile              # Bootloader Make build
│   └── CMakeLists.txt        # Bootloader CMake build
├── kernel/
│   ├── Makefile              # Kernel Make build
│   └── CMakeLists.txt        # Kernel CMake build
└── tests/
    ├── Makefile              # Tests Make build
    └── CMakeLists.txt        # Tests CMake build

---

Common Build Options

CMake Options

# Enable/disable components
-DBUILD_BOOTLOADER=ON/OFF
-DBUILD_KERNEL=ON/OFF
-DBUILD_TESTS=ON/OFF

# Build type
-DCMAKE_BUILD_TYPE=Debug
-DCMAKE_BUILD_TYPE=Release
-DCMAKE_BUILD_TYPE=RelWithDebInfo

# Compiler
-DCMAKE_C_COMPILER=/usr/bin/gcc
-DCMAKE_CXX_COMPILER=/usr/bin/g++

# Install prefix
-DCMAKE_INSTALL_PREFIX=/opt/metalos

Make Options

# Display mode for QEMU
QEMU_DISPLAY=gtk
QEMU_DISPLAY=sdl
QEMU_DISPLAY=none

# Verbose output
V=1
VERBOSE=1

---

Troubleshooting

CMake: Ninja not found

# Ubuntu/Debian
sudo apt-get install ninja-build

# macOS
brew install ninja

# Arch Linux
sudo pacman -S ninja

CMake: OVMF not found

# Ubuntu/Debian
sudo apt-get install ovmf

# Arch Linux
sudo pacman -S edk2-ovmf

# Or specify manually
cmake .. -DOVMF_FIRMWARE=/path/to/OVMF.fd

Conan: Profile not found

# Detect default profile
conan profile detect --force

# Create custom profile
conan profile show default > myprofile
# Edit myprofile as needed
conan install .. --profile=myprofile

---

Performance Comparison

Build time for clean build (approximate):

Build System	Time	Notes
Make	~2s	Single-threaded by default
Make -j8	~1s	With 8 parallel jobs
CMake + Make	~2s	Same as Make
CMake + Ninja	~0.5s	Fastest option
Conan + CMake	~3s	Additional dependency resolution

Times measured on a typical development machine. Your results may vary.

---

Future Plans

As MetalOS grows and adds dependencies (QT6, Mesa RADV), we recommend:

1. Development: CMake + Ninja (fastest iteration)
2. Dependency Management: Conan (when dependencies are added)
3. CI/CD: Keep Make for simplicity, or migrate to CMake
4. Distribution: Create Conan packages for easy installation

---

Getting Help

• Check docs/BUILD.md for detailed build instructions
• See docs/DEVELOPMENT.md for development workflow
• Read individual Makefiles and CMakeLists.txt for specifics
• Check conanfile.py comments for dependency information

---

Note: All build systems produce identical outputs. Choose based on your workflow and preferences!