Flags

Flags

Flags affect the configurations of each target and allow to fine control how the project gets compiled.

From version 2.0.0, flags with a single value or a list of values are treated by the exact same methods. Now the methods are smarter enough to detect that a flag is processing multiple values and turn them into a list and vice versa, when one value is left the flag turns into a single value. This make the output generated by pbxproj as close as possible to the actual output generated by Xcode itself.

All methods to add a flag have a remove counterpart. All the remove methods have the same signature as their add methods. For this reason, the remove methods are not going to be described in the sections below as will be extremely redundant.

Flags

To add a flag value, you can use the following:

project.add_flags('myflag', 'value1')
project.add_flags('myflag', 'value2')

or

project.add_flags('myflag', ['value1', 'value2'])

Both commands are equivalent.

Optional parameters:

• target_name: String, name of the target to add the flag to. If none is provided, the flags are added to all targets.
• configuration_name: String, name of the configuration to add the flag to. If none is provided, the flags are added to all configurations.

Note: notice that with target and configuration are 4 possible combinations:

• target and configuration given: just the matching combination is affected
• target but no configuration given: it will affect all configuration of the given target.
• configuration but no target given: it will affect the given configuration on all targets.
• no target and no configuration given: it will affect all configurations on all targets.

There are 2 very common kinds of flags and to reduce problems some aliases have been created.

Compiler flags

Compiler flags are passed as they are defined down to the C compiler. If you want to enable/disable or define something you have to format your flag as the compiler expects it.

project.add_other_cflags('-DDEBUG=1')

or

project.add_other_cflags(['-DDEBUG=1', '-DLOG=OFF'])

target_name and configuration_name are also accepted.

Linker flags

Linker flags are passed as they are defined to the linker. If you want to enable/disable or define something you have to format your flag as the compiler expects it.

project.add_other_ldflags('-ObjC')

or

project.add_other_ldflags(['-ObjC', '-all_load', '-fobjc-arc'])

target_name and configuration_name are also accepted.

Per-file flags

Individual build file objects returned by project.get_build_files_for_file contain a method called add_compiler_flag. Here is an example of a function which uses this to disable ARC for a specific file:

def disableArc(filePath):
    fileId = project.get_file_id_by_path(filePath)
    files = project.get_build_files_for_file(fileId)
    for f in files:
        f.add_compiler_flags('-fno-objc-arc')

disableArc('Libraries/Plugins/iOS/JSONKit.m')

Run Script

Allows to create a Run Script Phase to be executed when the target is getting built.

project.add_run_script('ls -l .')

Optional parameters:

• target_name is also accepted.
• insert_before_compile: Boolean, forces the run Script phase to be created before the compilation step. By default th run script phases are added at the end.

Search paths

Search paths allows to instruct the compiler and the linker where to find certain kinds of items (headers, frameworks and libraries)

project.add_search_paths('HEADER_SEARCH_PATHS', 'mypath')
project.add_search_paths('HEADER_SEARCH_PATHS', 'mypath2')

or

project.add_search_paths('HEADER_SEARCH_PATHS', ['mypath', 'mypath2'])

Optional parameters:

• target_name and configuration_name are also accepted.
• recursive: Boolean, indicates if the search path has to be followed recursively or not. By default is True.
• escape: Boolean, indicates that the given path should be escaped to avoid problems with the path. By default Xcode doesn't escape the paths.

As with the normal flags, some aliases are provided for simplicity

Header search paths

This allows to modify directly the headers search path flag.

project.add_header_search_paths('.')

or

project.add_header_search_paths(['.', 'headers'])

target_name, configuration_name, recursive and escape are also accepted.

Framework search paths

This allows to modify directly the framework search path flag.

project.add_framework_search_paths('.')

or

project.add_framework_search_paths(['.', 'frameworks'])

target_name, configuration_name, recursive and escape are also accepted.

Library search paths

This allows to modify directly the framework search path flag.

project.add_library_search_paths('.')

or

project.add_library_search_paths(['.', 'libraries'])

target_name, configuration_name, recursive and escape are also accepted.

Add code sign

Note: This is method currently does NOT have a remove counterpart

In xcode 8+ the provisioning_profile_uuid becomes optional, and the provisioning_profile_specifier becomes mandatory. Contrariwise, in xcode 8< provisioning_profile_uuid becomes mandatory and provisioning_profile_specifier becomes optional.

To add the code sign information to the project and creates the appropriate flags in the configuration use:

project.add_code_sign('iPhone Distribution[: <Company name> (MAAYFEXXXX)]', 
						  'MAAYFEXXXX', 
						  '6f1ffc4d-xxxx-xxxx-xxxx-6dc186280e1e', 
						  'My_provisioning_profile')

target_name and configuration_name are also accepted.