MetalOS/docs/BUILD_SYSTEMS.md

MetalOS Build Systems Guide

MetalOS uses CMake as its primary build system, which can be used with different build backends for different workflows.

Quick Start

Using CMake (Default)

mkdir build && cd build
cmake ..
cmake --build .
cmake --build . --target qemu  # Test in QEMU

Using CMake + Ninja (Fastest)

mkdir build && cd build
cmake -G Ninja ..
ninja
ninja qemu  # Test in QEMU

Using Conan + CMake

# First time: install Conan and setup profile
pip3 install conan
conan profile detect --force

# Install dependencies (generates toolchain files - Release by default)
conan install . --build=missing

# Configure with Conan toolchain
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=../build/Release/generators/conan_toolchain.cmake

# Build
cmake --build .

# Note: The toolchain path matches the build type:
# - Release (default): build/Release/generators/conan_toolchain.cmake
# - Debug: build/Debug/generators/conan_toolchain.cmake (use -s build_type=Debug)

Build System Comparison

Build Backend	Speed	Features	Best For
Make (default)	Medium	Cross-platform, standard	General use, CI/CD
Ninja	Fast	Parallel builds	Development, large projects
Conan	Medium	Dependency management	Projects with external deps

Detailed Usage

1. CMake (Primary Build System)

CMake is the primary build system for MetalOS, providing cross-platform support and modern features.

Build Commands

# Configure and build
mkdir build && cd build
cmake ..
cmake --build .

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

# Create bootable image
cmake --build . --target image

# Run in QEMU
cmake --build . --target qemu          # Headless mode
cmake --build . --target qemu-debug    # With debug output
cmake --build . --target qemu-gdb      # With GDB server
cmake --build . --target qemu-uefi-test # Test UEFI setup

# 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, VSCode, Visual Studio)
• ✅ Modern dependency management
• ✅ Better parallel build support
• ✅ Generates compile_commands.json for IDEs

Disadvantages

• ❌ Requires cmake installation
• ❌ Slightly more complex setup

---

2. Ninja (Fast Build Backend)

Ninja is a fast build backend that can be used with CMake for faster incremental builds.

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

# Install dependencies (generates toolchain in build/<BuildType>/generators/)
# Default is Release build type
conan install . --build=missing

# Alternative: Install with specific build type
conan install . --build=missing -s build_type=Debug    # Generates in build/Debug/generators/
conan install . --build=missing -s build_type=Release  # Generates in build/Release/generators/

# Create build directory and configure with Conan-generated toolchain
# Note: Toolchain path must match the build type used in conan install
mkdir build && cd build

# For Release build (default)
cmake .. -DCMAKE_TOOLCHAIN_FILE=../build/Release/generators/conan_toolchain.cmake

# Or for Debug build
cmake .. -DCMAKE_TOOLCHAIN_FILE=../build/Debug/generators/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
• ✅ Recommended for CI/CD - ensures consistent builds

Disadvantages

• ❌ Requires Python and Conan
• ❌ Additional setup step
• ❌ Learning curve

When to Use

• ✅ CI/CD pipelines (all workflows now use Conan)
• ✅ Production builds requiring reproducibility
• ✅ When adding external dependencies (QT6, Mesa RADV in the future)
• ✅ Cross-platform development needing consistent dependencies

---

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: Conan + CMake (Recommended)

# GitHub Actions, GitLab CI, etc.
# All MetalOS CI workflows now use Conan
conan install . --build=missing
cmake -B build -DCMAKE_TOOLCHAIN_FILE=build/Release/generators/conan_toolchain.cmake
cmake --build build
ctest --test-dir build

Benefits:

• ✅ Reproducible builds across different CI runners
• ✅ Consistent dependency versions
• ✅ Future-proof for when we add dependencies

For Cross-Platform Development

Use: Conan + CMake + Ninja

# Works on Linux, macOS, Windows
conan install . --build=missing
cmake -G Ninja -B build -DCMAKE_TOOLCHAIN_FILE=build/Release/generators/conan_toolchain.cmake
cmake --build build

For Projects with Dependencies (Current & 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!