class Xcodeproj::Project
This class represents a Xcode project document.
It can be used to manipulate existing documents or even create new ones from scratch.
An Xcode project document is a plist file where the root is a dictionary containing the following keys:
-
archiveVersion: the version of the document.
-
objectVersion: the version of the objects description.
-
classes: a key that apparently is always empty.
-
objects: a dictionary where the UUID of every object is associated to its attributes.
-
rootObject: the UUID identifier of the root object ({PBXProject}).
Every object is in turn a dictionary that specifies an ‘isa` (the class of the object) and in accordance to it maintains a set attributes. Those attributes might reference one or more other objects by UUID. If the reference is a collection, it is ordered.
The {Project} API returns instances of {AbstractObject} which wrap the objects described in the Xcode project document. All the attributes types are preserved from the plist, except for the relationships which are replaced with objects instead of UUIDs.
An object might be referenced by multiple objects, an when no other object is references it, it becomes unreachable (the root object is referenced by the project itself). Xcodeproj
takes care of adding and removing those objects from the ‘objects` dictionary so the project is always in a consistent state.
Attributes
@return [String] the archive version.
@return [Hash] an dictionary whose purpose is unknown.
@return [Array<String>] the list of all the generated UUIDs.
@note Used for checking new UUIDs for duplicates with UUIDs already
generated but used for objects which are not yet part of the `objects` hash but which might be added at a later time.
@return [String] the objects version.
@return [Hash{String => AbstractObject}] A hash containing all the
objects of the project by UUID.
@return [Pathname] the path of the project.
@return [Pathname] the directory of the project
@return [PBXProject] the root object of the project.
Public Class Methods
@param [Pathname, String] path @see path
The path provided will be expanded to an absolute path.
@param [Bool] skip_initialization
Wether the project should be initialized from scratch.
@param [Int] object_version
Object version to use for serialization, defaults to Xcode 3.2 compatible.
@example Creating a project
Project.new("path/to/Project.xcodeproj")
@note When initializing the project, Xcodeproj
mimics the Xcode behaviour
including the setup of a debug and release configuration. If you want a clean project without any configurations, you should override the `initialize_from_scratch` method to not add these configurations and manually set the object version.
# File lib/xcodeproj/project.rb, line 70 def initialize(path, skip_initialization = false, object_version = Constants::DEFAULT_OBJECT_VERSION) @path = Pathname.new(path).expand_path @project_dir = @path.dirname @objects_by_uuid = {} @generated_uuids = [] @available_uuids = [] @dirty = true unless skip_initialization.is_a?(TrueClass) || skip_initialization.is_a?(FalseClass) raise ArgumentError, '[Xcodeproj] Initialization parameter expected to ' \ "be a boolean #{skip_initialization}" end unless skip_initialization initialize_from_scratch @object_version = object_version.to_s unless Constants::COMPATIBILITY_VERSION_BY_OBJECT_VERSION.key?(object_version) raise ArgumentError, "[Xcodeproj] Unable to find compatibility version string for object version `#{object_version}`." end root_object.compatibility_version = Constants::COMPATIBILITY_VERSION_BY_OBJECT_VERSION[object_version] end end
Opens the project at the given path.
@param [Pathname, String] path
The path to the Xcode project document (xcodeproj).
@raise If the project versions are more recent than the ones know to
Xcodeproj to prevent it from corrupting existing projects. Naturally, this would never happen with a project generated by xcodeproj itself.
@raise If it can’t find the root object. This means that the project is
malformed.
@example Opening a project
Project.open("path/to/Project.xcodeproj")
# File lib/xcodeproj/project.rb, line 107 def self.open(path) path = Pathname.pwd + path unless Pathname.new(path).exist? raise "[Xcodeproj] Unable to open `#{path}` because it doesn't exist." end project = new(path, true) project.send(:initialize_from_file) project end
Replaces all the UUIDs in the list of provided projects with deterministic MD5 checksums.
@param [Array<Project>] projects
@note The current sorting of the project is taken into account when
generating the new UUIDs.
@note This method should only be used for entirely machine-generated
projects, as true UUIDs are useful for tracking changes in the project.
@return [void]
# File lib/xcodeproj/project.rb, line 412 def self.predictabilize_uuids(projects) UUIDGenerator.new(projects).generate! end
Get list of shared schemes in project
@param [String] path
project path
@return [Array]
# File lib/xcodeproj/project.rb, line 826 def self.schemes(project_path) schemes = Dir[File.join(project_path, 'xcshareddata', 'xcschemes', '*.xcscheme')].map do |scheme| File.basename(scheme, '.xcscheme') end schemes << File.basename(project_path, '.xcodeproj') if schemes.empty? schemes end
Public Instance Methods
A fast way to see if two {Project} instances refer to the same projects on disk. Use this over {#eql?} when you do not need to compare the full data.
This shallow comparison was chosen as the (common) ‘==` implementation, because it was too easy to introduce changes into the Xcodeproj
code-base that were slower than O(1).
@return [Boolean] whether or not the two ‘Project` instances refer to the
same projects on disk, determined solely by {#path} and `root_object.uuid` equality.
@todo If ever needed, we could also compare ‘uuids.sort` instead.
# File lib/xcodeproj/project.rb, line 151 def ==(other) other && path == other.path && root_object.uuid == other.root_object.uuid end
Returns a group at the given subpath relative to the main group.
@example
frameworks = project['Frameworks'] frameworks.name #=> 'Frameworks' main_group.children.include? frameworks #=> True
@param [String] group_path @see MobileCoreServices
@return [PBXGroup] the group at the given subpath.
# File lib/xcodeproj/project.rb, line 535 def [](group_path) main_group[group_path] end
Adds a new build configuration to the project and populates its with default settings according to the provided type.
@param [String] name
The name of the build configuration.
@param [Symbol] type
The type of the build configuration used to populate the build settings, must be :debug or :release.
@return [XCBuildConfiguration] The new build configuration.
# File lib/xcodeproj/project.rb, line 785 def add_build_configuration(name, type) build_configuration_list = root_object.build_configuration_list if build_configuration = build_configuration_list[name] build_configuration else build_configuration = new(XCBuildConfiguration) build_configuration.name = name common_settings = Constants::PROJECT_DEFAULT_BUILD_SETTINGS settings = ProjectHelper.deep_dup(common_settings[:all]) settings.merge!(ProjectHelper.deep_dup(common_settings[type])) build_configuration.build_settings = settings build_configuration_list.build_configurations << build_configuration build_configuration end end
@return [ObjectList<XCConfigurationList>] The build configuration list of
the project.
# File lib/xcodeproj/project.rb, line 636 def build_configuration_list root_object.build_configuration_list end
@return [ObjectList<XCBuildConfiguration>] A list of project wide
build configurations.
# File lib/xcodeproj/project.rb, line 643 def build_configurations root_object.build_configuration_list.build_configurations end
Returns the build settings of the project wide build configuration with the given name.
@param [String] name
The name of a project wide build configuration.
@return [Hash] The build settings.
# File lib/xcodeproj/project.rb, line 655 def build_settings(name) root_object.build_configuration_list.build_settings(name) end
@return [Boolean] Whether this project has been modified since read from
disk or saved.
# File lib/xcodeproj/project.rb, line 380 def dirty? @dirty == true end
Checks the native target for any targets in the project that are dependent on the native target and would be embedded in it at build time
@param [PBXNativeTarget] native target to check for
embedded targets
@return [Array<PBXNativeTarget>] A list of all targets that
are embedded in the passed in target
# File lib/xcodeproj/project.rb, line 591 def embedded_targets_in_native_target(native_target) native_targets.select do |target| host_targets_for_embedded_target(target).any? { |host| host.uuid == native_target.uuid } end end
Compares the project to another one, or to a plist representation.
@note This operation can be extremely expensive, because it converts a
`Project` instance to a hash, and should _only_ ever be used to determine wether or not the data contents of two `Project` instances are completely equal. To simply determine wether or not two {Project} instances refer to the same projects on disk, use the {#==} method instead.
@param [#to_hash] other the object to compare.
@return [Boolean] whether the project is equivalent to the given object.
# File lib/xcodeproj/project.rb, line 169 def eql?(other) other.respond_to?(:to_hash) && to_hash == other.to_hash end
@return [ObjectList<PBXFileReference>] a list of all the files in the
project.
# File lib/xcodeproj/project.rb, line 542 def files objects.grep(PBXFileReference) end
@return [PBXGroup] the ‘Frameworks` group creating it if necessary.
# File lib/xcodeproj/project.rb, line 629 def frameworks_group main_group['Frameworks'] || main_group.new_group('Frameworks') end
Pre-generates the given number of UUIDs. Useful for optimizing performance when the rough number of objects that will be created is known in advance.
@param [Integer] count
the number of UUIDs that should be generated.
@note This method might generated a minor number of uniques UUIDs than
the given count, because some might be duplicated a thus will be discarded.
@return [void]
# File lib/xcodeproj/project.rb, line 480 def generate_available_uuid_list(count = 100) new_uuids = (0..count).map { SecureRandom.hex(12).upcase } uniques = (new_uuids - (@generated_uuids + uuids)) @generated_uuids += uniques @available_uuids += uniques end
Generates a UUID unique for the project.
@note UUIDs are not guaranteed to be generated unique because we need
to trim the ones generated in the xcodeproj extension.
@note Implementation detail: as objects usually are created serially
this method creates a batch of UUID and stores the not colliding ones, so the search for collisions with known UUIDS (a performance bottleneck) is performed less often.
@return [String] A UUID unique to the project.
# File lib/xcodeproj/project.rb, line 454 def generate_uuid generate_available_uuid_list while @available_uuids.empty? @available_uuids.shift end
@return [ObjectList<PBXGroup>] a list of all the groups in the
project.
# File lib/xcodeproj/project.rb, line 520 def groups main_group.groups end
Returns the native targets, in which the embedded target is embedded. This works by traversing the targets to find those where the target is a dependency.
@param [PBXNativeTarget] native target that might be embedded
in another target
@return [Array<PBXNativeTarget>] the native targets that host the
embedded target
# File lib/xcodeproj/project.rb, line 607 def host_targets_for_embedded_target(embedded_target) native_targets.select do |native_target| ((embedded_target.uuid != native_target.uuid) && (native_target.dependencies.map(&:native_target_uuid).include? embedded_target.uuid)) end end
Initializes the instance with the project stored in the ‘path` attribute.
# File lib/xcodeproj/project.rb, line 209 def initialize_from_file pbxproj_path = path + 'project.pbxproj' plist = Plist.read_from_path(pbxproj_path.to_s) root_object.remove_referrer(self) if root_object @root_object = new_from_plist(plist['rootObject'], plist['objects'], self) @archive_version = plist['archiveVersion'] @object_version = plist['objectVersion'] @classes = plist['classes'] || {} @dirty = false unless root_object raise "[Xcodeproj] Unable to find a root object in #{pbxproj_path}." end if archive_version.to_i > Constants::LAST_KNOWN_ARCHIVE_VERSION UI.warn "[Xcodeproj] Archive version (#{archive_version.to_i}) is higher than the latest supported by xcodeproj (#{Constants::LAST_KNOWN_ARCHIVE_VERSION})." end if object_version.to_i > Constants::LAST_KNOWN_OBJECT_VERSION UI.warn "[Xcodeproj] Xcode project version (#{object_version.to_i}) is higher than the latest supported by xcodeproj (#{Constants::LAST_KNOWN_OBJECT_VERSION})." end # Projects can have product_ref_groups that are not listed in the main_groups["Products"] root_object.product_ref_group ||= root_object.main_group['Products'] || root_object.main_group.new_group('Products') end
Initializes the instance from scratch.
# File lib/xcodeproj/project.rb, line 186 def initialize_from_scratch @archive_version = Constants::LAST_KNOWN_ARCHIVE_VERSION.to_s @classes = {} root_object.remove_referrer(self) if root_object @root_object = new(PBXProject) root_object.add_referrer(self) root_object.main_group = new(PBXGroup) root_object.product_ref_group = root_object.main_group.new_group('Products') config_list = new(XCConfigurationList) root_object.build_configuration_list = config_list config_list.default_configuration_name = 'Release' config_list.default_configuration_is_visible = '0' add_build_configuration('Debug', :debug) add_build_configuration('Release', :release) new_group('Frameworks') end
@return [Array<AbstractObject>] all the objects of the project with a
given ISA.
# File lib/xcodeproj/project.rb, line 507 def list_by_class(klass) objects.select { |o| o.class == klass } end
@return [PBXGroup] the main top-level group.
# File lib/xcodeproj/project.rb, line 513 def main_group root_object.main_group end
Marks the project as dirty, that is, modified from what is on disk.
@return [void]
# File lib/xcodeproj/project.rb, line 373 def mark_dirty! @dirty = true end
@return [ObjectList<PBXNativeTarget>] A list of all the targets in the
project excluding aggregate targets.
# File lib/xcodeproj/project.rb, line 576 def native_targets root_object.targets.grep(PBXNativeTarget) end
Creates a new object with a suitable UUID.
The object is only configured with the default values of the ‘:simple` attributes, for this reason it is better to use the convenience methods offered by the {AbstractObject} subclasses or by this class.
@param [Class, String] klass
The concrete subclass of AbstractObject for new object or its ISA.
@return [AbstractObject] the new object.
# File lib/xcodeproj/project.rb, line 433 def new(klass) if klass.is_a?(String) klass = Object.const_get(klass) end object = klass.new(self, generate_uuid) object.initialize_defaults object end
Creates a new target and adds it to the project.
The target is configured for the given platform and its file reference it is added to the {products_group}.
The target is pre-populated with common build settings, and the appropriate Framework according to the platform is added to to its Frameworks phase.
@param [String] name
the name of the target.
@param [Array<AbstractTarget>] target_dependencies
targets, which should be added as dependencies.
@param [Symbol] platform
the platform of the aggregate target. Can be `:ios` or `:osx`.
@param [String] deployment_target
the deployment target for the platform.
@return [PBXNativeTarget] the target.
# File lib/xcodeproj/project.rb, line 765 def new_aggregate_target(name, target_dependencies = [], platform = nil, deployment_target = nil) ProjectHelper.new_aggregate_target(self, name, platform, deployment_target).tap do |aggregate_target| target_dependencies.each do |dep| aggregate_target.add_dependency(dep) end end end
Creates a new file reference in the main group.
@param @see PBXGroup#new_file
@return [PBXFileReference] the new file.
# File lib/xcodeproj/project.rb, line 670 def new_file(path, source_tree = :group) main_group.new_file(path, source_tree) end
Creates a new object from the given UUID and ‘objects` hash (of a plist).
The method sets up any relationship of the new object, generating the destination object(s) if not already present in the project.
@note This method is used to generate the root object
from a plist. Subsequent invocation are called by the {AbstractObject#configure_with_plist}. Clients of {Xcodeproj} are not expected to call this method.
@param [String] uuid
The UUID of the object that needs to be generated.
@param [Hash {String => Hash}] objects_by_uuid_plist
The `objects` hash of the plist representation of the project.
@param [Boolean] root_object
Whether the requested object is the root object and needs to be retained by the project before configuration to add it to the `objects` hash and avoid infinite loops.
@return [AbstractObject] the new object.
@visibility private.
# File lib/xcodeproj/project.rb, line 265 def new_from_plist(uuid, objects_by_uuid_plist, root_object = false) attributes = objects_by_uuid_plist[uuid] if attributes klass = Object.const_get(attributes['isa']) object = klass.new(self, uuid) objects_by_uuid[uuid] = object object.add_referrer(self) if root_object object.configure_with_plist(objects_by_uuid_plist) object end end
Creates a new group at the given subpath of the main group.
@param @see PBXGroup#new_group
@return [PBXGroup] the new group.
# File lib/xcodeproj/project.rb, line 680 def new_group(name, path = nil, source_tree = :group) main_group.new_group(name, path, source_tree) end
Creates a new resource bundles target and adds it to the project.
The target is configured for the given platform and its file reference it is added to the {products_group}.
The target is pre-populated with common build settings
@param [String] name
the name of the resources bundle.
@param [Symbol] platform
the platform of the resources bundle. Can be `:ios` or `:osx`.
@return [PBXNativeTarget] the target.
# File lib/xcodeproj/project.rb, line 736 def new_resources_bundle(name, platform, product_group = nil, product_basename = nil) product_group ||= products_group product_basename ||= name ProjectHelper.new_resources_bundle(self, name, platform, product_group, product_basename) end
Creates a new target and adds it to the project.
The target is configured for the given platform and its file reference it is added to the {products_group}.
The target is pre-populated with common build settings, and the appropriate Framework according to the platform is added to to its Frameworks phase.
@param [Symbol] type
the type of target. Can be `:application`, `:framework`, `:dynamic_library` or `:static_library`.
@param [String] name
the name of the target product.
@param [Symbol] platform
the platform of the target. Can be `:ios` or `:osx`.
@param [String] deployment_target
the deployment target for the platform.
@param [PBXGroup] product_group
the product group, where to add to a file reference of the created target.
@param [Symbol] language
the primary language of the target, can be `:objc` or `:swift`.
@return [PBXNativeTarget] the target.
# File lib/xcodeproj/project.rb, line 715 def new_target(type, name, platform, deployment_target = nil, product_group = nil, language = nil, product_basename = nil) product_group ||= products_group product_basename ||= name ProjectHelper.new_target(self, type, name, platform, deployment_target, product_group, language, product_basename) end
@return [Array<AbstractObject>] all the objects of the project.
# File lib/xcodeproj/project.rb, line 494 def objects objects_by_uuid.values end
Replaces all the UUIDs in the project with deterministic MD5 checksums.
@note The current sorting of the project is taken into account when
generating the new UUIDs.
@note This method should only be used for entirely machine-generated
projects, as true UUIDs are useful for tracking changes in the project.
@return [void]
# File lib/xcodeproj/project.rb, line 395 def predictabilize_uuids UUIDGenerator.new([self]).generate! end
@return [Hash{String => Hash}] A hash suitable to display the project
to the user.
# File lib/xcodeproj/project.rb, line 335 def pretty_print build_configurations = root_object.build_configuration_list.build_configurations { 'File References' => root_object.main_group.pretty_print.values.first, 'Targets' => root_object.targets.map(&:pretty_print), 'Build Configurations' => build_configurations.sort_by(&:name).map(&:pretty_print), } end
@return [ObjectList<PBXFileReference>] A list of the product file
references.
# File lib/xcodeproj/project.rb, line 623 def products products_group.children end
@return [PBXGroup] The group which holds the product file references.
# File lib/xcodeproj/project.rb, line 616 def products_group root_object.product_ref_group end
Recreates the user schemes of the project from scratch (removes the folder) and optionally hides them.
@param [Bool] visible
Whether the schemes should be visible or hidden.
@return [void]
# File lib/xcodeproj/project.rb, line 842 def recreate_user_schemes(visible = true) schemes_dir = XCScheme.user_data_dir(path) FileUtils.rm_rf(schemes_dir) FileUtils.mkdir_p(schemes_dir) xcschememanagement = {} xcschememanagement['SchemeUserState'] = {} xcschememanagement['SuppressBuildableAutocreation'] = {} targets.each do |target| scheme = XCScheme.new test_target = target if target.respond_to?(:test_target_type?) && target.test_target_type? launch_target = target.respond_to?(:launchable_target_type?) && target.launchable_target_type? scheme.configure_with_targets(target, test_target, :launch_target => launch_target) yield scheme, target if block_given? scheme.save_as(path, target.name, false) xcschememanagement['SchemeUserState']["#{target.name}.xcscheme"] = {} xcschememanagement['SchemeUserState']["#{target.name}.xcscheme"]['isShown'] = visible end xcschememanagement_path = schemes_dir + 'xcschememanagement.plist' Plist.write_to_path(xcschememanagement, xcschememanagement_path) end
Returns the file reference for the given absolute path.
@param [#to_s] absolute_path
The absolute path of the file whose reference is needed.
@return [PBXFileReference] The file reference. @return [Nil] If no file reference could be found.
# File lib/xcodeproj/project.rb, line 554 def reference_for_path(absolute_path) absolute_pathname = Pathname.new(absolute_path) unless absolute_pathname.absolute? raise ArgumentError, "Paths must be absolute #{absolute_path}" end objects.find do |child| child.isa == 'PBXFileReference' && child.real_path == absolute_pathname end end
Serializes the project in the xcodeproj format using the path provided during initialization or the given path (‘xcodeproj` file). If a path is provided file references depending on the root of the project are not updated automatically, thus clients are responsible to perform any needed modification before saving.
@param [String, Pathname] path
The optional path where the project should be saved.
@example Saving a project
project.save project.save
@return [void]
# File lib/xcodeproj/project.rb, line 359 def save(save_path = nil) save_path ||= path @dirty = false if save_path == path FileUtils.mkdir_p(save_path) file = File.join(save_path, 'project.pbxproj') Atomos.atomic_write(file) do |f| Nanaimo::Writer::PBXProjWriter.new(to_ascii_plist, :pretty => true, :output => f, :strict => false).write end end
Sorts the project.
@param [Hash] options
the sorting options.
@option options [Symbol] :groups_position
the position of the groups can be either `:above` or `:below`.
@return [void]
# File lib/xcodeproj/project.rb, line 810 def sort(options = nil) root_object.sort_recursively(options) end
@return [ObjectList<AbstractTarget>] A list of all the targets in the
project.
# File lib/xcodeproj/project.rb, line 569 def targets root_object.targets end
# File lib/xcodeproj/project.rb, line 291 def to_ascii_plist plist = {} objects_dictionary = {} objects .sort_by { |o| [o.isa, o.uuid] } .each do |obj| key = Nanaimo::String.new(obj.uuid, obj.ascii_plist_annotation) value = obj.to_ascii_plist.tap { |a| a.annotation = nil } objects_dictionary[key] = value end plist['archiveVersion'] = archive_version.to_s plist['classes'] = classes plist['objectVersion'] = object_version.to_s plist['objects'] = objects_dictionary plist['rootObject'] = Nanaimo::String.new(root_object.uuid, root_object.ascii_plist_annotation) Nanaimo::Plist.new.tap { |p| p.root_object = plist } end
@return [Hash] The hash representation of the project.
# File lib/xcodeproj/project.rb, line 279 def to_hash plist = {} objects_dictionary = {} objects.each { |obj| objects_dictionary[obj.uuid] = obj.to_hash } plist['objects'] = objects_dictionary plist['archiveVersion'] = archive_version.to_s plist['objectVersion'] = object_version.to_s plist['classes'] = classes plist['rootObject'] = root_object.uuid plist end
# File lib/xcodeproj/project.rb, line 173 def to_s "#<#{self.class}> path:`#{path}` UUID:`#{root_object.uuid}`" end
Converts the objects tree to a hash substituting the hash of the referenced to their UUID reference. As a consequence the hash of an object might appear multiple times and the information about their uniqueness is lost.
This method is designed to work in conjunction with {Hash#recursive_diff} to provide a complete, yet readable, diff of two projects not affected by differences in UUIDs.
@return [Hash] a hash representation of the project different from the
plist one.
# File lib/xcodeproj/project.rb, line 321 def to_tree_hash hash = {} objects_dictionary = {} hash['objects'] = objects_dictionary hash['archiveVersion'] = archive_version.to_s hash['objectVersion'] = object_version.to_s hash['classes'] = classes hash['rootObject'] = root_object.to_tree_hash hash end
@return [Array<String>] all the UUIDs of the project.
# File lib/xcodeproj/project.rb, line 500 def uuids objects_by_uuid.keys end