1094 lines
45 KiB
HTML
1094 lines
45 KiB
HTML
|
<!DOCTYPE HTML>
|
|||
|
|
<html lang="en" class="ayu sidebar-visible" dir="ltr">
|
|||
|
|
<head>
|
|||
|
|
<!-- Book generated using mdBook -->
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<title>Build System - Provisioning Platform Documentation</title>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Custom HTML head -->
|
|||
|
|
|
|||
|
|
<meta name="description" content="Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust">
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|||
|
|
<meta name="theme-color" content="#ffffff">
|
|||
|
|
|
|||
|
|
<link rel="icon" href="../favicon.svg">
|
|||
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|||
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|||
|
|
<link rel="stylesheet" href="../css/general.css">
|
|||
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|||
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|||
|
|
|
|||
|
|
<!-- Fonts -->
|
|||
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|||
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|||
|
|
|
|||
|
|
<!-- Highlight.js Stylesheets -->
|
|||
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
|||
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
|||
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
|||
|
|
|
|||
|
|
<!-- Custom theme stylesheets -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Provide site root and default themes to javascript -->
|
|||
|
|
<script>
|
|||
|
|
const path_to_root = "../";
|
|||
|
|
const default_light_theme = "ayu";
|
|||
|
|
const default_dark_theme = "navy";
|
|||
|
|
</script>
|
|||
|
|
<!-- Start loading toc.js asap -->
|
|||
|
|
<script src="../toc.js"></script>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div id="mdbook-help-container">
|
|||
|
|
<div id="mdbook-help-popup">
|
|||
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|||
|
|
<div>
|
|||
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|||
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|||
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|||
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div id="body-container">
|
|||
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|||
|
|
<script>
|
|||
|
|
try {
|
|||
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|||
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|||
|
|
|
|||
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|||
|
|
}
|
|||
|
|
} catch (e) { }
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|||
|
|
<script>
|
|||
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|||
|
|
let theme;
|
|||
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|||
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|||
|
|
const html = document.documentElement;
|
|||
|
|
html.classList.remove('ayu')
|
|||
|
|
html.classList.add(theme);
|
|||
|
|
html.classList.add("js");
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|||
|
|
|
|||
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|||
|
|
<script>
|
|||
|
|
let sidebar = null;
|
|||
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|||
|
|
if (document.body.clientWidth >= 1080) {
|
|||
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|||
|
|
sidebar = sidebar || 'visible';
|
|||
|
|
} else {
|
|||
|
|
sidebar = 'hidden';
|
|||
|
|
}
|
|||
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|||
|
|
html.classList.remove('sidebar-visible');
|
|||
|
|
html.classList.add("sidebar-" + sidebar);
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|||
|
|
<!-- populated by js -->
|
|||
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|||
|
|
<noscript>
|
|||
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|||
|
|
</noscript>
|
|||
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|||
|
|
<div class="sidebar-resize-indicator"></div>
|
|||
|
|
</div>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
<div id="page-wrapper" class="page-wrapper">
|
|||
|
|
|
|||
|
|
<div class="page">
|
|||
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|||
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|||
|
|
<div class="left-buttons">
|
|||
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|||
|
|
<i class="fa fa-bars"></i>
|
|||
|
|
</label>
|
|||
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|||
|
|
<i class="fa fa-paint-brush"></i>
|
|||
|
|
</button>
|
|||
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|||
|
|
</ul>
|
|||
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|||
|
|
<i class="fa fa-search"></i>
|
|||
|
|
</button>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<h1 class="menu-title">Provisioning Platform Documentation</h1>
|
|||
|
|
|
|||
|
|
<div class="right-buttons">
|
|||
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|||
|
|
<i id="print-button" class="fa fa-print"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/provisioning/provisioning-platform" title="Git repository" aria-label="Git repository">
|
|||
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/development/build-system.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|||
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div id="search-wrapper" class="hidden">
|
|||
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|||
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|||
|
|
</form>
|
|||
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|||
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|||
|
|
<ul id="searchresults">
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|||
|
|
<script>
|
|||
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|||
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|||
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|||
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|||
|
|
});
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<div id="content" class="content">
|
|||
|
|
<main>
|
|||
|
|
<h1 id="build-system-documentation"><a class="header" href="#build-system-documentation">Build System Documentation</a></h1>
|
|||
|
|
<p>This document provides comprehensive documentation for the provisioning project’s build system, including the complete Makefile reference with 40+ targets, build tools, compilation instructions, and troubleshooting.</p>
|
|||
|
|
<h2 id="table-of-contents"><a class="header" href="#table-of-contents">Table of Contents</a></h2>
|
|||
|
|
<ol>
|
|||
|
|
<li><a href="#overview">Overview</a></li>
|
|||
|
|
<li><a href="#quick-start">Quick Start</a></li>
|
|||
|
|
<li><a href="#makefile-reference">Makefile Reference</a></li>
|
|||
|
|
<li><a href="#build-tools">Build Tools</a></li>
|
|||
|
|
<li><a href="#cross-platform-compilation">Cross-Platform Compilation</a></li>
|
|||
|
|
<li><a href="#dependency-management">Dependency Management</a></li>
|
|||
|
|
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
|||
|
|
<li><a href="#cicd-integration">CI/CD Integration</a></li>
|
|||
|
|
</ol>
|
|||
|
|
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
|||
|
|
<p>The build system is a comprehensive, Makefile-based solution that orchestrates:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Rust compilation</strong>: Platform binaries (orchestrator, control-center, etc.)</li>
|
|||
|
|
<li><strong>Nushell bundling</strong>: Core libraries and CLI tools</li>
|
|||
|
|
<li><strong>KCL validation</strong>: Configuration schema validation</li>
|
|||
|
|
<li><strong>Distribution generation</strong>: Multi-platform packages</li>
|
|||
|
|
<li><strong>Release management</strong>: Automated release pipelines</li>
|
|||
|
|
<li><strong>Documentation generation</strong>: API and user documentation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Location</strong>: <code>/src/tools/</code>
|
|||
|
|
<strong>Main entry point</strong>: <code>/src/tools/Makefile</code></p>
|
|||
|
|
<h2 id="quick-start"><a class="header" href="#quick-start">Quick Start</a></h2>
|
|||
|
|
<pre><code class="language-bash"># Navigate to build system
|
|||
|
|
cd src/tools
|
|||
|
|
|
|||
|
|
# View all available targets
|
|||
|
|
make help
|
|||
|
|
|
|||
|
|
# Complete build and package
|
|||
|
|
make all
|
|||
|
|
|
|||
|
|
# Development build (quick)
|
|||
|
|
make dev-build
|
|||
|
|
|
|||
|
|
# Build for specific platform
|
|||
|
|
make linux
|
|||
|
|
make macos
|
|||
|
|
make windows
|
|||
|
|
|
|||
|
|
# Clean everything
|
|||
|
|
make clean
|
|||
|
|
|
|||
|
|
# Check build system status
|
|||
|
|
make status
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="makefile-reference"><a class="header" href="#makefile-reference">Makefile Reference</a></h2>
|
|||
|
|
<h3 id="build-configuration"><a class="header" href="#build-configuration">Build Configuration</a></h3>
|
|||
|
|
<p><strong>Variables</strong>:</p>
|
|||
|
|
<pre><code class="language-makefile"># Project metadata
|
|||
|
|
PROJECT_NAME := provisioning
|
|||
|
|
VERSION := $(git describe --tags --always --dirty)
|
|||
|
|
BUILD_TIME := $(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
|||
|
|
|
|||
|
|
# Build configuration
|
|||
|
|
RUST_TARGET := x86_64-unknown-linux-gnu
|
|||
|
|
BUILD_MODE := release
|
|||
|
|
PLATFORMS := linux-amd64,macos-amd64,windows-amd64
|
|||
|
|
VARIANTS := complete,minimal
|
|||
|
|
|
|||
|
|
# Flags
|
|||
|
|
VERBOSE := false
|
|||
|
|
DRY_RUN := false
|
|||
|
|
PARALLEL := true
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="build-targets"><a class="header" href="#build-targets">Build Targets</a></h3>
|
|||
|
|
<h4 id="primary-build-targets"><a class="header" href="#primary-build-targets">Primary Build Targets</a></h4>
|
|||
|
|
<p><strong><code>make all</code></strong> - Complete build, package, and test</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Runs: <code>clean build-all package-all test-dist</code></li>
|
|||
|
|
<li>Use for: Production releases, complete validation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make build-all</code></strong> - Build all components</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Runs: <code>build-platform build-core validate-kcl</code></li>
|
|||
|
|
<li>Use for: Complete system compilation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make build-platform</code></strong> - Build platform binaries for all targets</p>
|
|||
|
|
<pre><code class="language-bash">make build-platform
|
|||
|
|
# Equivalent to:
|
|||
|
|
nu tools/build/compile-platform.nu \
|
|||
|
|
--target x86_64-unknown-linux-gnu \
|
|||
|
|
--release \
|
|||
|
|
--output-dir dist/platform \
|
|||
|
|
--verbose=false
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make build-core</code></strong> - Bundle core Nushell libraries</p>
|
|||
|
|
<pre><code class="language-bash">make build-core
|
|||
|
|
# Equivalent to:
|
|||
|
|
nu tools/build/bundle-core.nu \
|
|||
|
|
--output-dir dist/core \
|
|||
|
|
--config-dir dist/config \
|
|||
|
|
--validate \
|
|||
|
|
--exclude-dev
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make validate-kcl</code></strong> - Validate and compile KCL schemas</p>
|
|||
|
|
<pre><code class="language-bash">make validate-kcl
|
|||
|
|
# Equivalent to:
|
|||
|
|
nu tools/build/validate-kcl.nu \
|
|||
|
|
--output-dir dist/kcl \
|
|||
|
|
--format-code \
|
|||
|
|
--check-dependencies
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make build-cross</code></strong> - Cross-compile for multiple platforms</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Builds for all platforms in <code>PLATFORMS</code> variable</li>
|
|||
|
|
<li>Parallel execution support</li>
|
|||
|
|
<li>Failure handling for each platform</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="package-targets"><a class="header" href="#package-targets">Package Targets</a></h4>
|
|||
|
|
<p><strong><code>make package-all</code></strong> - Create all distribution packages</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Runs: <code>dist-generate package-binaries package-containers</code></li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make dist-generate</code></strong> - Generate complete distributions</p>
|
|||
|
|
<pre><code class="language-bash">make dist-generate
|
|||
|
|
# Advanced usage:
|
|||
|
|
make dist-generate PLATFORMS=linux-amd64,macos-amd64 VARIANTS=complete
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make package-binaries</code></strong> - Package binaries for distribution</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Creates platform-specific archives</li>
|
|||
|
|
<li>Strips debug symbols</li>
|
|||
|
|
<li>Generates checksums</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make package-containers</code></strong> - Build container images</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Multi-platform container builds</li>
|
|||
|
|
<li>Optimized layers and caching</li>
|
|||
|
|
<li>Version tagging</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make create-archives</code></strong> - Create distribution archives</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>TAR and ZIP formats</li>
|
|||
|
|
<li>Platform-specific and universal archives</li>
|
|||
|
|
<li>Compression and checksums</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make create-installers</code></strong> - Create installation packages</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Shell script installers</li>
|
|||
|
|
<li>Platform-specific packages (DEB, RPM, MSI)</li>
|
|||
|
|
<li>Uninstaller creation</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="release-targets"><a class="header" href="#release-targets">Release Targets</a></h4>
|
|||
|
|
<p><strong><code>make release</code></strong> - Create a complete release (requires VERSION)</p>
|
|||
|
|
<pre><code class="language-bash">make release VERSION=2.1.0
|
|||
|
|
</code></pre>
|
|||
|
|
<p>Features:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Automated changelog generation</li>
|
|||
|
|
<li>Git tag creation and push</li>
|
|||
|
|
<li>Artifact upload</li>
|
|||
|
|
<li>Comprehensive validation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make release-draft</code></strong> - Create a draft release</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Create without publishing</li>
|
|||
|
|
<li>Review artifacts before release</li>
|
|||
|
|
<li>Manual approval workflow</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make upload-artifacts</code></strong> - Upload release artifacts</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>GitHub Releases</li>
|
|||
|
|
<li>Container registries</li>
|
|||
|
|
<li>Package repositories</li>
|
|||
|
|
<li>Verification and validation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make notify-release</code></strong> - Send release notifications</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Slack notifications</li>
|
|||
|
|
<li>Discord announcements</li>
|
|||
|
|
<li>Email notifications</li>
|
|||
|
|
<li>Custom webhook support</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make update-registry</code></strong> - Update package manager registries</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Homebrew formula updates</li>
|
|||
|
|
<li>APT repository updates</li>
|
|||
|
|
<li>Custom registry support</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="development-and-testing-targets"><a class="header" href="#development-and-testing-targets">Development and Testing Targets</a></h4>
|
|||
|
|
<p><strong><code>make dev-build</code></strong> - Quick development build</p>
|
|||
|
|
<pre><code class="language-bash">make dev-build
|
|||
|
|
# Fast build with minimal validation
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make test-build</code></strong> - Test build system</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Validates build process</li>
|
|||
|
|
<li>Runs with test configuration</li>
|
|||
|
|
<li>Comprehensive logging</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make test-dist</code></strong> - Test generated distributions</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Validates distribution integrity</li>
|
|||
|
|
<li>Tests installation process</li>
|
|||
|
|
<li>Platform compatibility checks</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make validate-all</code></strong> - Validate all components</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>KCL schema validation</li>
|
|||
|
|
<li>Package validation</li>
|
|||
|
|
<li>Configuration validation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make benchmark</code></strong> - Run build benchmarks</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Times build process</li>
|
|||
|
|
<li>Performance analysis</li>
|
|||
|
|
<li>Resource usage monitoring</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="documentation-targets"><a class="header" href="#documentation-targets">Documentation Targets</a></h4>
|
|||
|
|
<p><strong><code>make docs</code></strong> - Generate documentation</p>
|
|||
|
|
<pre><code class="language-bash">make docs
|
|||
|
|
# Generates API docs, user guides, and examples
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make docs-serve</code></strong> - Generate and serve documentation locally</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Starts local HTTP server on port 8000</li>
|
|||
|
|
<li>Live documentation browsing</li>
|
|||
|
|
<li>Development documentation workflow</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="utility-targets"><a class="header" href="#utility-targets">Utility Targets</a></h4>
|
|||
|
|
<p><strong><code>make clean</code></strong> - Clean all build artifacts</p>
|
|||
|
|
<pre><code class="language-bash">make clean
|
|||
|
|
# Removes all build, distribution, and package directories
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make clean-dist</code></strong> - Clean only distribution artifacts</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Preserves build cache</li>
|
|||
|
|
<li>Removes distribution packages</li>
|
|||
|
|
<li>Faster cleanup option</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make install</code></strong> - Install the built system locally</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Requires distribution to be built</li>
|
|||
|
|
<li>Installs to system directories</li>
|
|||
|
|
<li>Creates uninstaller</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make uninstall</code></strong> - Uninstall the system</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Removes system installation</li>
|
|||
|
|
<li>Cleans configuration</li>
|
|||
|
|
<li>Removes service files</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make status</code></strong> - Show build system status</p>
|
|||
|
|
<pre><code class="language-bash">make status
|
|||
|
|
# Output:
|
|||
|
|
# Build System Status
|
|||
|
|
# ===================
|
|||
|
|
# Project: provisioning
|
|||
|
|
# Version: v2.1.0-5-g1234567
|
|||
|
|
# Git Commit: 1234567890abcdef
|
|||
|
|
# Build Time: 2025-09-25T14:30:22Z
|
|||
|
|
#
|
|||
|
|
# Directories:
|
|||
|
|
# Source: /Users/user/repo-cnz/src
|
|||
|
|
# Tools: /Users/user/repo-cnz/src/tools
|
|||
|
|
# Build: /Users/user/repo-cnz/src/target
|
|||
|
|
# Distribution: /Users/user/repo-cnz/src/dist
|
|||
|
|
# Packages: /Users/user/repo-cnz/src/packages
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make info</code></strong> - Show detailed system information</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>OS and architecture details</li>
|
|||
|
|
<li>Tool versions (Nushell, Rust, Docker, Git)</li>
|
|||
|
|
<li>Environment information</li>
|
|||
|
|
<li>Build prerequisites</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="cicd-integration-targets"><a class="header" href="#cicd-integration-targets">CI/CD Integration Targets</a></h4>
|
|||
|
|
<p><strong><code>make ci-build</code></strong> - CI build pipeline</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Complete validation build</li>
|
|||
|
|
<li>Suitable for automated CI systems</li>
|
|||
|
|
<li>Comprehensive testing</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make ci-test</code></strong> - CI test pipeline</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Validation and testing only</li>
|
|||
|
|
<li>Fast feedback for pull requests</li>
|
|||
|
|
<li>Quality assurance</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make ci-release</code></strong> - CI release pipeline</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Build and packaging for releases</li>
|
|||
|
|
<li>Artifact preparation</li>
|
|||
|
|
<li>Release candidate creation</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong><code>make cd-deploy</code></strong> - CD deployment pipeline</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Complete release and deployment</li>
|
|||
|
|
<li>Artifact upload and distribution</li>
|
|||
|
|
<li>User notifications</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="platform-specific-targets"><a class="header" href="#platform-specific-targets">Platform-Specific Targets</a></h4>
|
|||
|
|
<p><strong><code>make linux</code></strong> - Build for Linux only</p>
|
|||
|
|
<pre><code class="language-bash">make linux
|
|||
|
|
# Sets PLATFORMS=linux-amd64
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make macos</code></strong> - Build for macOS only</p>
|
|||
|
|
<pre><code class="language-bash">make macos
|
|||
|
|
# Sets PLATFORMS=macos-amd64
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make windows</code></strong> - Build for Windows only</p>
|
|||
|
|
<pre><code class="language-bash">make windows
|
|||
|
|
# Sets PLATFORMS=windows-amd64
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="debugging-targets"><a class="header" href="#debugging-targets">Debugging Targets</a></h4>
|
|||
|
|
<p><strong><code>make debug</code></strong> - Build with debug information</p>
|
|||
|
|
<pre><code class="language-bash">make debug
|
|||
|
|
# Sets BUILD_MODE=debug VERBOSE=true
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong><code>make debug-info</code></strong> - Show debug information</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Make variables and environment</li>
|
|||
|
|
<li>Build system diagnostics</li>
|
|||
|
|
<li>Troubleshooting information</li>
|
|||
|
|
</ul>
|
|||
|
|
<h2 id="build-tools"><a class="header" href="#build-tools">Build Tools</a></h2>
|
|||
|
|
<h3 id="core-build-scripts"><a class="header" href="#core-build-scripts">Core Build Scripts</a></h3>
|
|||
|
|
<p>All build tools are implemented as Nushell scripts with comprehensive parameter validation and error handling.</p>
|
|||
|
|
<h4 id="srctoolsbuildcompile-platformnu"><a class="header" href="#srctoolsbuildcompile-platformnu"><code>/src/tools/build/compile-platform.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Compiles all Rust components for distribution</p>
|
|||
|
|
<p><strong>Components Compiled</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>orchestrator</code> → <code>provisioning-orchestrator</code> binary</li>
|
|||
|
|
<li><code>control-center</code> → <code>control-center</code> binary</li>
|
|||
|
|
<li><code>control-center-ui</code> → Web UI assets</li>
|
|||
|
|
<li><code>mcp-server-rust</code> → MCP integration binary</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu compile-platform.nu [options]
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--target STRING Target platform (default: x86_64-unknown-linux-gnu)
|
|||
|
|
--release Build in release mode
|
|||
|
|
--features STRING Comma-separated features to enable
|
|||
|
|
--output-dir STRING Output directory (default: dist/platform)
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
--clean Clean before building
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Example</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu compile-platform.nu \
|
|||
|
|
--target x86_64-apple-darwin \
|
|||
|
|
--release \
|
|||
|
|
--features "surrealdb,telemetry" \
|
|||
|
|
--output-dir dist/macos \
|
|||
|
|
--verbose
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="srctoolsbuildbundle-corenu"><a class="header" href="#srctoolsbuildbundle-corenu"><code>/src/tools/build/bundle-core.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Bundles Nushell core libraries and CLI for distribution</p>
|
|||
|
|
<p><strong>Components Bundled</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Nushell provisioning CLI wrapper</li>
|
|||
|
|
<li>Core Nushell libraries (<code>lib_provisioning</code>)</li>
|
|||
|
|
<li>Configuration system</li>
|
|||
|
|
<li>Template system</li>
|
|||
|
|
<li>Extensions and plugins</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu bundle-core.nu [options]
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--output-dir STRING Output directory (default: dist/core)
|
|||
|
|
--config-dir STRING Configuration directory (default: dist/config)
|
|||
|
|
--validate Validate Nushell syntax
|
|||
|
|
--compress Compress bundle with gzip
|
|||
|
|
--exclude-dev Exclude development files (default: true)
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Validation Features</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Syntax validation of all Nushell files</li>
|
|||
|
|
<li>Import dependency checking</li>
|
|||
|
|
<li>Function signature validation</li>
|
|||
|
|
<li>Test execution (if tests present)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="srctoolsbuildvalidate-kclnu"><a class="header" href="#srctoolsbuildvalidate-kclnu"><code>/src/tools/build/validate-kcl.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Validates and compiles KCL schemas</p>
|
|||
|
|
<p><strong>Validation Process</strong>:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li>Syntax validation of all <code>.k</code> files</li>
|
|||
|
|
<li>Schema dependency checking</li>
|
|||
|
|
<li>Type constraint validation</li>
|
|||
|
|
<li>Example validation against schemas</li>
|
|||
|
|
<li>Documentation generation</li>
|
|||
|
|
</ol>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu validate-kcl.nu [options]
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--output-dir STRING Output directory (default: dist/kcl)
|
|||
|
|
--format-code Format KCL code during validation
|
|||
|
|
--check-dependencies Validate schema dependencies
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="srctoolsbuildtest-distributionnu"><a class="header" href="#srctoolsbuildtest-distributionnu"><code>/src/tools/build/test-distribution.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Tests generated distributions for correctness</p>
|
|||
|
|
<p><strong>Test Types</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Basic</strong>: Installation test, CLI help, version check</li>
|
|||
|
|
<li><strong>Integration</strong>: Server creation, configuration validation</li>
|
|||
|
|
<li><strong>Complete</strong>: Full workflow testing including cluster operations</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu test-distribution.nu [options]
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--dist-dir STRING Distribution directory (default: dist)
|
|||
|
|
--test-types STRING Test types: basic,integration,complete
|
|||
|
|
--platform STRING Target platform for testing
|
|||
|
|
--cleanup Remove test files after completion
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="srctoolsbuildclean-buildnu"><a class="header" href="#srctoolsbuildclean-buildnu"><code>/src/tools/build/clean-build.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Intelligent build artifact cleanup</p>
|
|||
|
|
<p><strong>Cleanup Scopes</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>all</strong>: Complete cleanup (build, dist, packages, cache)</li>
|
|||
|
|
<li><strong>dist</strong>: Distribution artifacts only</li>
|
|||
|
|
<li><strong>cache</strong>: Build cache and temporary files</li>
|
|||
|
|
<li><strong>old</strong>: Files older than specified age</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu clean-build.nu [options]
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--scope STRING Cleanup scope: all,dist,cache,old
|
|||
|
|
--age DURATION Age threshold for 'old' scope (default: 7d)
|
|||
|
|
--force Force cleanup without confirmation
|
|||
|
|
--dry-run Show what would be cleaned without doing it
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="distribution-tools"><a class="header" href="#distribution-tools">Distribution Tools</a></h3>
|
|||
|
|
<h4 id="srctoolsdistributiongenerate-distributionnu"><a class="header" href="#srctoolsdistributiongenerate-distributionnu"><code>/src/tools/distribution/generate-distribution.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Main distribution generator orchestrating the complete process</p>
|
|||
|
|
<p><strong>Generation Process</strong>:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li>Platform binary compilation</li>
|
|||
|
|
<li>Core library bundling</li>
|
|||
|
|
<li>KCL schema validation and packaging</li>
|
|||
|
|
<li>Configuration system preparation</li>
|
|||
|
|
<li>Documentation generation</li>
|
|||
|
|
<li>Archive creation and compression</li>
|
|||
|
|
<li>Installer generation</li>
|
|||
|
|
<li>Validation and testing</li>
|
|||
|
|
</ol>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu generate-distribution.nu [command] [options]
|
|||
|
|
|
|||
|
|
Commands:
|
|||
|
|
<default> Generate complete distribution
|
|||
|
|
quick Quick development distribution
|
|||
|
|
status Show generation status
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--version STRING Version to build (default: auto-detect)
|
|||
|
|
--platforms STRING Comma-separated platforms
|
|||
|
|
--variants STRING Variants: complete,minimal
|
|||
|
|
--output-dir STRING Output directory (default: dist)
|
|||
|
|
--compress Enable compression
|
|||
|
|
--generate-docs Generate documentation
|
|||
|
|
--parallel-builds Enable parallel builds
|
|||
|
|
--validate-output Validate generated output
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Advanced Examples</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Complete multi-platform release
|
|||
|
|
nu generate-distribution.nu \
|
|||
|
|
--version 2.1.0 \
|
|||
|
|
--platforms linux-amd64,macos-amd64,windows-amd64 \
|
|||
|
|
--variants complete,minimal \
|
|||
|
|
--compress \
|
|||
|
|
--generate-docs \
|
|||
|
|
--parallel-builds \
|
|||
|
|
--validate-output
|
|||
|
|
|
|||
|
|
# Quick development build
|
|||
|
|
nu generate-distribution.nu quick \
|
|||
|
|
--platform linux \
|
|||
|
|
--variant minimal
|
|||
|
|
|
|||
|
|
# Status check
|
|||
|
|
nu generate-distribution.nu status
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="srctoolsdistributioncreate-installernu"><a class="header" href="#srctoolsdistributioncreate-installernu"><code>/src/tools/distribution/create-installer.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Creates platform-specific installers</p>
|
|||
|
|
<p><strong>Installer Types</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>shell</strong>: Shell script installer (cross-platform)</li>
|
|||
|
|
<li><strong>package</strong>: Platform packages (DEB, RPM, MSI, PKG)</li>
|
|||
|
|
<li><strong>container</strong>: Container image with provisioning</li>
|
|||
|
|
<li><strong>source</strong>: Source distribution with build instructions</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu create-installer.nu DISTRIBUTION_DIR [options]
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--output-dir STRING Installer output directory
|
|||
|
|
--installer-types STRING Installer types: shell,package,container,source
|
|||
|
|
--platforms STRING Target platforms
|
|||
|
|
--include-services Include systemd/launchd service files
|
|||
|
|
--create-uninstaller Generate uninstaller
|
|||
|
|
--validate-installer Test installer functionality
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="package-tools"><a class="header" href="#package-tools">Package Tools</a></h3>
|
|||
|
|
<h4 id="srctoolspackagepackage-binariesnu"><a class="header" href="#srctoolspackagepackage-binariesnu"><code>/src/tools/package/package-binaries.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Packages compiled binaries for distribution</p>
|
|||
|
|
<p><strong>Package Formats</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>archive</strong>: TAR.GZ and ZIP archives</li>
|
|||
|
|
<li><strong>standalone</strong>: Single binary with embedded resources</li>
|
|||
|
|
<li><strong>installer</strong>: Platform-specific installer packages</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Features</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Binary stripping for size reduction</li>
|
|||
|
|
<li>Compression optimization</li>
|
|||
|
|
<li>Checksum generation (SHA256, MD5)</li>
|
|||
|
|
<li>Digital signing (if configured)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h4 id="srctoolspackagebuild-containersnu"><a class="header" href="#srctoolspackagebuild-containersnu"><code>/src/tools/package/build-containers.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Builds optimized container images</p>
|
|||
|
|
<p><strong>Container Features</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Multi-stage builds for minimal image size</li>
|
|||
|
|
<li>Security scanning integration</li>
|
|||
|
|
<li>Multi-platform image generation</li>
|
|||
|
|
<li>Layer caching optimization</li>
|
|||
|
|
<li>Runtime environment configuration</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="release-tools"><a class="header" href="#release-tools">Release Tools</a></h3>
|
|||
|
|
<h4 id="srctoolsreleasecreate-releasenu"><a class="header" href="#srctoolsreleasecreate-releasenu"><code>/src/tools/release/create-release.nu</code></a></h4>
|
|||
|
|
<p><strong>Purpose</strong>: Automated release creation and management</p>
|
|||
|
|
<p><strong>Release Process</strong>:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li>Version validation and tagging</li>
|
|||
|
|
<li>Changelog generation from git history</li>
|
|||
|
|
<li>Asset building and validation</li>
|
|||
|
|
<li>Release creation (GitHub, GitLab, etc.)</li>
|
|||
|
|
<li>Asset upload and verification</li>
|
|||
|
|
<li>Release announcement preparation</li>
|
|||
|
|
</ol>
|
|||
|
|
<p><strong>Usage</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">nu create-release.nu [options]
|
|||
|
|
|
|||
|
|
Options:
|
|||
|
|
--version STRING Release version (required)
|
|||
|
|
--asset-dir STRING Directory containing release assets
|
|||
|
|
--draft Create draft release
|
|||
|
|
--prerelease Mark as pre-release
|
|||
|
|
--generate-changelog Auto-generate changelog
|
|||
|
|
--push-tag Push git tag
|
|||
|
|
--auto-upload Upload assets automatically
|
|||
|
|
--verbose Enable verbose logging
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="cross-platform-compilation"><a class="header" href="#cross-platform-compilation">Cross-Platform Compilation</a></h2>
|
|||
|
|
<h3 id="supported-platforms"><a class="header" href="#supported-platforms">Supported Platforms</a></h3>
|
|||
|
|
<p><strong>Primary Platforms</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>linux-amd64</code> (x86_64-unknown-linux-gnu)</li>
|
|||
|
|
<li><code>macos-amd64</code> (x86_64-apple-darwin)</li>
|
|||
|
|
<li><code>windows-amd64</code> (x86_64-pc-windows-gnu)</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Additional Platforms</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>linux-arm64</code> (aarch64-unknown-linux-gnu)</li>
|
|||
|
|
<li><code>macos-arm64</code> (aarch64-apple-darwin)</li>
|
|||
|
|
<li><code>freebsd-amd64</code> (x86_64-unknown-freebsd)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="cross-compilation-setup"><a class="header" href="#cross-compilation-setup">Cross-Compilation Setup</a></h3>
|
|||
|
|
<p><strong>Install Rust Targets</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Install additional targets
|
|||
|
|
rustup target add x86_64-apple-darwin
|
|||
|
|
rustup target add x86_64-pc-windows-gnu
|
|||
|
|
rustup target add aarch64-unknown-linux-gnu
|
|||
|
|
rustup target add aarch64-apple-darwin
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Platform-Specific Dependencies</strong>:</p>
|
|||
|
|
<p><strong>macOS Cross-Compilation</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Install osxcross toolchain
|
|||
|
|
brew install FiloSottile/musl-cross/musl-cross
|
|||
|
|
brew install mingw-w64
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Windows Cross-Compilation</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Install Windows dependencies
|
|||
|
|
brew install mingw-w64
|
|||
|
|
# or on Linux:
|
|||
|
|
sudo apt-get install gcc-mingw-w64
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="cross-compilation-usage"><a class="header" href="#cross-compilation-usage">Cross-Compilation Usage</a></h3>
|
|||
|
|
<p><strong>Single Platform</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Build for macOS from Linux
|
|||
|
|
make build-platform RUST_TARGET=x86_64-apple-darwin
|
|||
|
|
|
|||
|
|
# Build for Windows
|
|||
|
|
make build-platform RUST_TARGET=x86_64-pc-windows-gnu
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Multiple Platforms</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Build for all configured platforms
|
|||
|
|
make build-cross
|
|||
|
|
|
|||
|
|
# Specify platforms
|
|||
|
|
make build-cross PLATFORMS=linux-amd64,macos-amd64,windows-amd64
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Platform-Specific Targets</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Quick platform builds
|
|||
|
|
make linux # Linux AMD64
|
|||
|
|
make macos # macOS AMD64
|
|||
|
|
make windows # Windows AMD64
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="dependency-management"><a class="header" href="#dependency-management">Dependency Management</a></h2>
|
|||
|
|
<h3 id="build-dependencies"><a class="header" href="#build-dependencies">Build Dependencies</a></h3>
|
|||
|
|
<p><strong>Required Tools</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Nushell 0.107.1+</strong>: Core shell and scripting</li>
|
|||
|
|
<li><strong>Rust 1.70+</strong>: Platform binary compilation</li>
|
|||
|
|
<li><strong>Cargo</strong>: Rust package management</li>
|
|||
|
|
<li><strong>KCL 0.11.2+</strong>: Configuration language</li>
|
|||
|
|
<li><strong>Git</strong>: Version control and tagging</li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Optional Tools</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Docker</strong>: Container image building</li>
|
|||
|
|
<li><strong>Cross</strong>: Simplified cross-compilation</li>
|
|||
|
|
<li><strong>SOPS</strong>: Secrets management</li>
|
|||
|
|
<li><strong>Age</strong>: Encryption for secrets</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="dependency-validation"><a class="header" href="#dependency-validation">Dependency Validation</a></h3>
|
|||
|
|
<p><strong>Check Dependencies</strong>:</p>
|
|||
|
|
<pre><code class="language-bash">make info
|
|||
|
|
# Shows versions of all required tools
|
|||
|
|
|
|||
|
|
# Output example:
|
|||
|
|
# Tool Versions:
|
|||
|
|
# Nushell: 0.107.1
|
|||
|
|
# Rust: rustc 1.75.0
|
|||
|
|
# Docker: Docker version 24.0.6
|
|||
|
|
# Git: git version 2.42.0
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Install Missing Dependencies</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Install Nushell
|
|||
|
|
cargo install nu
|
|||
|
|
|
|||
|
|
# Install KCL
|
|||
|
|
cargo install kcl-cli
|
|||
|
|
|
|||
|
|
# Install Cross (for cross-compilation)
|
|||
|
|
cargo install cross
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="dependency-caching"><a class="header" href="#dependency-caching">Dependency Caching</a></h3>
|
|||
|
|
<p><strong>Rust Dependencies</strong>:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Cargo cache: <code>~/.cargo/registry</code></li>
|
|||
|
|
<li>Target cache: <code>target/</code> directory</li>
|
|||
|
|
<li>Cross-compilation cache: <code>~/.cache/cross</code></li>
|
|||
|
|
</ul>
|
|||
|
|
<p><strong>Build Cache Management</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Clean Cargo cache
|
|||
|
|
cargo clean
|
|||
|
|
|
|||
|
|
# Clean cross-compilation cache
|
|||
|
|
cross clean
|
|||
|
|
|
|||
|
|
# Clean all caches
|
|||
|
|
make clean SCOPE=cache
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
|
|||
|
|
<h3 id="common-build-issues"><a class="header" href="#common-build-issues">Common Build Issues</a></h3>
|
|||
|
|
<h4 id="rust-compilation-errors"><a class="header" href="#rust-compilation-errors">Rust Compilation Errors</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>linker 'cc' not found</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Install build essentials
|
|||
|
|
sudo apt-get install build-essential # Linux
|
|||
|
|
xcode-select --install # macOS
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Error</strong>: <code>target not found</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Install target
|
|||
|
|
rustup target add x86_64-unknown-linux-gnu
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Error</strong>: Cross-compilation linking errors</p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Use cross instead of cargo
|
|||
|
|
cargo install cross
|
|||
|
|
make build-platform CROSS=true
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="nushell-script-errors"><a class="header" href="#nushell-script-errors">Nushell Script Errors</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>command not found</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Ensure Nushell is in PATH
|
|||
|
|
which nu
|
|||
|
|
export PATH="$HOME/.cargo/bin:$PATH"
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Error</strong>: Permission denied</p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Make scripts executable
|
|||
|
|
chmod +x src/tools/build/*.nu
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Error</strong>: Module not found</p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Check working directory
|
|||
|
|
cd src/tools
|
|||
|
|
nu build/compile-platform.nu --help
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="kcl-validation-errors"><a class="header" href="#kcl-validation-errors">KCL Validation Errors</a></h4>
|
|||
|
|
<p><strong>Error</strong>: <code>kcl command not found</code></p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Install KCL
|
|||
|
|
cargo install kcl-cli
|
|||
|
|
# or
|
|||
|
|
brew install kcl
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Error</strong>: Schema validation failed</p>
|
|||
|
|
<pre><code class="language-bash"># Solution: Check KCL syntax
|
|||
|
|
kcl fmt kcl/
|
|||
|
|
kcl check kcl/
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="build-performance-issues"><a class="header" href="#build-performance-issues">Build Performance Issues</a></h3>
|
|||
|
|
<h4 id="slow-compilation"><a class="header" href="#slow-compilation">Slow Compilation</a></h4>
|
|||
|
|
<p><strong>Optimizations</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Enable parallel builds
|
|||
|
|
make build-all PARALLEL=true
|
|||
|
|
|
|||
|
|
# Use faster linker
|
|||
|
|
export RUSTFLAGS="-C link-arg=-fuse-ld=lld"
|
|||
|
|
|
|||
|
|
# Increase build jobs
|
|||
|
|
export CARGO_BUILD_JOBS=8
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Cargo Configuration</strong> (<code>~/.cargo/config.toml</code>):</p>
|
|||
|
|
<pre><code class="language-toml">[build]
|
|||
|
|
jobs = 8
|
|||
|
|
|
|||
|
|
[target.x86_64-unknown-linux-gnu]
|
|||
|
|
linker = "lld"
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="memory-issues"><a class="header" href="#memory-issues">Memory Issues</a></h4>
|
|||
|
|
<p><strong>Solutions</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Reduce parallel jobs
|
|||
|
|
export CARGO_BUILD_JOBS=2
|
|||
|
|
|
|||
|
|
# Use debug build for development
|
|||
|
|
make dev-build BUILD_MODE=debug
|
|||
|
|
|
|||
|
|
# Clean up between builds
|
|||
|
|
make clean-dist
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="distribution-issues"><a class="header" href="#distribution-issues">Distribution Issues</a></h3>
|
|||
|
|
<h4 id="missing-assets"><a class="header" href="#missing-assets">Missing Assets</a></h4>
|
|||
|
|
<p><strong>Validation</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Test distribution
|
|||
|
|
make test-dist
|
|||
|
|
|
|||
|
|
# Detailed validation
|
|||
|
|
nu src/tools/package/validate-package.nu dist/
|
|||
|
|
</code></pre>
|
|||
|
|
<h4 id="size-optimization"><a class="header" href="#size-optimization">Size Optimization</a></h4>
|
|||
|
|
<p><strong>Optimizations</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Strip binaries
|
|||
|
|
make package-binaries STRIP=true
|
|||
|
|
|
|||
|
|
# Enable compression
|
|||
|
|
make dist-generate COMPRESS=true
|
|||
|
|
|
|||
|
|
# Use minimal variant
|
|||
|
|
make dist-generate VARIANTS=minimal
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="debug-mode"><a class="header" href="#debug-mode">Debug Mode</a></h3>
|
|||
|
|
<p><strong>Enable Debug Logging</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Set environment
|
|||
|
|
export PROVISIONING_DEBUG=true
|
|||
|
|
export RUST_LOG=debug
|
|||
|
|
|
|||
|
|
# Run with debug
|
|||
|
|
make debug
|
|||
|
|
|
|||
|
|
# Verbose make output
|
|||
|
|
make build-all VERBOSE=true
|
|||
|
|
</code></pre>
|
|||
|
|
<p><strong>Debug Information</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Show debug information
|
|||
|
|
make debug-info
|
|||
|
|
|
|||
|
|
# Build system status
|
|||
|
|
make status
|
|||
|
|
|
|||
|
|
# Tool information
|
|||
|
|
make info
|
|||
|
|
</code></pre>
|
|||
|
|
<h2 id="cicd-integration"><a class="header" href="#cicd-integration">CI/CD Integration</a></h2>
|
|||
|
|
<h3 id="github-actions"><a class="header" href="#github-actions">GitHub Actions</a></h3>
|
|||
|
|
<p><strong>Example Workflow</strong> (<code>.github/workflows/build.yml</code>):</p>
|
|||
|
|
<pre><code class="language-yaml">name: Build and Test
|
|||
|
|
on: [push, pull_request]
|
|||
|
|
|
|||
|
|
jobs:
|
|||
|
|
build:
|
|||
|
|
runs-on: ubuntu-latest
|
|||
|
|
steps:
|
|||
|
|
- uses: actions/checkout@v4
|
|||
|
|
|
|||
|
|
- name: Setup Nushell
|
|||
|
|
uses: hustcer/setup-nu@v3.5
|
|||
|
|
|
|||
|
|
- name: Setup Rust
|
|||
|
|
uses: actions-rs/toolchain@v1
|
|||
|
|
with:
|
|||
|
|
toolchain: stable
|
|||
|
|
|
|||
|
|
- name: CI Build
|
|||
|
|
run: |
|
|||
|
|
cd src/tools
|
|||
|
|
make ci-build
|
|||
|
|
|
|||
|
|
- name: Upload Artifacts
|
|||
|
|
uses: actions/upload-artifact@v4
|
|||
|
|
with:
|
|||
|
|
name: build-artifacts
|
|||
|
|
path: src/dist/
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="release-automation"><a class="header" href="#release-automation">Release Automation</a></h3>
|
|||
|
|
<p><strong>Release Workflow</strong>:</p>
|
|||
|
|
<pre><code class="language-yaml">name: Release
|
|||
|
|
on:
|
|||
|
|
push:
|
|||
|
|
tags: ['v*']
|
|||
|
|
|
|||
|
|
jobs:
|
|||
|
|
release:
|
|||
|
|
runs-on: ubuntu-latest
|
|||
|
|
steps:
|
|||
|
|
- uses: actions/checkout@v4
|
|||
|
|
|
|||
|
|
- name: Build Release
|
|||
|
|
run: |
|
|||
|
|
cd src/tools
|
|||
|
|
make ci-release VERSION=${{ github.ref_name }}
|
|||
|
|
|
|||
|
|
- name: Create Release
|
|||
|
|
run: |
|
|||
|
|
cd src/tools
|
|||
|
|
make release VERSION=${{ github.ref_name }}
|
|||
|
|
</code></pre>
|
|||
|
|
<h3 id="local-ci-testing"><a class="header" href="#local-ci-testing">Local CI Testing</a></h3>
|
|||
|
|
<p><strong>Test CI Pipeline Locally</strong>:</p>
|
|||
|
|
<pre><code class="language-bash"># Run CI build pipeline
|
|||
|
|
make ci-build
|
|||
|
|
|
|||
|
|
# Run CI test pipeline
|
|||
|
|
make ci-test
|
|||
|
|
|
|||
|
|
# Full CI/CD pipeline
|
|||
|
|
make ci-release
|
|||
|
|
</code></pre>
|
|||
|
|
<p>This build system provides a comprehensive, maintainable foundation for the provisioning project’s development lifecycle, from local development to production releases.</p>
|
|||
|
|
|
|||
|
|
</main>
|
|||
|
|
|
|||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|||
|
|
<!-- Mobile navigation buttons -->
|
|||
|
|
<a rel="prev" href="../development/index.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../development/project-structure.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<div style="clear: both"></div>
|
|||
|
|
</nav>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|||
|
|
<a rel="prev" href="../development/index.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../development/project-structure.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<!-- Livereload script (if served using the cli tool) -->
|
|||
|
|
<script>
|
|||
|
|
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
|||
|
|
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
|||
|
|
const socket = new WebSocket(wsAddress);
|
|||
|
|
socket.onmessage = function (event) {
|
|||
|
|
if (event.data === "reload") {
|
|||
|
|
socket.close();
|
|||
|
|
location.reload();
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
window.onbeforeunload = function() {
|
|||
|
|
socket.close();
|
|||
|
|
}
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script>
|
|||
|
|
window.playground_copyable = true;
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script src="../elasticlunr.min.js"></script>
|
|||
|
|
<script src="../mark.min.js"></script>
|
|||
|
|
<script src="../searcher.js"></script>
|
|||
|
|
|
|||
|
|
<script src="../clipboard.min.js"></script>
|
|||
|
|
<script src="../highlight.js"></script>
|
|||
|
|
<script src="../book.js"></script>
|
|||
|
|
|
|||
|
|
<!-- Custom JS scripts -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|