Class: Xcodeproj::Project

Inherits:
Object
  • Object
show all
Includes:
Object
Defined in:
lib/xcodeproj/project.rb,
lib/xcodeproj/project/object.rb,
lib/xcodeproj/project/object_list.rb,
lib/xcodeproj/project/object/group.rb,
lib/xcodeproj/project/case_converter.rb,
lib/xcodeproj/project/project_helper.rb,
lib/xcodeproj/project/uuid_generator.rb,
lib/xcodeproj/project/object/build_file.rb,
lib/xcodeproj/project/object/build_rule.rb,
lib/xcodeproj/project/object_attributes.rb,
lib/xcodeproj/project/object_dictionary.rb,
lib/xcodeproj/project/object/build_phase.rb,
lib/xcodeproj/project/object/root_object.rb,
lib/xcodeproj/project/object/native_target.rb,
lib/xcodeproj/project/object/file_reference.rb,
lib/xcodeproj/project/object/reference_proxy.rb,
lib/xcodeproj/project/object/target_dependency.rb,
lib/xcodeproj/project/object/configuration_list.rb,
lib/xcodeproj/project/object/build_configuration.rb,
lib/xcodeproj/project/object/container_item_proxy.rb,
lib/xcodeproj/project/object/helpers/groupable_helper.rb,
lib/xcodeproj/project/object/swift_package_remote_reference.rb,
lib/xcodeproj/project/object/helpers/file_references_factory.rb,
lib/xcodeproj/project/object/swift_package_product_dependency.rb,
lib/xcodeproj/project/object/helpers/build_settings_array_settings_by_object_version.rb

Overview

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 (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 Object::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.

Defined Under Namespace

Modules: Object, ProjectHelper Classes: ObjectDictionary, ObjectList, UUIDGenerator

Creating objects collapse

Instance Attribute Summary collapse

Initialization collapse

Plist serialization collapse

Creating objects collapse

Convenience accessors collapse

Helpers collapse

Schemes collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path, skip_initialization = false, object_version = Constants::DEFAULT_OBJECT_VERSION) ⇒ Project

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.

Returns a new instance of Project.

Examples:

Creating a project

Project.new("path/to/Project.xcodeproj")

Parameters:

  • path (Pathname, String) —

    @see path The path provided will be expanded to an absolute path.

  • skip_initialization (Bool) (defaults to: false) —

    Wether the project should be initialized from scratch.

  • object_version (Int) (defaults to: Constants::DEFAULT_OBJECT_VERSION) —

    Object version to use for serialization, defaults to Xcode 3.2 compatible.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# 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

Instance Attribute Details

#archive_version ⇒ String (readonly)

Returns the archive version.

Returns:

  • (String) —

    the archive version.



119
120
121
 
# File 'lib/xcodeproj/project.rb', line 119

def archive_version
  @archive_version
end

#classes ⇒ Hash (readonly)

Returns an dictionary whose purpose is unknown.

Returns:

  • (Hash) —

    an dictionary whose purpose is unknown.



123
124
125
 
# File 'lib/xcodeproj/project.rb', line 123

def classes
  @classes
end

#generated_uuids ⇒ Array<String> (readonly)

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.

Returns the list of all the generated UUIDs.

Returns:

  • (Array<String>) —

    the list of all the generated UUIDs.



465
466
467
 
# File 'lib/xcodeproj/project.rb', line 465

def generated_uuids
  @generated_uuids
end

#object_version ⇒ String (readonly)

Returns the objects version.

Returns:

  • (String) —

    the objects version.



127
128
129
 
# File 'lib/xcodeproj/project.rb', line 127

def object_version
  @object_version
end

#objects_by_uuid ⇒ Hash{String => AbstractObject} (readonly)

Returns A hash containing all the objects of the project by UUID.

Returns:

  • (Hash{String => AbstractObject}) —

    A hash containing all the objects of the project by UUID.



132
133
134
 
