Build Phases

Build phases define the stages by which your product is built. Three of these phases—Compile Sources, Link Binary With Libraries, and Copy Bundle Resources—are required, and others can be added as necessary. As build phases define how the target will be built, changing the build phases changes the build process.

Build Settings

Build settings define what to do at various stages of the build process, and hence provide a means of customizing this process. There are actually multiple lists of build setting values, each of which is called a build configuration. A build configuration is a named collection of build settings that are used to build a target’s product in a particular way. They provide a mechanism for building different versions of the same target. You can also create build configuration files. These enable you to easily share a set of build setting definitions across targets, projects, and among developers.

Build Configurations

A project build configuration is used to build a software product. It contains build-setting definitions. These can be embedded in an Xcode project file or stored in a separate configuration settings file. When you create a project, Xcode provides two default embedded build configurations: Debug and Release, which differ primarily in the inclusion of debug information and in the degree to which the build is optimized. The Debug configuration is typically used throughout the development process, whereas the Release configuration is used for late-stage testing, when you want to check performance on a device. Several of the build settings for the Debug configuration are shown in Listing B-1.

Listing B-1.  Debug Build Configuration Settings

ONLY_ACTIVE_ARCH=YES
CONFIGURATION_BUILD_DIR=build/Debug
COPY_PHASE_STRIP=NO
GCC_OPTIMIZATION_LEVEL=0
GCC_PREPROCESSOR_DEFINITIONS=DEBUG=1

A configuration settings file is a plain text file that specifies a list of build-setting definitions, one per line. If you are creating a new build configuration from an existing one, it must be based only on a configuration file that is in your project, not an external file.

Build Rules

Build rules provide instructions for processing files on a per-target basis. Xcode provides a set of default build rules, and you can add your own custom build rules to perform custom processing for specific file types.

Build rules specify how particular types of files are processed and which tool is used to process files during build phases. Each build rule consists of a condition and an action. The condition, which usually specifies a file type, determines whether a source file is processed with the associated action.

Xcode provides default build rules that process a variety of file types, including C-based files (such as Objective-C files) and assembly files. You can add custom build rules to process other types of files to each target. These are added in the Build Rules pane of the editor window, as shown in Figure B-1. Build rules are processed in the order they appear in the Rules pane.

Creating a Configuration Settings File

In this example, you will use Xcode to create a plain-text build configuration settings file for a project.

1. In Xcode, create a new project by selecting New Project … from the Xcode File menu.
2. In the New Project Assistant pane, create a command-line application.
3. In the Project Options window specify ConfigSettingsProject for the Product Name, choose Foundation for the Project Type, and select ARC memory management by selecting the Use Automatic Reference Counting check box.
4. Specify the location in your file system where you want the project to be created (if necessary select New Folder and enter the name and location for the folder), uncheck the Source Control check box, and then click the Create button.
5. Now you will create the configuration settings file. Select New File … from the Xcode File menu and select the Configuration Settings File template from the Other option under OS X (as shown in Figure B-2).

   

   Figure B-2. Selecting a configuration settings file

6. Name the file Test, select the ConfigSettingsProject folder for the files location and the ConfigSettingsProject project as the target, and then click the Create button.
7. This creates an empty configuration settings file named Test.xconfig. Now update this file to support code coverage during testing. This is accomplished by setting the configuration flags to Enable test coverage and Instrument program flow.

   GCC_GENERATE_TEST_COVERAGE_FILES=YES
   GCC_INSTRUMENT_PROGRAM_FLOW_ARCS=YES

8. In Xcode, select and update the Test.xconfig file, as shown in Figure B-3.

   

   Figure B-3. Edit the configuration settings file to support code coverage

Now you need to add the settings from the file to the current build configuration for the project.

1. In the Xcode project navigator, select the ConfigSettingsProject, and then the ConfigSettingsProject in the Project Editor, and finally the Info tab in the Editor window. Note that the Debug configuration (under Configurations in the Editor window) has no configurations set.
2. Click the arrow next to Debug to display the ConfigSettingsProject, and then under the configuration file drop-down list select Test (as shown in Figure B-4) to update the Debug configuration settings with the values in the Test.xconfig file.

