From f4a0b3299889ca629493c99e830c4e29d67df7a2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 28 Dec 2025 20:57:33 +0000 Subject: [PATCH] Update BUILD.md and BUILD_SYSTEMS.md to remove Makefile references Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- docs/BUILD.md | 60 ++++++++++++----------- docs/BUILD_SYSTEMS.md | 109 ++++++++++++++---------------------------- 2 files changed, 67 insertions(+), 102 deletions(-) diff --git a/docs/BUILD.md b/docs/BUILD.md index 518ea52..19660e8 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -21,10 +21,12 @@ The easiest way to build MetalOS is using Docker, which provides a pre-configure ./scripts/docker-run.sh scripts/setup-deps.sh # 3. Build MetalOS -./scripts/docker-run.sh make all +mkdir build && cd build +cmake .. +cmake --build . # 4. Test in QEMU (headless mode) -./scripts/docker-run.sh make qemu +cmake --build . --target qemu # 5. Optional: Interactive shell in container ./scripts/docker-run.sh /bin/bash @@ -33,7 +35,7 @@ The easiest way to build MetalOS is using Docker, which provides a pre-configure ### What's Included in Docker The Docker image includes: -- **Build tools**: GCC, NASM, Make, CMake, Meson +- **Build tools**: GCC, NASM, CMake, Meson - **QEMU**: For testing with UEFI firmware - **OVMF**: UEFI firmware for QEMU - **Dependency management**: Scripts to download AMD firmware, Mesa RADV, QT6 @@ -127,11 +129,15 @@ This produces `kernel/metalos.bin` - the kernel binary. ## Creating Bootable Image ```bash -# From repository root -make image +# From repository root, if you haven't already +mkdir build && cd build +cmake .. + +# Create the bootable image +cmake --build . --target image ``` -This creates `build/metalos.img` - a bootable disk image containing: +This creates `build/build/metalos.img` - a bootable disk image containing: - EFI System Partition with bootloader - Kernel binary - Any required data files @@ -146,41 +152,33 @@ Ensure QEMU and OVMF are installed: ```bash # Ubuntu/Debian -sudo apt-get install qemu-system-x86 ovmf mtools +sudo apt-get install qemu-system-x86 ovmf mtools cmake # Arch Linux -sudo pacman -S qemu-full edk2-ovmf mtools +sudo pacman -S qemu-full edk2-ovmf mtools cmake # Fedora -sudo dnf install qemu-system-x86 edk2-ovmf mtools +sudo dnf install qemu-system-x86 edk2-ovmf mtools cmake ``` ### Boot MetalOS in QEMU ```bash -make qemu +cd build +cmake --build . --target qemu ``` This will: -1. Build bootloader and kernel (or use placeholders if build fails) +1. Build bootloader and kernel 2. Create a bootable FAT32 disk image with UEFI boot structure 3. Launch QEMU with OVMF UEFI firmware in headless mode -4. Boot the system (will drop to UEFI shell until bootloader is complete) - -**Display Options**: By default, QEMU runs in headless mode (no graphics). To use graphical display: - -```bash -# Use GTK display (if available) -make qemu QEMU_DISPLAY=gtk - -# Use SDL display (if available) -make qemu QEMU_DISPLAY=sdl -``` +4. Boot the system ### Boot with Debug Output ```bash -make qemu-debug +cd build +cmake --build . --target qemu-debug ``` This includes CPU interrupt and reset debugging output. @@ -191,7 +189,8 @@ For debugging with GDB: ```bash # Terminal 1 - Start QEMU with GDB server -make qemu-gdb +cd build +cmake --build . --target qemu-gdb # Terminal 2 - Connect GDB gdb kernel/metalos.bin @@ -206,7 +205,8 @@ QEMU will wait for GDB connection before starting execution. To verify QEMU and OVMF are properly installed without needing a bootable OS image: ```bash -make qemu-uefi-test +cd build +cmake --build . --target qemu-uefi-test ``` This boots directly to the UEFI shell, confirming your QEMU+OVMF setup works correctly. @@ -292,10 +292,14 @@ ENABLE_SERIAL ?= 1 ```bash # Clean all build artifacts -make clean +cd build +cmake --build . --target clean -# Clean everything including dependencies -make distclean +# Or remove the build directory entirely +cd .. +rm -rf build +mkdir build && cd build +cmake .. ``` ## Troubleshooting diff --git a/docs/BUILD_SYSTEMS.md b/docs/BUILD_SYSTEMS.md index 33b9a3a..5cedd5f 100644 --- a/docs/BUILD_SYSTEMS.md +++ b/docs/BUILD_SYSTEMS.md @@ -1,21 +1,15 @@ # MetalOS Build Systems Guide -MetalOS supports multiple build systems to accommodate different developer preferences and workflows. +MetalOS uses **CMake** as its primary build system, which can be used with different build backends for different workflows. ## Quick Start -### Using Make (Traditional) -```bash -make all # Build everything -make qemu # Test in QEMU -make clean # Clean build artifacts -``` - -### Using CMake + Make +### Using CMake (Default) ```bash mkdir build && cd build cmake .. cmake --build . +cmake --build . --target qemu # Test in QEMU ``` ### Using CMake + Ninja (Fastest) @@ -23,6 +17,7 @@ cmake --build . mkdir build && cd build cmake -G Ninja .. ninja +ninja qemu # Test in QEMU ``` ### Using Conan + CMake @@ -35,89 +30,38 @@ 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 | +| 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. Make (Traditional Build System) +### 1. CMake (Primary Build System) -The original build system using GNU Make. +CMake is the primary build system for MetalOS, providing cross-platform support and modern features. #### 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) +# Configure and build 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 +# Create bootable image +make 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 @@ -133,6 +77,23 @@ 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)