# File 'lib/xcodeproj/project.rb', line 132

def objects_by_uuid
  @objects_by_uuid
end

#path ⇒ Pathname (readonly)

Returns the path of the project.

Returns:

  • (Pathname) —

    the path of the project.



48
49
50
 
# File 'lib/xcodeproj/project.rb', line 48

def path
  @path
end

#project_dir ⇒ Pathname (readonly)

Returns the directory of the project.

Returns:

  • (Pathname) —

    the directory of the project



52
53
54
 
# File 'lib/xcodeproj/project.rb', line 52

def project_dir
  @project_dir
end

#root_object ⇒ PBXProject (readonly)

Returns the root object of the project.

Returns:

  • (PBXProject) —

    the root object of the project.



136
137
138
 
# File 'lib/xcodeproj/project.rb', line 136

def root_object
  @root_object
end

Class Method Details

.open(path) ⇒ Object

Opens the project at the given path.

Examples:

Opening a project

Project.open("path/to/Project.xcodeproj")

Parameters:

  • path (Pathname, String) —

    The path to the Xcode project document (xcodeproj).

Raises:

  • 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.

  • If it can’t find the root object. This means that the project is malformed.



107
108
109
110
111
112
113
114
115
 
# 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

.predictabilize_uuids(projects) ⇒ void

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.

This method returns an undefined value.

Replaces all the UUIDs in the list of provided projects with deterministic MD5 checksums.

Parameters:



412
413
414
 
# File 'lib/xcodeproj/project.rb', line 412

def self.predictabilize_uuids(projects)
  UUIDGenerator.new(projects).generate!
end

.schemes(project_path) ⇒ Array

Get list of shared schemes in project

Parameters:

  • path (String) —

    project path

Returns:

  • (Array) 


826
827
828
829
830
831
832
 
# 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

Instance Method Details

#==(other) ⇒ Boolean

TODO:

If ever needed, we could also compare ‘uuids.sort` instead.

A fast way to see if two Xcodeproj::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).

Returns:

  • (Boolean) —

    whether or not the two ‘Project` instances refer to the same projects on disk, determined solely by #path and `root_object.uuid` equality.



151
152
153
 
# File 'lib/xcodeproj/project.rb', line 151

def ==(other)
  other && path == other.path && root_object.uuid == other.root_object.uuid
end

#[](group_path) ⇒ PBXGroup

Returns a group at the given subpath relative to the main group.

Examples:

frameworks = project['Frameworks']
frameworks.name #=> 'Frameworks'
main_group.children.include? frameworks #=> True

Parameters:

  • group_path (String) —

    @see MobileCoreServices

Returns:

  • (PBXGroup) —

    the group at the given subpath.



535
536
537
 
# File 'lib/xcodeproj/project.rb', line 535

def [](group_path)
  main_group[group_path]
end

#add_build_configuration(name, type) ⇒ XCBuildConfiguration

Adds a new build configuration to the project and populates its with default settings according to the provided type.

Parameters:

  • name (String) —

    The name of the build configuration.

  • type (Symbol) —

    The type of the build configuration used to populate the build settings, must be :debug or :release.

Returns:



785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
 
# 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

#build_configuration_list ⇒ ObjectList<XCConfigurationList>

Returns The build configuration list of the project.

Returns:



636
637
638
 
# File 'lib/xcodeproj/project.rb', line 636

def build_configuration_list
  root_object.build_configuration_list
end

#build_configurations ⇒ ObjectList<XCBuildConfiguration>

Returns A list of project wide build configurations.

Returns:



643
644
645
 
# File 'lib/xcodeproj/project.rb', line 643

def build_configurations
  root_object.build_configuration_list.build_configurations
end

#build_settings(name) ⇒ Hash

Returns the build settings of the project wide build configuration with the given name.

Parameters:

  • name (String) —

    The name of a project wide build configuration.

Returns:

  • (Hash) —

    The build settings.



