Add comprehensive documentation for custom Conan repository (KernelCenter)

Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
2026-04-24 13:45:02 +00:00 · 2025-12-28 23:24:03 +00:00
parent f8318fcf61
commit ffb0bc7748
4 changed files with 432 additions and 0 deletions
--- 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
--- 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

 ```
--- 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
--- a/docs/CONAN.md
+++ 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 <package>/<version>@<user>/<channel> -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 <name> <url>
+
+# List remotes
+conan remote list
+
+# Remove remote
+conan remote remove <name>
+
+# Enable/disable remote
+conan remote enable <name>
+conan remote disable <name>
+```
+
+### Profile Management
+
+```bash
+# Detect system profile
+conan profile detect --force
+
+# Show profile
+conan profile show <name>
+
+# List profiles
+conan profile list
+
+# Create/edit custom profile
+conan profile new <name> --detect
+```
+
+### Package Management
+
+```bash
+# Search packages
+conan search <pattern>
+conan search <pattern> -r=<remote>
+
+# Get package info
+conan inspect <package>
+
+# Install package
+conan install <package>
+
+# Remove package from cache
+conan remove <package>
+```
+
+### Build Commands
+
+```bash
+# Install dependencies
+conan install <path> --build=missing
+
+# Create package
+conan create <path>
+
+# Export recipe
+conan export <path> <user>/<channel>
+```
+
+## 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 "<package>/*" -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