Build Configuration

Set up automated build triggers and configuration

Table of contents

1. Build Configuration Overview
   1. Prerequisites
2. Build Triggers
   1. Automatic Triggers
      1. Source Control Triggers
      2. Schedule Triggers
      3. Manual Triggers
   2. Trigger Configuration
3. Build Templates
   1. Quick Start Templates
      1. Unreal Engine Template
      2. Unity Template
      3. Custom Engine Template
   2. Creating Custom Templates
4. Build Environments
   1. Environment Setup
      1. Cloud Builders
      2. Self-Hosted Builders
   2. Environment Configuration
5. Build Steps Deep Dive
   1. Pre-Build Steps
   2. Main Build Steps
   3. Post-Build Steps
6. Advanced Configuration
   1. Conditional Builds
   2. Parallel Builds
   3. Build Caching
7. Testing Your Configuration
   1. Build Testing Workflow
   2. Common Build Issues
      1. Build Timeouts
      2. Missing Dependencies
      3. Artifact Upload Failures
8. Monitoring and Optimization
   1. Build Metrics
   2. Performance Optimization
      1. Speed Improvements
      2. Cost Optimization
9. Next Steps

Build Configuration Overview

ButterStack automates your build process by monitoring triggers and executing predefined build steps. This guide walks you through setting up your first automated build.

Prerequisites

Before configuring builds, ensure you have:

• Project created in ButterStack
• Source control connected (Git, Perforce, etc.)
• Build system integrated (Jenkins, GitHub Actions, etc.)
• Basic understanding of your build process

Build Triggers

Automatic Triggers

ButterStack can automatically start builds based on various events:

Source Control Triggers

• Commit to main branch - Build every commit to production branch
• Pull request creation - Build PRs for testing
• Tag creation - Build releases when tags are pushed
• Branch creation - Build new feature branches

Schedule Triggers

• Nightly builds - Run comprehensive builds overnight
• Weekly builds - Full builds with all tests
• Custom schedule - Define your own cron schedule

Manual Triggers

• On-demand builds - Start builds manually from dashboard
• API triggers - Trigger builds via REST API
• Chat commands - Trigger builds from Slack/Discord

Trigger Configuration

1. Navigate to Build Settings
   • Go to Project Dashboard
   • Click Build Configuration
   • Select Triggers tab
2. Enable Desired Triggers ```yaml triggers:
   • type: commit branches: [main, develop] message_filter: “#ci”
   • type: schedule cron: “0 2 * * *” # Nightly at 2 AM
   • type: pull_request target_branches: [main] ```
3. Configure Trigger Conditions
   • Set branch filters
   • Define file path filters
   • Add commit message filters

Build Templates

Quick Start Templates

ButterStack provides pre-configured templates for common scenarios:

Unreal Engine Template

name: Unreal Engine Build
engine: unreal
version: "5.3"
platform: Windows
steps:
  - name: Setup
    action: setup_unreal
  - name: Build
    action: build_project
    config: Development
  - name: Package
    action: package_game
    platform: Win64

Unity Template

name: Unity Build
engine: unity
version: "2023.2"
platform: Windows
steps:
  - name: Setup
    action: setup_unity
  - name: Build
    action: build_player
    target: StandaloneWindows64
  - name: Archive
    action: create_archive

Custom Engine Template

name: Custom Build
engine: custom
steps:
  - name: Environment Setup
    script: "./scripts/setup.sh"
  - name: Compile Code
    script: "make release"
  - name: Run Tests
    script: "./run_tests.sh"
  - name: Package Build
    script: "./package.sh"

Creating Custom Templates

1. Start from Template
   • Choose closest existing template
   • Customize for your needs
2. Define Build Steps ```yaml steps:

   • name: “Pre-build Setup” script: “./scripts/prebuild.sh” timeout: 300

   • name: “Compile Assets” script: “cook_assets.exe” parallel: true

   • name: “Build Executable” script: “build.exe –config Release” artifacts: [“bin/Game.exe”]

   • name: “Run Unit Tests” script: “test_runner.exe” continue_on_failure: false ```

3. Configure Artifacts ```yaml artifacts:

   • name: “Game Executable” path: “bin/Game.exe” publish: true

   • name: “Debug Symbols” path: “bin/*.pdb” publish: false retention_days: 7 ```

Build Environments

Environment Setup

Define the environment where builds will run:

Cloud Builders

• Shared runners - Cost-effective for small projects
• Dedicated runners - Consistent performance for larger projects
• GPU-enabled runners - For builds requiring graphics processing

Self-Hosted Builders

• On-premise machines - Full control over build environment
• Hybrid setup - Mix of cloud and on-premise
• Docker containers - Consistent, reproducible builds

