Skip to main content
FlowDeck includes an intelligent background build feature that automatically builds your project incrementally to keep SourceKit LSP’s code intelligence up-to-date. This ensures you always have accurate autocomplete, symbol navigation, and error detection without manual intervention.

​
How It Works

When enabled, FlowDeck:
  1. Monitors file changes - Watches Swift and Objective-C source files for modifications
  2. Debounces changes - Waits for a configurable delay to batch multiple changes
  3. Runs incremental builds - Performs low-priority background builds with reduced CPU usage
  4. Updates code index - Automatically refreshes SourceKit LSP’s understanding of your code
  5. Parses build logs - Updates .compile files for accurate LSP integration
Background builds run with reduced CPU priority and limited parallelism to minimize impact on your system performance.

​
Configuration

Access background build settings through: Settings → Extensions → FlowDeck → Language Server Protocol (Experimental)

​
Available Settings

SettingTypeDefaultDescription
flowdeck.lsp.backgroundBuilds.enabledbooleantrueEnable/disable automatic background builds
flowdeck.lsp.backgroundBuilds.delaynumber3000Delay in milliseconds after file changes (1000-10000)
flowdeck.lsp.backgroundBuilds.jobLimitnumber4Number of parallel build jobs (1-16)
flowdeck.lsp.backgroundBuilds.nicePrioritynumber15Process priority (0-19, higher = lower priority)
flowdeck.lsp.backgroundBuilds.batteryAwarebooleantrueReduce resources when on battery power
flowdeck.lsp.backgroundBuilds.skipOnSyntaxErrorsbooleantrueSkip builds when files have syntax errors
flowdeck.lsp.xcodebuildserver.autogeneratebooleantrueAuto-regenerate build server config on scheme changes

​
Performance Tuning

​
For Best Code Intelligence (Higher CPU Usage)

{
  "flowdeck.lsp.backgroundBuilds.enabled": true,
  "flowdeck.lsp.backgroundBuilds.delay": 1000,
  "flowdeck.lsp.backgroundBuilds.jobLimit": 8,
  "flowdeck.lsp.backgroundBuilds.nicePriority": 10
}

​
Balanced Performance (Default)

{
  "flowdeck.lsp.backgroundBuilds.enabled": true,
  "flowdeck.lsp.backgroundBuilds.delay": 3000,
  "flowdeck.lsp.backgroundBuilds.jobLimit": 4,
  "flowdeck.lsp.backgroundBuilds.nicePriority": 15
}

​
Low Resource Usage

{
  "flowdeck.lsp.backgroundBuilds.enabled": true,
  "flowdeck.lsp.backgroundBuilds.delay": 5000,
  "flowdeck.lsp.backgroundBuilds.jobLimit": 2,
  "flowdeck.lsp.backgroundBuilds.nicePriority": 19
}

​
Manual Builds Only

{
  "flowdeck.lsp.backgroundBuilds.enabled": false
}

​
Battery-Aware Mode

When batteryAware is enabled and your Mac is running on battery power:
  • Build priority automatically increases to 19 (lowest)
  • Job limit reduces to 2 parallel jobs
  • Helps conserve battery life during development

​
Understanding Build Priority

The nicePriority setting controls how much CPU the background builds can use:
  • 0-9: Higher priority than normal processes (not recommended)
  • 10-14: Moderate priority
  • 15-19: Low priority (recommended for background builds)
  • 19: Lowest priority, yields to all other processes

​
Monitored File Types

Background builds trigger for changes to:
  • *.swift - Swift source files
  • *.h - Header files
  • *.m - Objective-C source files
  • *.mm - Objective-C++ source files
  • *.cpp, *.cc, *.c - C/C++ source files
  • *.hpp, *.hxx - C++ header files
Files in these directories are automatically ignored:
  • /.build/ - Swift Package Manager build directory
  • /DerivedData/ - Xcode derived data
  • /build/ - Generic build directories
CommandDescription
FlowDeck: Toggle Background LSP BuildsEnable/disable background builds
FlowDeck: Show Background LSP Build StatusDisplay current build status
FlowDeck: Update LSP Index for Current FileManually trigger indexing for current file
FlowDeck: Quick Build for LSP UpdatePerform a quick build to update code intelligence

​
Xcode Build Server Integration

FlowDeck automatically manages the buildServer.json configuration file that connects SourceKit LSP to the Xcode build system. When you change schemes or build configurations, FlowDeck:
  1. Detects the change
  2. Regenerates buildServer.json
  3. Updates build flags in .compile files
  4. SourceKit LSP automatically picks up the changes
The deprecated setting flowdeck.build.restartLSPServerOnBuild is no longer needed as SourceKit LSP now automatically detects configuration changes.

​
Troubleshooting

​
Background Builds Not Starting

  • Check that flowdeck.lsp.backgroundBuilds.enabled is true
  • Verify you have an active scheme selected
  • Ensure your project builds successfully manually first

​
High CPU Usage

  • Increase the delay setting to batch more changes
  • Reduce jobLimit to use fewer parallel jobs
  • Increase nicePriority to 18 or 19

​
Code Intelligence Not Updating

  • Check the Output panel for build errors
  • Ensure syntax errors are fixed (or disable skipOnSyntaxErrors)
  • Try a manual build with FlowDeck: Build

​
Battery Draining Quickly

  • Enable batteryAware mode
  • Increase nicePriority to 19
  • Consider disabling background builds on battery

​
Best Practices

  1. Start with defaults - The default settings work well for most projects
  2. Adjust based on project size - Larger projects benefit from longer delays
  3. Monitor CPU usage - Use Activity Monitor to ensure builds aren’t impacting performance
  4. Fix syntax errors quickly - Background builds skip files with syntax errors by default
  5. Use manual builds for major changes - After big refactors, run a full manual build
Background builds require a successful initial build. Always ensure your project builds successfully before relying on automatic background builds.