2026-01-14 02:59:52 +00:00
|
|
|
# Build System Documentation\n\nThis document provides comprehensive documentation for the provisioning project's build system, including the complete Makefile reference with 40+\ntargets, build tools, compilation instructions, and troubleshooting.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Quick Start](#quick-start)\n3. [Makefile Reference](#makefile-reference)\n4. [Build Tools](#build-tools)\n5. [Cross-Platform Compilation](#cross-platform-compilation)\n6. [Dependency Management](#dependency-management)\n7. [Troubleshooting](#troubleshooting)\n8. [CI/CD Integration](#cicd-integration)\n\n## Overview\n\nThe build system is a comprehensive, Makefile-based solution that orchestrates:\n\n- **Rust compilation**: Platform binaries (orchestrator, control-center, etc.)\n- **Nushell bundling**: Core libraries and CLI tools\n- **Nickel validation**: Configuration schema validation\n- **Distribution generation**: Multi-platform packages\n- **Release management**: Automated release pipelines\n- **Documentation generation**: API and user documentation\n\n**Location**: `/src/tools/`\n**Main entry point**: `/src/tools/Makefile`\n\n## Quick Start\n\n```{$detected_lang}\n# Navigate to build system\ncd src/tools\n\n# View all available targets\nmake help\n\n# Complete build and package\nmake all\n\n# Development build (quick)\nmake dev-build\n\n# Build for specific platform\nmake linux\nmake macos\nmake windows\n\n# Clean everything\nmake clean\n\n# Check build system status\nmake status\n```\n\n## Makefile Reference\n\n### Build Configuration\n\n**Variables**:\n\n```{$detected_lang}\n# Project metadata\nPROJECT_NAME := provisioning\nVERSION := $(git describe --tags --always --dirty)\nBUILD_TIME := $(date -u +"%Y-%m-%dT%H:%M:%SZ")\n\n# Build configuration\nRUST_TARGET := x86_64-unknown-linux-gnu\nBUILD_MODE := release\nPLATFORMS := linux-amd64,macos-amd64,windows-amd64\nVARIANTS := complete,minimal\n\n# Flags\nVERBOSE := false\nDRY_RUN := false\nPARALLEL := true\n```\n\n### Build Targets\n\n#### Primary Build Targets\n\n**`make all`** - Complete build, package, and test\n\n- Runs: `clean build-all package-all test-dist`\n- Use for: Production releases, complete validation\n\n**`make build-all`** - Build all components\n\n- Runs: `build-platform build-core validate-nickel`\n- Use for: Complete system compilation\n\n**`make build-platform`** - Build platform binaries for all targets\n\n```{$detected_lang}\nmake build-platform\n# Equivalent to:\nnu tools/build/compile-platform.nu \\n --target x86_64-unknown-linux-gnu \\n --release \\n --output-dir dist/platform \\n --verbose=false\n```\n\n**`make build-core`** - Bundle core Nushell libraries\n\n```{$detected_lang}\nmake build-core\n# Equivalent to:\nnu tools/build/bundle-core.nu \\n --output-dir dist/core \\n --config-dir dist/config \\n --validate \\n --exclude-dev\n```\n\n**`make validate-nickel`** - Validate and compile Nickel schemas\n\n```{$detected_lang}\nmake validate-nickel\n# Equivalent to:\nnu tools/build/validate-nickel.nu \\n --output-dir dist/schemas \\n --format-code \\n --check-dependencies\n```\n\n**`make build-cross`** - Cross-compile for multiple platforms\n\n- Builds for all platforms in `PLATFORMS` variable\n- Parallel execution support\n- Failure handling for each platform\n\n#### Package Targets\n\n**`make package-all`** - Create all distribution packages\n\n- Runs: `dist-generate package-binaries package-containers`\n\n**`make dist-generate`** - Generate complete distributions\n\n```{$detected_lang}\nmake dist-generate\n# Advanced usage:\nmake dist-generate PLATFORMS=linux-amd64,macos-amd64 VARIANTS=complete\n```\n\n**`make package-binaries`** - Package binaries for distribution\n\n- Creates platform-specific archives\n- Strips debug symbols\n- Generates checksums\n\n**`make package-containers`** - Build container images\n\n- Multi-platform container builds\n- Optimized layers and caching\n- Version tagging\n\n**`make create-archives`** - Create distribution archives\n\n- TAR and ZIP formats\n- Platform-specific and uni
|