The settings for the debug configuration have now been updated. You can check this by viewing the updated build settings for test coverage (see Figure B-5).

The Xcode Build Setting Reference provides a comprehensive reference for the various build settings available for Xcode.

Adding an Existing Project to a Workspace

In Xcode, perform the following steps to add an existing project to a workspace:

1. In the project navigator, Control-click in the empty space below the projects in the list. In the pop-up menu that follows, select Add Files to “<WorkspaceName>”…, where WorkspaceName is the name of the workspace.
2. Navigate to the folder containing the corresponding Xcode project file (it ends with .xcodeproj).
3. Select the project file and click Add.

The project is now part of the workspace, and thus its contents can be shared with other projects in the workspace.

Using Static Libraries in a Workspace

Now you will learn how to incorporate static libraries into a workspace. Briefly, the steps you will perform are as follows:

1. Create workspace.
2. Create static library.
3. Create app.

With those steps completed, your static library is properly configured. Now let’s create the app.

Creating the App

Now you will create the application that uses the static library.

1. In Xcode, create a new project by selecting New Project … from the Xcode File menu.
2. In the New Project Assistant pane, create a command-line application by selecting the Command Line Tool icon (from the Application selection under OS X template groups).
3. In the Project Options window, specify HelloApp for the Product Name, choose Foundation for the Project Type, and select ARC memory management by checking the Use Automatic Reference Counting check box. Specify the location in your file system where you want the project to be created (if necessary, select New Folder and enter the name and location for the folder) and uncheck the Source Control check box.
4. Finally, select HelloSpace in the Add to: and Group: drop-down lists (to add this library to the HelloSpace workspace), and then click the Create button.

The first thing you’ll do is link the app against the static library.

1. Select the HelloApp project in the project navigator, and then select the HelloApp target in the project editor.
2. Select the Build Phases tab, disclose the Link Binaries With Libraries phase, and click the plus (+) button.
3. In the window, choose libHelloLib.a and click Add to add the library.

Next you’ll update build configuration settings to link the library:

1. Select the Build Settings tab.
2. Find the Other Linker Flags build setting (using the search tool) and add the flag

-ObjC to this setting’s value, if not present (as shown in Figure B-11).

The -ObjC flag will tell the linker to link all Objective-C classes and categories from static libraries into your application, even if the linker can’t tell that they are used (e.g., categories and/or classes added dynamically).

Now you need to import the header file for the static library.

The build products for all the projects in a workspace are located in the workspace build directory. Earlier, you copied the HelloLib.h header file into the Products Directory include directory. This directory is automatically included in the search path for all projects in the workspace. Because you specified a subdirectory named after the PRODUCT_NAME build setting (e.g., include/${PRODUCT_NAME}) in the subpath, the import statement should include that directory, for example:

#import "HelloLib/HelloLib.h"

OK, now you will add the code to the app to demonstrate use of the static library. In the project navigator, select the main.m file for the HelloApp and make the updates shown in Listing B-4.

Listing B-4.  HelloApp main() Function

#import <Foundation/Foundation.h>
#import "HelloLib/HelloLib.h"

int main(int argc, const char * argv[])
{
  @autoreleasepool
  {
    HelloLib *hello = [HelloLib new];
    NSLog(@"%@", [hello greeting:@"Hello"]);
  }
  return 0;
}

The header file for the HelloLib static library is imported with the statement.

#import "HelloLib/HelloLib.h"

The main() function creates a HelloLib instance and invokes its greeting: method. When you compile and run the program, you should observe the messages in the output pane shown in Figure B-12.

Cool. This demonstrates how to incorporate static libraries into your projects using Xcode workspaces. The same techniques apply for other reusable software libraries (dynamic libraries, frameworks, bundles, etc.).