Krypton Toolkit Build System and Workflows Documentation

Overview

This document contains comprehensive developer documentation for the Krypton Toolkit build system, workflows, and development processes. The documentation is organized into focused topics, each in its own file.

Documentation Index

1. Build System Overview

Start here for an introduction to the build system.

  • Build system architecture and components
  • Configuration overview (Stable, Canary, Nightly, Debug, Installer)
  • Target frameworks and multi-targeting
  • Directory structure
  • Build outputs and artifacts
  • Prerequisites and requirements
  • Common build tasks

2. MSBuild Project Files

Detailed documentation of .proj files.

  • Project file structure and patterns
  • Scripts/Build/build.proj - Stable/Release builds
  • Scripts/Build/canary.proj - Beta pre-releases
  • Scripts/Build/nightly.proj - Alpha nightly builds
  • debug.proj - Debug builds
  • installer.proj - Installer packages
  • Available targets (Clean, Restore, Build, Pack, Push, etc.)
  • Archive generation (ZIP, TAR.GZ)
  • Custom target execution

3. Build Scripts

Windows command scripts for building and maintenance.

  • build-stable.cmd - Stable release builds
  • build-canary.cmd - Canary release builds
  • build-nightly.cmd - Nightly release builds
  • buildsolution.cmd - Interactive builder
  • purge.cmd - Clean build artifacts
  • publish.cmd - Publish to NuGet
  • Visual Studio detection
  • Logging and troubleshooting

4. Directory.Build Configuration

MSBuild property and target configuration.

  • Root Directory.Build.props - Global versioning
  • Component Directory.Build.props - Component properties
  • Component Directory.Build.targets - Component targets
  • Version calculation by configuration
  • Conditional compilation symbols
  • Assembly information
  • NuGet package metadata
  • Property inheritance

5. Version Management

Automated versioning strategy and implementation.

  • Version format: Major.Minor.Build.Revision[-Suffix]
  • Date-based semantic versioning
  • Configuration-specific versioning
  • Version properties (Assembly, File, Package)
  • Version ordering and SemVer compliance
  • Querying version information
  • Best practices and troubleshooting

6. NuGet Package Creation and Publishing

Complete guide to NuGet packages.

  • Package structure and variants
  • Lite vs. full packages
  • Configuration-specific packages (Stable, Canary, Nightly)
  • Package creation workflow
  • Package metadata and dependencies
  • Publishing to NuGet.org
  • Publishing to GitHub Packages
  • Package verification
  • Local package testing
  • Troubleshooting

7. GitHub Actions CI/CD Workflows

Automated continuous integration and deployment.

  • build.yml - CI builds for PRs and branches
  • release.yml - Production releases for multiple branches
  • nightly.yml - Automated nightly builds with change detection
  • Security features and verification
  • Required secrets and variables
  • Workflow outputs and notifications
  • Troubleshooting CI/CD issues
  • Manual workflow execution

8. ModernBuild Tool

Interactive Terminal UI build tool.

  • Installation and running
  • User interface layout
  • Ops Page - Build operations
  • NuGet Page - Package publishing
  • Controls and keyboard shortcuts
  • Build logs and status
  • Project file detection
  • Troubleshooting ModernBuild

9. Troubleshooting Guide

Solutions to common issues.

  • Build system issues
  • Compilation errors
  • NuGet package issues
  • GitHub Actions issues
  • Runtime issues
  • Performance issues
  • Getting help and reporting issues

Quick Start

New to the Project?

  1. Start with Build System Overview
  2. Try building with Build Scripts

Building the Toolkit?

  1. Review Build Scripts
  2. Understand MSBuild Project Files
  3. Learn about Version Management

Creating Packages?

  1. Read NuGet Package Creation and Publishing
  2. Understand Version Management
  3. Review Directory.Build Configuration

Setting up CI/CD?

  1. Study GitHub Actions CI/CD Workflows
  2. Understand Version Management
  3. Review NuGet Package Creation and Publishing

Troubleshooting?

  1. Check Troubleshooting Guide first
  2. Review relevant topic documentation
  3. Check GitHub Issues

Common Tasks

Build Debug Locally

dotnet build "Source/Krypton Components/Krypton Toolkit Suite 2022 - VS2022.sln" -c Debug

Build Release

cd Scripts
build-stable.cmd Build

See: Build Scripts

Create NuGet Packages

cd Scripts
msbuild build.proj /t:Build;Pack

See: NuGet Package Creation and Publishing

Publish to NuGet.org

cd Scripts
publish.cmd

See: NuGet Package Creation and Publishing

Clean Build Artifacts

cd Scripts
purge.cmd

See: Build Scripts

Run TestForm

dotnet run --project "Source/Krypton Components/TestForm/TestForm.csproj" -c Debug

Conventions

Code Examples

All code examples use:

  • Windows Command Prompt syntax (not PowerShell or Bash)
  • Absolute paths where needed for clarity
  • Relative paths from repository root by default

Terminology

Term Meaning
TFM Target Framework Moniker (e.g., net8.0-windows)
Configuration Build configuration (Debug, Release, Canary, Nightly, Installer)
Channel Release channel (Stable, Canary, Nightly)
Lite Package variant with fewer frameworks (TFMs=lite)
All Package variant with all frameworks (TFMs=all)
CI/CD Continuous Integration / Continuous Deployment

Contributing to Documentation

Updating Documentation

  1. Edit relevant .md file in Documents/Workflows/
  2. Follow existing formatting and structure
  3. Update cross-references if needed
  4. Update this README if adding new files

Adding New Documentation

  1. Create new file: ##-New-Topic.md
  2. Add entry to Documentation Index
  3. Add to Quick Start if relevant
  4. Add cross-references in related documents

Documentation Standards

  • Use Markdown formatting
  • Include code examples for common tasks
  • Provide troubleshooting tips where applicable
  • Cross-reference related documentation
  • Keep line length reasonable (80-120 characters preferred)
  • Use tables for structured information
  • Include command-line examples with expected outputs

Additional Resources

External Documentation

Krypton Suite Resources