Skip to main content

​
Overview

This guide will walk you through building and running the ExampleApp using Buck. You’ll learn the basic Buck commands and workflows used in iOS development.
Make sure you’ve completed the Installation steps before proceeding.

​
Basic Workflow

1

Navigate to the project directory

Open your terminal and navigate to the BuckSample directory:
cd BuckSample
2

List available targets

View all build targets in the project:
make targets
Or use Buck directly:
tools/buck targets //...
You’ll see output listing all available targets:
//App:ExampleApp
//App:ExampleAppBinary
//App:ExampleAppLibrary
//App:ExampleAppAssets
//App:ExampleAppCITests
//App:ExampleWatchApp
//App:ExampleMessageExtension
//Libraries/ASwiftModule:ASwiftModule
//Libraries/Objc1:Objc1
//Libraries/SwiftAndObjc:SwiftAndObjc
//Pods:CryptoSwift
//Pods:PromiseKit
The // prefix indicates the project root. Target paths follow the format //path/to/directory:TargetName.
3

Build the application

Build the ExampleApp target:
make build
This executes:
tools/buck build //App:ExampleApp
Buck will:
  1. Parse all BUCK files and build the dependency graph
  2. Compile Swift and Objective-C source files
  3. Process resources (assets, strings, storyboards)
  4. Link libraries and create the final app bundle
Expected output:
[-] PROCESSING BUCK FILES...FINISHED 0.2s
[-] DOWNLOADING... (0.00 B/S, TOTAL: 0.00 B, 0 Artifacts)
[-] BUILDING...FINISHED 12.3s [100%]
BUILD SUCCEEDED
4

Run the app in the simulator

Build, install, and launch the app in the iOS Simulator:
make debug
This runs:
tools/buck install //App:ExampleApp --run --simulator-name 'iPhone 8'
Buck will:
  1. Build the app (if not already built)
  2. Launch the iOS Simulator
  3. Install the app on the simulator
  4. Launch the app automatically
The default simulator is iPhone 8. You can modify this in the Makefile or run Buck directly with a different simulator:
tools/buck install //App:ExampleApp --run --simulator-name 'iPhone 14 Pro'
5

Run tests

Execute the unit tests:
make test
This command runs:
tools/buck test //App:ExampleAppCITests
Expected output:
[-] PROCESSING BUCK FILES...FINISHED 0.2s
[-] BUILDING...FINISHED 3.1s [100%]
[-] TESTING...FINISHED 2.4s
TESTS PASSED (5 Passed / 0 Failed)
The test target ExampleAppCITests bundles all unit tests from the app and its libraries into a single test suite for faster CI execution.

​
Additional Commands

​
Build for Release

Build with release configuration: 
make build_release
This uses a custom Buck configuration file: 
tools/buck build //App:ExampleApp --config-file ./BuildConfigurations/Release.buckconfig

​
Build Specific Extensions

​
Watch App

make watch
Builds: 
tools/buck build //App:ExampleWatchAppExtension#watchsimulator-i386

​
iMessage Extension

make message
Builds: 
tools/buck build //App:ExampleMessageExtension

​
Clean Build Artifacts

Remove all build outputs: 
make clean
This removes:
  • Generated Xcode projects (.xcworkspace, .xcodeproj)
  • Buck build outputs (buck-out directory)

​
Working with Xcode

While Buck can build from the command line, you can also use Xcode for development.

​
Generate Xcode Project

make project
Standard project generates an Xcode project that builds natively with Xcode: 
tools/buck project //App:workspace
open App/ExampleApp-BUCK.xcworkspace
Buck Local project generates an Xcode project that invokes Buck for builds: 
bundle exec rake buck_local:generate_project \
  buck_binary_path=tools/buck \
  workspace_target='//App:workspace-buck-local' \
  top_level_lib_target='//App:ExampleAppLibrary' \
  xcworkspace='App/ExampleAppBuckLocal-BUCK.xcworkspace'
open App/ExampleAppBuckLocal-BUCK.xcworkspace
Generated Xcode projects are temporary. Regenerate them after modifying BUCK files or adding/removing source files.

​
Run Tests in Xcode

Once you’ve generated an Xcode project:
  1. Open the workspace: App/ExampleApp-BUCK.xcworkspace
  2. Select the ExampleApp scheme
  3. Press Cmd + U to run tests
You can also use breakpoints and the debugger as normal.

​
Understanding Build Targets

The ExampleApp is composed of several targets:

​
Main App Targets

  • //App:ExampleAppLibrary - Core application code (Swift/Objective-C)
  • //App:ExampleAppBinary - Application binary
  • //App:ExampleApp - Complete app bundle (binary + resources)

​
Library Targets

First-party libraries demonstrating different scenarios:
  • //Libraries/ASwiftModule:ASwiftModule - Pure Swift module
  • //Libraries/Objc1:Objc1 - Pure Objective-C module
  • //Libraries/SwiftAndObjc:SwiftAndObjc - Mixed Swift and Objective-C
  • //Libraries/SwiftWithAssets:SwiftWithAssets - Swift module with asset catalogs
  • //Libraries/SwiftWithMLModel:SwiftWithMLModel - Swift module with CoreML model

​
Third-Party Dependencies

  • //Pods:CryptoSwift - CocoaPods dependency
  • //Pods:PromiseKit - CocoaPods dependency
  • //PrebuiltFrameworks:AFNetworking - Prebuilt framework

​
Visualizing Dependencies

Buck can generate a dependency graph for any target: 
make dependency_graph
Or manually: 
tools/buck query "deps(//App:ExampleAppBinary)" --dot > result.dot
dot -Tpng result.dot -o result.png
open result.png
This creates a visual representation of all dependencies for ExampleAppBinary.
Requires Graphviz to be installed:
brew install graphviz

​
Common Workflows

​
Incremental Development

  1. Make code changes in your editor
  2. Run make build to compile
  3. Run make debug to test in simulator
  4. Run make test to verify tests pass
Buck automatically detects changes and only rebuilds affected targets. This makes incremental builds very fast.

​
Adding New Source Files

  1. Create your new .swift or .m file
  2. Add it to the appropriate BUCK file’s srcs array
  3. Rebuild with make build

​
Debugging Build Issues

If you encounter build errors:
  1. Check the error message for the failing target
  2. Verify dependencies are correctly declared in BUCK files
  3. Try a clean build: make clean && make build
  4. Check Buck’s verbose output: tools/buck build //App:ExampleApp -v 5

​
Next Steps

Now that you’ve built and run the app, explore these topics:
  • Build Targets - Learn how to define and configure Buck targets
  • Dependencies - Understand dependency management and CocoaPods integration
  • Configuration - Customize build settings and configurations
  • Testing - Set up comprehensive test suites

​
Quick Reference

CommandDescription
make install_buckInstall Buck build system
make targetsList all build targets
make buildBuild the ExampleApp
make debugBuild and run in simulator
make testRun unit tests
make projectGenerate Xcode project
make cleanClean build artifacts
tools/buck --helpShow Buck CLI help
All Makefile commands are shortcuts for Buck CLI commands. You can view the actual Buck commands in the Makefile or run Buck directly for more control.

Build docs developers (and LLMs) love

Get started for freeTalk to us