How to Build an Xcode Project from the Command Line?

If you are working on an iOS project, you probably use Xcode as your IDE. Xcode provides a graphical interface for creating, editing, debugging, and testing your app. But sometimes, you may want to build your project from the command line, for example, when you are using a continuous integration or continuous delivery (CI/CD) pipeline.

In this post, I will show you how to use xcodebuild, a set of commands that let you build an Xcode project from the terminal. You will learn about some important terms related to Xcode projects, such as workspace, target, scheme, and build configuration. You will also see how to write a simple script that automates the build process.

What Is xcodebuild?

xcodebuild is a tool that comes with Xcode and allows you to build your project from the terminal. You can use it to perform various operations on your project, such as building, running, testing, archiving, profiling, and analyzing. You can also specify different options and parameters to customize the build process.

To use xcodebuild, you need to have Xcode installed on your Mac. You can check if xcodebuild is installed by going to the terminal and issuing the following command:

xcodebuild -help

This will show you the usage and options of xcodebuild. If you find that xcodebuild is not installed, you can install it by giving this command:

xcode-select --install

This will prompt you to install the Xcode command-line tools.

Important Terms for Building an Xcode Project

Before we start using xcodebuild, we need to understand some terms that are related to an Xcode project. These terms are:

  • iOS project file: This is the main file that links everything in your project. It has the extension .xcodeproj and contains references to the source files, resources, libraries, targets, and build configurations of your project.
  • Workspace: This is a container that can hold one or more projects. It has the extension .xcworkspace and is useful when you have multiple projects that depend on each other or use external libraries such as CocoaPods. A workspace also has its own build settings and schemes.
  • Target: This defines the product that is built from your project. A project can have one or more targets, such as an app target, a test target, or an extension target. Each target has its own build settings and build phases that specify how to build the product.
  • Scheme: This defines how the operations are performed on each target. A scheme can have one or more actions, such as build, run, test, archive, profile, and analyze. Each action has its own settings and options that determine how to execute the operation.
  • Build configuration: This defines a set of build settings that apply to a specific situation. A project usually has two build configurations: Debug and Release. The Debug configuration is used for development and testing purposes, while the Release configuration is used for distribution and deployment purposes.

How to Build an Xcode Project from the Command Line?

Now that we have some basic knowledge of Xcode terms, we can start using xcodebuild to build our project from the command line.

The simplest way to build a project is to use the following command:

xcodebuild -project <path_to_project_file> -target <target_name> -configuration <configuration_name> build

This will build the specified target with the specified configuration in the specified project file.

For example, if we have a project file called MyApp.xcodeproj in our current directory, and we want to build the app target with the Debug configuration, we can use this command:

xcodebuild -project MyApp.xcodeproj -target MyApp -configuration Debug build

This will create a build folder in our current directory that contains the app executable and other files.

If we have a workspace instead of a project file, we can use the -workspace option instead of the -project option:

xcodebuild -workspace <path_to_workspace_file> -scheme <scheme_name> -configuration <configuration_name> build

This will build the scheme with the specified configuration in the specified workspace file.

For example, if we have a workspace file called MyApp.xcworkspace in our current directory, and we want to build the app scheme with the Release configuration, we can use this command:

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release build

This will create a build folder in our current directory that contains the app executable and other files.

How to Write a Script to Automate the Build Process?

If we want to automate the build process and avoid typing the same commands every time, we can write a simple script that executes xcodebuild with the desired options and parameters.

For example, we can create a file called build.sh in our project directory and write the following code:

#!/bin/bash

# Set the project or workspace file name
PROJECT_FILE="MyApp.xcodeproj"
# PROJECT_FILE="MyApp.xcworkspace"

# Set the target or scheme name
TARGET_NAME="MyApp"
# SCHEME_NAME="MyApp"

# Set the configuration name
CONFIGURATION_NAME="Debug"
# CONFIGURATION_NAME="Release"

# Set the build directory
BUILD_DIR="./build"

# Build the project or workspace
xcodebuild -project $PROJECT_FILE -target $TARGET_NAME -configuration $CONFIGURATION_NAME build -derivedDataPath $BUILD_DIR
# xcodebuild -workspace $PROJECT_FILE -scheme $SCHEME_NAME -configuration $CONFIGURATION_NAME build -derivedDataPath $BUILD_DIR

# Print a success message
echo "Build completed successfully!"

This script will build our project with the specified options and parameters and save the output in the build directory. We can modify the script according to our needs by changing the variables or adding more options.

To run the script, we need to make it executable by giving this command in the terminal:

chmod +x build.sh

Then, we can execute it by giving this command:

./build.sh

This will run xcodebuild and print a success message if everything goes well.

Here is a possible paragraph to include in the blog post:

How to Archive an Xcode Project from the Command Line?

Another operation that you may want to perform on your project is archiving. Archiving creates a bundle that contains your app executable and other files, such as symbols and dSYMs, that are useful for debugging and distribution. You can use the archive to export your app for different purposes, such as uploading to the App Store or distributing to testers.

To archive a project from the command line, you can use the following command:

xcodebuild -project <path_to_project_file> -scheme <scheme_name> -archivePath <path_to_archive_file> archive

This will archive the scheme in the project file and save it as an .xcarchive file in the specified path.

For example, if we have a project file called MyApp.xcodeproj in our current directory, and we want to archive the app scheme and save it as MyApp.xcarchive in our build directory, we can use this command:

xcodebuild -project MyApp.xcodeproj -scheme MyApp -archivePath ./build/MyApp.xcarchive archive

This will create an archive file in our build directory that contains our app executable and other files.

If we have a workspace instead of a project file, we can use the -workspace option instead of the -project option:

xcodebuild -workspace <path_to_workspace_file> -scheme <scheme_name> -archivePath <path_to_archive_file> archive

This will archive the scheme in the workspace file and save it as an .xcarchive file in the specified path.

After archiving your project, you can use the Organizer window in Xcode to view, export, or upload your archive. Alternatively, you can use other tools or scripts to perform these tasks from the command line.

How to Export Archive from the Command Line?

To export an archive from the command line, you need to use the following command:

xcodebuild -exportArchive -archivePath <path_to_archive_file> -exportPath <path_to_ipa_file> -exportOptionsPlist <path_to_export_options_plist>

This will export the archive file to an IPA file using the settings specified in the export options plist file. The export options plist file is a property list file that contains key-value pairs that control how the app is exported. You can create this file manually or use Xcode to generate one for you.

For example, if we have an archive file called MyApp.xcarchive in our build directory, and we want to export it as MyApp.ipa in our output directory, using an export options plist file called ExportOptions.plist in our project directory, we can use this command:

xcodebuild -exportArchive -archivePath ./build/MyApp.xcarchive -exportPath ./output/MyApp.ipa -exportOptionsPlist ./ExportOptions.plist

This will create an IPA file in our output directory that contains our app executable and other files.

The export options plist file can have different keys and values depending on the type of distribution you want to use. For example, if you want to export your app for App Store distribution, you need to set the method key to app-store and provide your App Store Connect credentials. If you want to export your app for Ad Hoc distribution, you need to set the method key to ad-hoc and provide your Ad Hoc provisioning profile.

Thanks for reading!