Being able to build and run Xcode projects through the CLI is a necessary skill for any iOS developer. CLI tools like xcodebuild and xcrun provide us iOS developers with a way to automate our builds and deployment process, making it more efficient and even possible to run builds on Continuous Integration (CI) servers like Jenkins or Travis CI. By integrating CLI tools into our development workflows, we can quickly test, build, and deploy apps to the appstore. Let’s take a look at some of the technical definitions and practical examples of xcodebuild.
Definitions
What’s even xcodebuild?
xcodebuild is CLI tool that can build one or more targets contained in an Xcode project, or builds a scheme contained in an Xcode workspace or Xcode project. What does that mean? Well that means that xcodebuild is generally the first option when we need to interact with an Xcode project from the terminal. With the help of this native CLI tool provided by apple, we can test, build, archive, and query for information on an Xcode project or workspace.
Available Actions - What xcodebuild can do for us
Ok we have the definitions but what’s in it for us, what actions can xcodebuild even help us perform, well let’s take a look
xcodebuild actions
build Will Build the target in the build root. This is the default build action.
archive Will Archive a scheme from the build root. This requires us to specify a scheme.
test Will Test a scheme from the build root. This requires us to specify a scheme as well.
installsrc Copy the source of the project to the source root
install Build the target and install it into the target’s installation directory in the distribution root.
clean Remove build products and intermediate files from the build root.
Available Options - What can we give to xcodebuild
For us to easily use the xcodebuild tools, we need to know what options are even available to us. Thankfully, there are several options that comes with this native CLI tool that makes our job easy. Here’s a pretty extensive list:
xcodebuild options
-project projectname
Build the project specified by projectname. This is required if there are
multiple project files in the same directory.
-target targetname
Build the target specified by targetname.
-alltargets
Build all the targets in the specified project.
-workspace workspacename
Build the workspace specified by workspacename.
-scheme schemename
Build the scheme specified by schemename. Required if building a
workspace.
-configuration configurationname
Use the build configuration specified by configurationname when
building each target.
-arch architecture
Use the architecture specified by architecture when building each
target.
-sdk [<sdkfullpath> | <sdkname>]
Build an Xcode project or workspace against the specified SDK,
using build tools appropriate for that SDK. The argument may be an
absolute path to an SDK, or the canonical name of an SDK.
-showsdks
Lists all available SDKs that Xcode knows about, including their
canonical names suitable for use with -sdk. Does not initiate a
build.
-list
Lists the targets and configurations in a project, or the schemes
in a workspace. Does not initiate a build.
Cheat Sheet - Practical Examples
Build & Run iOS App Unit & UI Tests
1
xcodebuild test -project MyCoolProjectName.xcodeproj -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest'
This will build and then run all our unit and ui tests for the specified project from the terminal as long as we are in the project’s root directory.
But what If our app uses a workspace, because we are using CocoaPods as our dependency manager, well, thankfully we have the -workspace options that we can pass in instead of the -project flag. It would look like this then:
1
xcodebuild test -workspace MyCoolProjectName.workspace -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest'
Build without Running Tests
For workspace projects
1
xcodebuild -workspace MyCoolProjectName.workspace -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest'
for regular xcodeproj
1
xcodebuild -project MyCoolProjectName.xcodeproj -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest'
Run Unit Tests Without Building Them
For workspace projects
1
xcodebuild test-without-building -workspace MyCoolProjectName.workspace -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest'
for regular xcodeproj
1
xcodebuild test-without-building -project MyCoolProjectName.xcodeproj -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest'
Run a Single Unit Test
1
xcodebuild test -project MyCoolProjectName.xcodeproj -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest' -only-testing MyCoolProjectNameTests/MyCoolProjectNameTests/testThisUnitTestToFail
Skip Selected Unit Test
1
xcodebuild test -project MyCoolProjectName.xcodeproj -scheme MyCoolProjectName -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest' -skip-testing PhotoAppTests/FormModelTests/testInvalidFirstName
Conclusion
So far, we have learned how to build and run Xcode projects from the CLI. We learned about the xcodebuild command tool and how to use it to build, and run tests, and archive our projects. We also learned about the definitions and all the options and actions available to us as iOS developers. By integrating these tools into our development workflows, we can quickly put together CI jobs and even CD process with the help of xcodebuild tool. Hopefully you found this useful.
Further Learning Resources
-
https://www.macstadium.com/blog/making-sense-of-xcodebuild-arguments
-
https://www.manpagez.com/man/1/xcodebuild/
-
https://mokacoding.com/blog/xcodebuild-destination-options/