From ffb0bc7748f2259552a4d41ba3ebea913c0521dd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 28 Dec 2025 23:24:03 +0000 Subject: [PATCH] Add comprehensive documentation for custom Conan repository (KernelCenter) Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- README.md | 6 + deps/README.md | 9 ++ docs/BUILD.md | 30 ++++ docs/CONAN.md | 387 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 432 insertions(+) create mode 100644 docs/CONAN.md diff --git a/README.md b/README.md index aea37e9..ea11a26 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,9 @@ ninja pip3 install conan conan profile detect --force +# Optional: Add MetalOS custom Conan repository (KernelCenter) +conan remote add kernelcenter https://johndoe6345789.github.io/kernelcenter/ + # Install dependencies and generate toolchain (Release build by default) conan install . --build=missing @@ -125,6 +128,8 @@ ninja # cmake .. -DCMAKE_TOOLCHAIN_FILE=../build/Debug/generators/conan_toolchain.cmake -G Ninja ``` +**Custom Conan Repository**: MetalOS provides [KernelCenter](https://johndoe6345789.github.io/kernelcenter/), a custom Conan repository with MetalOS-specific packages. See [docs/CONAN.md](docs/CONAN.md) for details. + ### Docker Build (Recommended for Consistency) The easiest way to build MetalOS with all dependencies: @@ -165,6 +170,7 @@ See [deps/README.md](deps/README.md) for detailed dependency management instruct - [MINIMALISM.md](docs/MINIMALISM.md) - Extreme minimalism philosophy - [ROADMAP.md](docs/ROADMAP.md) - Development phases and milestones - [BUILD.md](docs/BUILD.md) - Build system and toolchain +- [CONAN.md](docs/CONAN.md) - Conan package manager and custom repository - [DEVELOPMENT.md](docs/DEVELOPMENT.md) - Development environment setup - [STATUS.md](docs/STATUS.md) - Current implementation status - [TESTING.md](docs/TESTING.md) - Unit tests and QEMU testing diff --git a/deps/README.md b/deps/README.md index 072c569..6fd34e7 100644 --- a/deps/README.md +++ b/deps/README.md @@ -2,6 +2,15 @@ This directory contains third-party dependencies managed in-house for MetalOS development. +## Dependency Management Options + +MetalOS provides two approaches for dependency management: + +1. **In-house dependencies** (this directory) - Manual download and setup of dependencies +2. **Conan package manager** - Automated dependency management via [KernelCenter](https://johndoe6345789.github.io/kernelcenter/) + +For Conan-based dependency management, see [docs/CONAN.md](../docs/CONAN.md). + ## Directory Structure ``` diff --git a/docs/BUILD.md b/docs/BUILD.md index f28521e..cf155f9 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -122,8 +122,38 @@ brew install nasm qemu x86_64-elf-gcc x86_64-elf-binutils cmake python3 # Install Conan (optional but recommended) pip3 install conan conan profile detect --force + +# Add MetalOS custom Conan repository (optional) +conan remote add kernelcenter https://johndoe6345789.github.io/kernelcenter/ ``` +### Custom Conan Repository (KernelCenter) + +MetalOS provides a **custom Conan repository** that hosts MetalOS-specific packages and optimized configurations for minimal OS development. + +**Repository URL**: https://johndoe6345789.github.io/kernelcenter/ + +To use the custom repository: + +```bash +# Add the KernelCenter remote +conan remote add kernelcenter https://johndoe6345789.github.io/kernelcenter/ + +# Verify it was added +conan remote list + +# View repository information +curl https://johndoe6345789.github.io/kernelcenter/ +``` + +The KernelCenter repository provides: +- Pre-built MetalOS components +- Custom package recipes for freestanding environments +- GPU firmware packages +- Future Mesa RADV and QT6 minimal builds + +For detailed Conan configuration and usage, see [docs/CONAN.md](CONAN.md). + ## Building the Bootloader ```bash diff --git a/docs/CONAN.md b/docs/CONAN.md new file mode 100644 index 0000000..064c63a --- /dev/null +++ b/docs/CONAN.md @@ -0,0 +1,387 @@ +# Conan Package Manager Integration + +MetalOS uses [Conan](https://conan.io/) as a package manager to manage C/C++ dependencies and build configurations. + +## Overview + +Conan provides: +- **Dependency management** - Handle third-party libraries and tools +- **Build configuration** - Generate CMake toolchains for reproducible builds +- **Package distribution** - Share MetalOS components as Conan packages +- **Cross-platform builds** - Consistent builds across different environments + +## Custom Conan Repository + +MetalOS has a **custom Conan repository (KernelCenter)** that hosts MetalOS-specific packages and configurations: + +**Repository URL**: https://johndoe6345789.github.io/kernelcenter/ + +This custom repository provides: +- Pre-built MetalOS components and dependencies +- Custom package recipes optimized for minimal OS development +- Freestanding environment configurations +- GPU firmware packages and utilities + +### Adding the Custom Repository + +To use the custom Conan repository with your MetalOS development: + +```bash +# Add the KernelCenter remote +conan remote add kernelcenter https://johndoe6345789.github.io/kernelcenter/ + +# List your configured remotes to verify +conan remote list + +# Set KernelCenter as the primary remote (optional) +conan remote enable kernelcenter +``` + +### Using Packages from KernelCenter + +Once the remote is added, you can install packages from it: + +```bash +# Search for available packages +conan search "*" -r=kernelcenter + +# Install specific packages +conan install /@/ -r=kernelcenter +``` + +### Repository Information + +You can view detailed information about the KernelCenter repository: + +```bash +# Fetch repository information +curl https://johndoe6345789.github.io/kernelcenter/ +# or +wget -q -O - https://johndoe6345789.github.io/kernelcenter/ +``` + +The repository page contains: +- Available package list +- Package versions and compatibility +- Installation instructions +- Repository metadata and configuration + +## Standard Conan Workflow + +### Installation + +```bash +# Install Conan via pip +pip3 install conan + +# Verify installation +conan --version + +# Create default profile +conan profile detect --force +``` + +### Profile Configuration + +MetalOS includes a custom Conan profile at `conan_profile`: + +```bash +# View the MetalOS profile +cat conan_profile + +# Use the custom profile +conan install . --profile=conan_profile --build=missing +``` + +The profile configures: +- Target architecture (x86_64) +- Compiler settings (GCC/Clang) +- Build type (Release/Debug) +- OS settings (Linux freestanding) + +### Installing Dependencies + +```bash +# Install all MetalOS dependencies +conan install . --build=missing + +# Install for specific build type +conan install . --build=missing -s build_type=Debug +conan install . --build=missing -s build_type=Release +``` + +This generates: +- `build/Release/generators/conan_toolchain.cmake` - CMake toolchain file +- `build/Release/generators/CMakeDeps.cmake` - CMake dependency files +- Build configuration files + +### Building with Conan + +```bash +# 1. Install dependencies +conan install . --build=missing + +# 2. Configure CMake with Conan toolchain +mkdir build && cd build +cmake .. -DCMAKE_TOOLCHAIN_FILE=../build/Release/generators/conan_toolchain.cmake + +# 3. Build +cmake --build . +``` + +Or with Ninja: + +```bash +cmake .. -DCMAKE_TOOLCHAIN_FILE=../build/Release/generators/conan_toolchain.cmake -G Ninja +ninja +``` + +## Conan Package Definition + +The `conanfile.py` defines MetalOS as a Conan package: + +```python +class MetalOSConan(ConanFile): + name = "metalos" + version = "0.1.0" + + settings = "os", "compiler", "build_type", "arch" + options = { + "build_bootloader": [True, False], + "build_kernel": [True, False], + "build_tests": [True, False], + } +``` + +### Package Options + +Configure MetalOS components: + +```bash +# Build only the kernel +conan install . -o build_bootloader=False -o build_tests=False + +# Build everything +conan install . -o build_bootloader=True -o build_kernel=True -o build_tests=True +``` + +## Testing Conan Integration + +Verify that Conan is properly configured: + +```bash +# Run the integration test +./scripts/test-conan-build.sh +``` + +This script: +1. Checks Conan installation +2. Verifies profile configuration +3. Installs dependencies +4. Generates toolchain +5. Tests CMake configuration +6. Validates the integration + +## Future Dependencies + +MetalOS currently has no external dependencies (freestanding OS), but future phases will integrate: + +### Phase 4 - GPU Support +```python +requires = ( + "mesa-radv/24.0.0@kernelcenter/stable", + "amd-gpu-firmware/navi23@kernelcenter/stable", +) +``` + +### Phase 7 - QT6 Integration +```python +requires = ( + "qt/6.5.3@kernelcenter/minimal", # Minimal static build +) +``` + +These packages will be available from the KernelCenter repository. + +## Conan Commands Reference + +### Remote Management + +```bash +# Add remote +conan remote add + +# List remotes +conan remote list + +# Remove remote +conan remote remove + +# Enable/disable remote +conan remote enable +conan remote disable +``` + +### Profile Management + +```bash +# Detect system profile +conan profile detect --force + +# Show profile +conan profile show + +# List profiles +conan profile list + +# Create/edit custom profile +conan profile new --detect +``` + +### Package Management + +```bash +# Search packages +conan search +conan search -r= + +# Get package info +conan inspect + +# Install package +conan install + +# Remove package from cache +conan remove +``` + +### Build Commands + +```bash +# Install dependencies +conan install --build=missing + +# Create package +conan create + +# Export recipe +conan export / +``` + +## Advanced Configuration + +### Custom Build Types + +```bash +# Create custom build type profile +conan profile new metalos-optimized --detect + +# Edit profile to add custom settings +conan profile update settings.compiler.optimization=aggressive metalos-optimized +``` + +### Multiple Configurations + +```bash +# Generate configurations for multiple build types +conan install . -s build_type=Debug --build=missing +conan install . -s build_type=Release --build=missing +conan install . -s build_type=RelWithDebInfo --build=missing +``` + +### Offline Development + +```bash +# Download all dependencies once +conan install . --build=missing + +# Later builds use cached packages (no network needed) +conan install . +``` + +## Troubleshooting + +### Conan Not Found + +```bash +# Reinstall Conan +pip3 install --upgrade conan + +# Add to PATH if needed +export PATH="$HOME/.local/bin:$PATH" +``` + +### Profile Issues + +```bash +# Reset profile +rm -rf ~/.conan2/profiles/default +conan profile detect --force + +# Or manually create profile +conan profile new default --detect +``` + +### Cache Issues + +```bash +# Clear Conan cache +conan remove "*" -c + +# Or remove specific package +conan remove "/*" -c +``` + +### Remote Connection Issues + +```bash +# Test remote connectivity +conan search "*" -r=kernelcenter + +# Check remote configuration +conan remote list + +# Re-add remote if needed +conan remote remove kernelcenter +conan remote add kernelcenter https://johndoe6345789.github.io/kernelcenter/ +``` + +### Build Generation Issues + +```bash +# Clean and regenerate +rm -rf build CMakeUserPresets.json +conan install . --build=missing + +# Verify toolchain exists +ls -la build/Release/generators/conan_toolchain.cmake +``` + +## Integration with CI/CD + +MetalOS Docker environment includes Conan for consistent CI builds: + +```dockerfile +# Install Conan in Docker +RUN pip3 install conan && conan profile detect --force + +# Add custom remote +RUN conan remote add kernelcenter https://johndoe6345789.github.io/kernelcenter/ +``` + +This ensures all builds (local and CI) use identical dependency versions. + +## Resources + +- **Conan Documentation**: https://docs.conan.io/ +- **KernelCenter Repository**: https://johndoe6345789.github.io/kernelcenter/ +- **MetalOS Conan Profile**: `conan_profile` in repository root +- **MetalOS Package Definition**: `conanfile.py` in repository root +- **Integration Test**: `scripts/test-conan-build.sh` + +## See Also + +- [BUILD.md](BUILD.md) - Building MetalOS +- [DEVELOPMENT.md](DEVELOPMENT.md) - Development workflow +- [deps/README.md](../deps/README.md) - Dependency management +- [DOCKER.md](DOCKER.md) - Docker build environment