Table of Contents

Build Scripts

The template includes cross-platform build scripts organized by functionality in the scripts/ folder for easy local development and CI/CD integration.

Build System Architecture

The core build system is implemented via Nuke in src/4-Build/Build.cs. This provides:

  • Centralized Build Logic: All build operations defined in one place
  • Dependency Management: Automatic execution order based on target dependencies
  • Cross-Platform Consistency: Same behavior across all operating systems

Script Organization

scripts/
├── compile/          # Compilation scripts
├── lint/            # Code linting scripts
├── packages/        # Package management scripts
└── tests/           # Test runner scripts

Available Scripts

Compile

  • Purpose: Compiles the entire solution
  • Location: scripts/compile/
  • Files: Compile.bat, Compile.ps1, Compile.sh
  • Nuke Equivalent: nuke Compile

Lint

  • Purpose: Runs code quality checks
  • Location: scripts/lint/
  • Files: Lint.bat, Lint.ps1, Lint.sh
  • Nuke Equivalent: nuke Lint

Tests

  • Purpose: Executes unit and integration tests
  • Location: scripts/tests/
  • Files: RunUnitTests.bat, RunUnitTests.ps1, RunUnitTests.sh
  • Nuke Equivalent: nuke RunUnitTests

Packages

  • Purpose: Updates CodeBlock DevKit NuGet packages
  • Location: scripts/packages/
  • Files: UpdateDevKitPackages.bat, UpdateDevKitPackages.ps1, UpdateDevKitPackages.sh
  • Nuke Equivalent: nuke UpdateDevKitPackages

Build Scripts vs Nuke Commands

Build Scripts (Convenience)

  • Purpose: Quick access to common build tasks
  • Use Case: Simple operations during development
  • Limitation: No dependency management between targets
  • Purpose: Full build system with dependency resolution
  • Use Case: Production builds, CI/CD pipelines, complex workflows
  • Advantage: Automatic execution order and dependency management

Note: The build scripts in the src/4-Build/scripts/ folder are convenience wrappers around Nuke commands. For production use and CI/CD, Nuke commands are recommended.

Running Scripts

Option 1: Direct Script Execution

Windows

# Batch files
scripts\compile\Compile.bat
scripts\lint\Lint.bat
scripts\tests\RunUnitTests.bat
scripts\packages\UpdateDevKitPackages.bat

# PowerShell
.\scripts\compile\Compile.ps1
.\scripts\lint\Lint.ps1
.\scripts\tests\RunUnitTests.ps1
.\scripts\packages\UpdateDevKitPackages.ps1

macOS/Linux

# Make scripts executable (one-time setup)
chmod +x scripts/**/*.sh

# Run scripts
./scripts/compile/Compile.sh
./scripts/lint/Lint.sh
./scripts/tests/RunUnitTests.sh
./scripts/packages/UpdateDevKitPackages.sh

All build operations are accessible via nuke commands from the template root directory:

# Compilation
nuke Compile

# Code quality
nuke Lint

# Testing
nuke RunUnitTests

# Package updates
nuke UpdateDevKitPackages

Nuke Build Targets and Dependencies

The Nuke build system automatically handles dependencies between targets:

LogInformation → Preparation → Clean → Restore → Compile → Lint → LintCheck → RunUnitTests

Key Nuke Targets

  • nuke LogInformation: Shows build configuration details
  • nuke Preparation: Prepares build artifacts and directories
  • nuke Clean: Cleans the solution
  • nuke Restore: Restores NuGet packages
  • nuke Compile: Compiles the solution
  • nuke Lint: Applies code formatting
  • nuke LintCheck: Verifies code formatting compliance
  • nuke RunUnitTests: Executes unit tests
  • nuke RunIntegrationTests: Executes integration tests
  • nuke UpdateDevKitPackages: Updates DevKit NuGet packages

Linting Configuration

Linting is a code quality tool that automatically checks and enforces coding standards, formatting rules, and best practices. It helps maintain consistent code style across your project and catches potential issues early.

How Linting Works in This Template

The template uses two main linting targets:

  • nuke Lint: Automatically fixes most linting issues and applies code formatting
  • nuke LintCheck: Verifies code compliance without making changes (used in CI pipelines)

Automatic Linting Resolution

When you run nuke Lint or the lint scripts, the system automatically resolves most linting issues:

  • Code Formatting: Applies consistent spacing, indentation, and line breaks
  • Style Rules: Enforces naming conventions and code structure
  • Analyzer Issues: Fixes simple code quality problems

Note: Most linting errors will be resolved automatically. Any remaining issues that can't be auto-fixed will need manual resolution.

Linting Rules Configuration

All linting rules are defined in the .editorconfig file in the root folder. This file configures:

  • Code formatting standards
  • Naming conventions
  • File organization rules
  • Language-specific settings

Controlling Linting Behavior

Linting can be controlled via the SkipLinting property in src/4-Build/Build.cs:

public class Build : BaseBuild
{
    /// <summary>
    /// Set to false to enable linting during build
    /// </summary>
    protected override bool SkipLinting => true; // Set to false to enable
}

Implications of Skipping Linting

Setting SkipLinting => true:

  • ✅ Faster Builds: No time spent on linting checks
  • ✅ No Linting Errors: Build won't fail due to style issues
  • ❌ Code Quality Risk: Inconsistent formatting and potential style violations
  • ❌ CI Pipeline Issues: nuke LintCheck will be ignored, potentially allowing poor code quality

Setting SkipLinting => false (Recommended):

  • ✅ Consistent Code Quality: Enforced coding standards
  • ✅ CI Pipeline Safety: Build fails if linting issues exist
  • ✅ Team Collaboration: Everyone follows the same code style
  • ❌ Build Time: Slightly longer builds due to linting checks

CI/CD Pipeline Integration

The nuke LintCheck target is automatically used in CI pipelines to ensure code quality:

  • Runs automatically on every build
  • Fails the build if linting issues are found
  • Ensures consistency across all team contributions
  • Can be bypassed by setting SkipLinting => true

Warning: If you set SkipLinting => true, your CI pipeline will not enforce code quality standards, which could lead to inconsistent code and potential merge conflicts.

Cross-Platform Compatibility

Each script category includes multiple formats:

  • .bat - Windows batch files
  • .ps1 - PowerShell scripts (cross-platform)
  • .sh - Shell scripts (Unix-based systems)

CI/CD Integration

These scripts are designed to work seamlessly in CI/CD pipelines:

  • Use nuke commands for consistent execution and dependency management
  • Scripts return appropriate exit codes for pipeline success/failure
  • Cross-platform compatibility ensures consistent behavior