655
656
657
 
# File 'lib/xcodeproj/project.rb', line 655

def build_settings(name)
  root_object.build_configuration_list.build_settings(name)
end

#dirty? ⇒ Boolean

Returns Whether this project has been modified since read from disk or saved.

Returns:

  • (Boolean) —

    Whether this project has been modified since read from disk or saved.



380
381
382
 
# File 'lib/xcodeproj/project.rb', line 380

def dirty?
  @dirty == true
end

#embedded_targets_in_native_target(native_target) ⇒ Array<PBXNativeTarget>

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

Parameters:

Returns:

  • (Array<PBXNativeTarget>) —

    A list of all targets that are embedded in the passed in target



591
592
593
594
595
 
# 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

#eql?(other) ⇒ Boolean

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 Xcodeproj::Project instances refer to the same projects on disk, use the #== method instead.

Compares the project to another one, or to a plist representation.

Parameters:

  • other (#to_hash) —

    the object to compare.

Returns:

  • (Boolean) —

    whether the project is equivalent to the given object.



169
170
171
 
# File 'lib/xcodeproj/project.rb', line 169

def eql?(other)
  other.respond_to?(:to_hash) && to_hash == other.to_hash
end

#files ⇒ ObjectList<PBXFileReference>

Returns a list of all the files in the project.

Returns:



542
543
544
 
# File 'lib/xcodeproj/project.rb', line 542

def files
  objects.grep(PBXFileReference)
end

#frameworks_group ⇒ PBXGroup

Returns the ‘Frameworks` group creating it if necessary.

Returns:

  • (PBXGroup) —

    the ‘Frameworks` group creating it if necessary.



629
630
631
 
# File 'lib/xcodeproj/project.rb', line 629

def frameworks_group
  main_group['Frameworks'] || main_group.new_group('Frameworks')
end

#generate_available_uuid_list(count = 100) ⇒ void

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.

This method returns an undefined value.

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.

Parameters:

  • count (Integer) (defaults to: 100) —

    the number of UUIDs that should be generated.



480
481
482
483
484
485
 
# 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

#generate_uuid ⇒ String

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.

Generates a UUID unique for the project.

Returns:

  • (String) —

    A UUID unique to the project.



454
455
456
457
 
# File 'lib/xcodeproj/project.rb', line 454

def generate_uuid
  generate_available_uuid_list while @available_uuids.empty?
  @available_uuids.shift
end

#groups ⇒ ObjectList<PBXGroup>

Returns a list of all the groups in the project.

Returns:



520
521
522
 
# File 'lib/xcodeproj/project.rb', line 520

def groups
  main_group.groups
end

#host_targets_for_embedded_target(embedded_target) ⇒ Array<PBXNativeTarget>

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.

Parameters:

  • native (PBXNativeTarget) —

    target that might be embedded in another target

Returns:

  • (Array<PBXNativeTarget>) —

    the native targets that host the embedded target



607
608
609
610
611
612
 
# 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

#initialize_from_file ⇒ Object

Initializes the instance with the project stored in the ‘path` attribute.



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# 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
    raise "[Xcodeproj] Unknown archive version (#{archive_version.to_i})."
  end

  if object_version.to_i > Constants::LAST_KNOWN_OBJECT_VERSION
    raise "[Xcodeproj] Unknown object version (#{object_version.to_i})."
  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

#initialize_from_scratch ⇒ Object

Initializes the instance from scratch.



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# 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

#list_by_class(klass) ⇒ Array<AbstractObject>

Returns all the objects of the project with a given ISA.

Returns:

  • (Array<AbstractObject>) —

    all the objects of the project with a given ISA.



507
508
509
 
# File 'lib/xcodeproj/project.rb', line 507

def list_by_class(klass)
  objects.select { |o| o.class == klass }
end

#main_group ⇒ PBXGroup

Returns the main top-level group.

Returns:

  • (PBXGroup) —

    the main top-level group.



513
514
515
 
# File 'lib/xcodeproj/project.rb', line 513

def main_group
  root_object.main_group
end

#mark_dirty! ⇒ void

This method returns an undefined value.

Marks the project as dirty, that is, modified from what is on disk.



373
374
375
 
# File 'lib/xcodeproj/project.rb', line 373

def mark_dirty!
  @dirty = true
end

#native_targets ⇒ ObjectList<PBXNativeTarget>

Returns A list of all the targets in the project excluding aggregate targets.

Returns:



576
577
578
 
# File 'lib/xcodeproj/project.rb', line 576

def native_targets
  root_object.targets.grep(PBXNativeTarget)
end

#new(klass) ⇒ AbstractObject

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 Xcodeproj::Project::Object::AbstractObject subclasses or by this class.

Parameters:

  • klass (Class, String) —

    The concrete subclass of AbstractObject for new object or its ISA.

Returns:



433
434
435
436
437
438
439
440
 
# 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

#new_aggregate_target(name, target_dependencies = [], platform = nil, deployment_target = nil) ⇒ PBXNativeTarget

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.

Parameters:

  • name (String) —

    the name of the target.

  • target_dependencies (Array<AbstractTarget>) (defaults to: []) —

    targets, which should be added as dependencies.

  • platform (Symbol) (defaults to: nil) —

    the platform of the aggregate target. Can be ‘:ios` or `:osx`.

  • deployment_target (String) (defaults to: nil) —

    the deployment target for the platform.

Returns:



765
766
767
768
769
770
771
 
# 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

#new_file(path, source_tree = :group) ⇒ PBXFileReference

Creates a new file reference in the main group.

Parameters:

  • @see —

    PBXGroup#new_file

Returns:



670
671
672
 
# File 'lib/xcodeproj/project.rb', line 670

def new_file(path, source_tree = :group)
  main_group.new_file(path, source_tree)
end

#new_from_plist(uuid, objects_by_uuid_plist, root_object = false) ⇒ AbstractObject

Note:

This method is used to generate the root object from a plist. Subsequent invocation are called by the Xcodeproj::Project::Object::AbstractObject#configure_with_plist. Clients of Xcodeproj are not expected to call this method.

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.

Parameters:

  • uuid (String) —

    The UUID of the object that needs to be generated.

  • objects_by_uuid_plist (Hash {String => Hash}) —

    The ‘objects` hash of the plist representation of the project.

  • root_object (Boolean) (defaults to: false) —

    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.

Returns:



265
266
267
268
269
270
271
272
273
274
275
 
# 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

#new_group(name, path = nil, source_tree = :group) ⇒ PBXGroup

Creates a new group at the given subpath of the main group.

Parameters:

  • @see —

    PBXGroup#new_group

Returns:



680
681
682
 
# 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

#new_resources_bundle(name, platform, product_group = nil, product_basename = nil) ⇒ PBXNativeTarget

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

Parameters:

  • name (String) —

    the name of the resources bundle.

  • platform (Symbol) —

    the platform of the resources bundle. Can be ‘:ios` or `:osx`.

Returns:



736
737
738
739
740
 
# 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

#new_target(type, name, platform, deployment_target = nil, product_group = nil, language = nil, product_basename = nil) ⇒ PBXNativeTarget

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.

Parameters:

  • type (Symbol) —

    the type of target. Can be ‘:application`, `:framework`, `:dynamic_library` or `:static_library`.

  • name (String) —

    the name of the target product.

  • platform (Symbol) —

    the platform of the target. Can be ‘:ios` or `:osx`.

  • deployment_target (String) (defaults to: nil) —

    the deployment target for the platform.

  • product_group (PBXGroup) (defaults to: nil) —

    the product group, where to add to a file reference of the created target.

  • language (Symbol) (defaults to: nil) —

    the primary language of the target, can be ‘:objc` or `:swift`.

Returns:



715
716
717
718
719
 
# 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

#objects ⇒ Array<AbstractObject>

Returns all the objects of the project.

Returns:



494
495
496
 
# File 'lib/xcodeproj/project.rb', line 494

def objects
  objects_by_uuid.values
end

#predictabilize_uuids ⇒ void

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.

This method returns an undefined value.

Replaces all the UUIDs in the project with deterministic MD5 checksums.



395
396
397
 
# File 'lib/xcodeproj/project.rb', line 395

def predictabilize_uuids
  UUIDGenerator.new([self]).generate!
end

#pretty_print ⇒ Hash{String => Hash}

Returns A hash suitable to display the project to the user.

Returns:

  • (Hash{String => Hash}) —

    A hash suitable to display the project to the user.



335
336
337
338
339
340
341
342
 
# 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

#products ⇒ ObjectList<PBXFileReference>

Returns A list of the product file references.

Returns:



623
624
625
 
# File 'lib/xcodeproj/project.rb', line 623

def products
  products_group.children
end

#products_group ⇒ PBXGroup

Returns The group which holds the product file references.

Returns:

  • (PBXGroup) —

    The group which holds the product file references.



616
617
618
 
# File 'lib/xcodeproj/project.rb', line 616

def products_group
  root_object.product_ref_group
end

#recreate_user_schemes(visible = true) ⇒ void

This method returns an undefined value.

Recreates the user schemes of the project from scratch (removes the folder) and optionally hides them.

Parameters:

  • visible (Bool) (defaults to: true) —

    Whether the schemes should be visible or hidden.



842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
 
# 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

#reference_for_path(absolute_path) ⇒ PBXFileReference, Nil

Returns the file reference for the given absolute path.

Parameters:

  • absolute_path (#to_s) —

    The absolute path of the file whose reference is needed.

Returns:

  • (PBXFileReference) —

    The file reference.

  • (Nil) —

    If no file reference could be found.



554
555
556
557
558
559
560
561
562
563
564
 
# 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

#save(save_path = nil) ⇒ void

This method returns an undefined value.

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.

Examples:

Saving a project

project.save
project.save

Parameters:

  • path (String, Pathname) —

    The optional path where the project should be saved.



359
360
361
362
363
364
365
366
367
 
# 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

#sort(options = nil) ⇒ void

This method returns an undefined value.

Sorts the project.

Parameters:

  • options (Hash) (defaults to: nil) —

    the sorting options.

Options Hash (options):

  • :groups_position (Symbol) —

    the position of the groups can be either ‘:above` or `:below`.



810
811
812
 
# File 'lib/xcodeproj/project.rb', line 810

def sort(options = nil)
  root_object.sort_recursively(options)
end

#targets ⇒ ObjectList<AbstractTarget>

Returns A list of all the targets in the project.

Returns:



569
570
571
 
# File 'lib/xcodeproj/project.rb', line 569

def targets
  root_object.targets
end

#to_ascii_plist ⇒ Object 



291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# 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

#to_hash ⇒ Hash

Returns The hash representation of the project.

Returns:

  • (Hash) —

    The hash representation of the project.



279
280
281
282
283
284
285
286
287
288
289
 
# 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

#to_s ⇒ Object Also known as: inspect 



173
174
175
 
# File 'lib/xcodeproj/project.rb', line 173

def to_s
  "#<#{self.class}> path:`#{path}` UUID:`#{root_object.uuid}`"
end

#to_tree_hash ⇒ Hash

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.

Returns:

  • (Hash) —

    a hash representation of the project different from the plist one.



321
322
323
324
325
326
327
328
329
330
 
# 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

#uuids ⇒ Array<String>

Returns all the UUIDs of the project.

Returns:

  • (Array<String>) —

    all the UUIDs of the project.



500
501
502
 
# File 'lib/xcodeproj/project.rb', line 500

def uuids
  objects_by_uuid.keys
end