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)
```bash
make all      # Build everything
make qemu     # Test in QEMU
make clean    # Clean build artifacts
```

### Using CMake + Make
```bash
mkdir build && cd build
cmake ..
cmake --build .
```

### Using CMake + Ninja (Fastest)
```bash
mkdir build && cd build
cmake -G Ninja ..
ninja
```

### Using Conan + CMake
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Install Conan (first time only)
pip install conan

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

#### Build Commands
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# Works on Linux, macOS, Windows
cmake -G Ninja -B build
cmake --build build
```

### For Projects with Dependencies (Future)
**Use: Conan + CMake**
```bash
# 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
```bash
# 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
```bash
# Display mode for QEMU
QEMU_DISPLAY=gtk
QEMU_DISPLAY=sdl
QEMU_DISPLAY=none

# Verbose output
V=1
VERBOSE=1
```

---

## Troubleshooting

### CMake: Ninja not found
```bash
# Ubuntu/Debian
sudo apt-get install ninja-build

# macOS
brew install ninja

# Arch Linux
sudo pacman -S ninja
```

### CMake: OVMF not found
```bash
# 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
```bash
# 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!