Skip to content

Files

Jump to bottom
kronenthaler edited this page Sep 29, 2019 · 8 revisions

Files are what allow Xcode to build a functional app. Xcode considers certain special folders as files, for instance, .framework and .storyboard, are just examples of "files" that can be added to Xcode.

Add files

To add new files to your project execute:

project.add_file('my folder/file.m', force=False)

This method contains the following optional parameters:

  • parent: PBXGroup object, the group reference under the file will be listed in the project. None means Project Root.
  • tree: String, indicating what filesystem should be used as a root. By default SOURCE_ROOT is used, meaning this project folder.
  • target_name: String or list of String, Target name(s) that will include the new file added. By default, the file added is included in all targets.
  • force: Boolean, adds the file without checking for its existance first. By default, files are forced to be added (backwards compatibility), but it is recommended to not add files if they already exists.
  • file_options: FileOptions object. Contains file specific flags to be consider when the file is being added.
    • create_build_files: Boolean, add this files to the build phase. By default, all files are added to the build phase.
    • weak: Boolean, link the file as a required or weak reference. Only applies to frameworks and libraries.
    • ignore_unknown_type: Boolean, when adding files that are unknown to the project an error is reported. That check can be overruled with this flag. Using this flag may lead to unexpected behaviors.
    • embed_framework: Boolean, when a framework is being added, embed the binary in the final app.
    • code_sign_on_copy: Boolean, force the framework to be code signed when copied to the final app.
    • header_scope: HeaderScope constant, allows to add headers as public or private. Use HeaderScope.PUBLIC, HeaderScope.PRIVATE or HeaderScope.PROJECT (default).

Add files with unknown extensions

Sometimes your project will be adding files with extensions that are not familiar to most xcode projects, for instance, new video or audio formats, or external components that are new Xcode's features.

In many cases, you don't need to wait for this project to add support of them. If your file only needs to be treated as a resource, or as a compiled code (e.g. it doesn't need to be added to any special project section), you can simply do the following in your project's script

ProjectFiles._FILE_TYPES[<ext>] = (<type>, <phase>)

Where:

  • ext is the extension of your file, including the .. e.g. u'.wav'
  • type is the Xcode given type. E.g. u'audio.wav'. To know exactly what type you should provide, add the file type manually in Xcode and diff against the PBXFileReference phase, lastKnownFileType entry.
  • phase is the phase where the file needs to be added to. Normally, you want to default to PBXResourcesBuildPhase and simply copy it as a resource.

You can add any amount of extra entries this way.

In cases, where the file type requires additional actions, other than simply add it to a given phase, please open an issue providing the following information:

  • A sample, blank project with no files in it.
  • A sample project with the file properly inserted by Xcode.

Add a library/framework

Libraries and Frameworks are the second most common assets added to a project. They are special files, they might have special requirements (minimum version to work, other system frameworks, etc). Also they have 2 types, system frameworks and 3rd party frameworks.

To add a system framework:

file_options = FileOptions(weak=True)
project.add_file('System/Library/Frameworks/AdSupport.framework', parent=frameworks, tree='SDKROOT', force=False, file_options=file_options)

parent can be either a group previously created/retrieved or an ID indicating the name of the group. In the example: frameworks = project.get_or_create_group('Frameworks'). Most system frameworks are under the tree SDKROOT and the relative path is System/Library/Frameworks/. System libraries reside under the SDKROOT as well but in a different path usr/lib/. For instance: usr/lib/libsqlite3.0.dylib

To add a 3rd party framework:

file_options = FileOptions(weak=True)
project.add_file('Libraries/MyFramework.framework', parent=frameworks, force=False, file_options=file_options)

parent can be either a group previously created/retrieved or an ID indicating the name of the group. In the example: frameworks = project.get_or_create_group('Frameworks'). This will look up for the framework under the tree SOURCE_ROOT a.k.a. the project folder.

Remove files by ID

You need to have the ID of the file. The ID is a string of hexadecimal of 24 characters

project.remove_file_by_id('AF62C671190997D50075DD39')

Optional parameters:

  • target_name: String or list of String, Target name(s) to remove the file from the specified target name(s) only. By default, the file is removed from all targets.

Remove files by path

You can remove files by their physical path relative to the group. For instance, imagine 'Classes/Module/Header.h', if all groups are created properly to match the physical structure, you have to delete the file using: "Header.h". Au contraire, if the groups don't match the physical structure, you have to use the real relative path: 'Module/Header.h' or 'Classes/Module/Header.h' depending on the parent group.

project.remove_files_by_path('Header.h')

Optional parameters:

  • target_name: String or list of String, Target name(s) to remove the file from the specified target name(s) only. By default, the file is removed from all targets.
  • tree: String, tree that should match the path. By default the tree is SOURCE_ROOT

Warning: if multiple files match the path all of them will be removed from the project, use the tree and target parameters to narrow the search

Add xcodeproj

Sometimes you have 2 xcode projects that depend on one another. In this cases, to simplify the compilation process, one contains the other and links to its products. In this way, only one project is open, and the compilation can happen in a single place.

With pbproj, you can add another xcodeproj file into the currently opened project with the following command:

project.add_project('path/to/project.xcodeproj', force=False)

This method contains the following optional parameters:

  • parent: PBXGroup object, the group reference under the file will be listed in the project. None means Project Root.
  • tree: String, indicating what filesystem should be used as a root. By default SOURCE_ROOT is used, meaning this project folder.
  • target_name: String or list of String, Target name(s), that will include the new file added. By default, the file added is included in all targets.
  • force: Boolean, adds the file without checking for its existance first. By default, files are forced to be added (backwards compatibility), but it is recommended to not add files if they already exists.
  • file_options: FileOptions object. Contains file specific flags to be consider when the file is being added.
    • create_build_files: Boolean, add this files to the build phase. By default, all files are added to the build phase.
    • weak: Boolean, link the file as a required or weak reference. Only applies to frameworks and libraries.
    • ignore_unknown_type: Boolean, when adding files that are unknown to the project an error is reported. That check can be overruled with this flag. Using this flag may lead to unexpected behaviors.
    • embed_framework: Boolean, when a framework is being added, embed the binary in the final app.
    • code_sign_on_copy: Boolean, force the framework to be code signed when copied to the final app.

Pbxproj will open the given project, will find the products of that project and will link any framework/library and copy any bundle product automatically. If you don't want to link/copy the products at the moment, you can use the FileOption.create_build_files set to False.

Index

Clone this wiki locally