Environment Configuration

environment:
  type: cloud  # or self_hosted
  os: windows
  cpu_cores: 8
  memory_gb: 32
  gpu: nvidia_rtx_4080
  
  # Custom software
  software:
    - unreal_engine_5.3
    - visual_studio_2022
    - perforce_client
    
  # Environment variables
  env_vars:
    UE_ROOT: "C:/UnrealEngine"
    BUILD_CONFIG: "Shipping"

Build Steps Deep Dive

Pre-Build Steps

Essential setup before main build:

pre_build:
  - name: "Clean Workspace"
    script: "rm -rf build/*"
    
  - name: "Sync Source"
    action: sync_perforce
    changelist: latest
    
  - name: "Install Dependencies"
    script: "npm install"
    cache_key: "package-lock.json"

Main Build Steps

Core compilation and processing:

build:
  - name: "Compile Code"
    script: "msbuild Game.sln /p:Configuration=Release"
    timeout: 1800  # 30 minutes
    
  - name: "Cook Content"
    script: "UnrealBuildTool -cook -platform=Win64"
    parallel: true
    
  - name: "Package Game"
    script: "UnrealBuildTool -package -distribution"
    artifacts: ["Packaged/Game/*"]

Post-Build Steps

Cleanup and publication:

post_build:
  - name: "Run Tests"
    script: "./run_automation_tests.sh"
    continue_on_failure: true
    
  - name: "Upload to Steam"
    action: steam_upload
    condition: "branch == 'main'"
    
  - name: "Send Notifications"
    action: notify_slack
    channel: "#builds"

Advanced Configuration

Conditional Builds

Run different builds based on conditions:

conditions:
  - if: "branch == 'main'"
    steps:
      - name: "Production Build"
        script: "./build_production.sh"
        
  - if: "branch startsWith 'feature/'"
    steps:
      - name: "Feature Build"
        script: "./build_feature.sh"
        
  - if: "files_changed contains '*.cpp'"
    steps:
      - name: "C++ Code Analysis"
        script: "./analyze_cpp.sh"

Parallel Builds

Speed up builds with parallel execution:

parallel_jobs:
  - name: "Compile Game"
    script: "compile_game.sh"
    
  - name: "Compile Editor"
    script: "compile_editor.sh"
    
  - name: "Process Assets"
    script: "process_assets.sh"

# Wait for all parallel jobs before continuing
wait_for_parallel: true

next_steps:
  - name: "Package Everything"
    script: "package_final.sh"

Build Caching

Optimize build times with smart caching:

cache:
  - key: "cpp-objects-"
    paths: ["build/obj/"]
    
  - key: "asset-cache-"
    paths: ["build/cooked/"]
    
  - key: "dependencies-"
    paths: ["node_modules/"]

Testing Your Configuration

Build Testing Workflow

1. Start Small
   • Begin with minimal configuration
   • Add complexity gradually
2. Test Triggers
   • Verify automatic triggers work
   • Test manual trigger functionality
3. Validate Steps
   • Ensure each build step completes
   • Check artifact generation
4. Monitor Performance
   • Track build duration
   • Identify bottlenecks

Common Build Issues

Build Timeouts

Problem: Builds fail due to timeout

Solutions:

• Increase timeout values for long steps
• Optimize build process for speed
• Use parallel execution where possible

Missing Dependencies

Problem: Build fails due to missing tools/libraries

Solutions:

• Add dependency installation steps
• Use Docker for consistent environments
• Pre-install tools on build machines

Artifact Upload Failures

Problem: Build artifacts not properly stored

Solutions:

• Verify artifact paths are correct
• Check storage permissions
• Ensure sufficient disk space

Monitoring and Optimization

Build Metrics

Track important build metrics:

• Build Success Rate - Percentage of successful builds
• Average Build Time - Time from start to completion
• Queue Time - Time waiting for available runner
• Cost per Build - Resource usage and billing

Performance Optimization

Speed Improvements

• Incremental builds - Only rebuild changed components
• Distributed builds - Spread work across multiple machines
• Build caching - Reuse previous build artifacts
• Parallel processing - Run independent tasks simultaneously

Cost Optimization

• Right-size runners - Use appropriate machine specs
• Schedule management - Avoid peak pricing periods
• Resource cleanup - Clean up unused artifacts
• Spot instances - Use cheaper cloud instances when available

Next Steps

With builds configured:

1. Set Up Steam Deployment - Track releases to Steam
2. Configure Discord Notifications - Get build alerts
3. Unreal Build Setup - Advanced engine builds
4. Add More Integrations - Connect additional tools

Need Help? Build configuration can be complex. Our support team is here to help optimize your setup. Contact support@butterstack.com or join our Discord community.