Mastering xctool: Building and Testing Xcode Projects (with examples)

xctool is a command-line tool for building and testing Xcode projects, proving especially useful for developers looking to automate and streamline the build process. Initially developed by Facebook, it provides an alternative to xcodebuild by offering better results presentation and more advanced testing capabilities. While newer tools have emerged, xctool remains a helpful utility for legacy systems and projects.

Use case 1: Building a Single Project Without Any Workspace

Code:

xctool -project YourProject.xcodeproj -scheme YourScheme build

Motivation:

Building a single project without a workspace is particularly useful when you are working on a standalone app or library that doesn’t require external dependencies managed by a workspace. This use case represents a straightforward scenario where you want to compile and link your project’s code to ensure everything is set up correctly and functions as expected.

Explanation:

• -project YourProject.xcodeproj: Specifies the .xcodeproj file to build. This file contains the project settings and references to your source files.
• -scheme YourScheme: Defines the scheme to use for building. Schemes are essential in Xcode as they determine which project configurations, such as build targets, are used.
• build: The action to be performed. This command helps transform the source code in your project into a compiled application.

Example Output:

=== BUILD TARGET YourProject OF PROJECT YourProject WITH CONFIGURATION Debug ===
    Check dependencies
    CompileC build/YourProject.build/Debug/YourProject.build/Objects-normal/arm64/main.o YourProject/main.m normal arm64 objective-c com.apple.compilers.llvm.clang.1_0.compiler
    ...
** BUILD SUCCEEDED **

Use case 2: Building a Project That Is Part of a Workspace

Code:

xctool -workspace YourWorkspace.xcworkspace -scheme YourScheme build

Motivation:

When multiple projects are interdependent within an Xcode workspace, building a single project may not suffice. Utilizing a workspace ensures all projects and dependencies are accounted for during the build process. This approach is particularly useful when your app relies on multiple libraries or modules that are all managed within the same workspace.

Explanation:

• -workspace YourWorkspace.xcworkspace: Specifies the workspace file, which includes multiple projects and their interdependencies.
• -scheme YourScheme: Selects the build scheme, just like in a single project, but now it applies within the context of the workspace.
• build: Instructs xctool to compile and link all necessary parts of the projects within the workspace.

Example Output:

=== BUILD AGGREGATE TARGET WorkspaceDependencies OF PROJECT YourWorkspaceProject WITH CONFIGURATION Release ===
    Check dependencies
    ...
    PhaseScriptExecution [CP] Check Pods Manifest.lock build/YourWorkspace.build/Release/WorkspaceDependencies.build/Script-XXXXXXXX.sh
** BUILD SUCCEEDED **

Use case 3: Clean, Build, and Execute All the Tests

Code:

xctool -workspace YourWorkspace.xcworkspace -scheme YourScheme clean build test

Motivation:

Running a clean build followed by tests is crucial for ensuring that the compiled application is not influenced by stale binary files and is free of errors. This approach is often employed before releasing an app to catch potential issues early on. Cleaning the build clears cached data and intermediary build artifacts, while testing verifies application logic and behavior.

Explanation:

• -workspace YourWorkspace.xcworkspace: Defines the workspace context, ensuring all project dependencies are included.
• -scheme YourScheme: Determines which build configuration and test suites to execute.
• clean: Removes any previous build artifacts. It’s important to start from a clean state to avoid potential dependencies on outdated files.
• build: Compiles and links the source files from scratch.
• test: Executes all tests associated with the scheme, providing feedback on the current state of the codebase.

Example Output:

=== CLEAN TARGET YourApp OF PROJECT YourWorkspaceProject WITH CONFIGURATION Debug ===
    Clean.Remove clean build/YourApp.build/Debug-iphonesimulator/YourApp.build
    ...
=== BUILD TARGET YourApp OF PROJECT YourWorkspaceProject WITH CONFIGURATION Debug ===
    ...
Test Suite 'YourAppTests' started at ...
✅ All tests passed

Conclusion

xctool remains a valuable tool for developers managing Xcode projects, particularly those involving complex dependencies and testing requirements. Whether building a single project or coordinating across an entire workspace, xctool offers clear and actionable logging which is beneficial for both continuous integration setups and individual development environments.