ZergXcode is a tool and library for performing automated modifications to Xcode
project files. It can be used to work around Xcode’s limitations, such as
- the cumbersome UI for assigning files to the main target vs the test target
(zerg-xcode retarget) - the impossibility to easily drop other people’s code in your project
(zerg-xcode import) - a problem that annoys you enough to learn the API and write a ruby script
If you’re on OSX Leopard, you already have most of the infrastructure in place.
Install the gem by typing the following in Terminal.
sudo gem install zerg_xcode
Stay in Terminal and take a look at the available commands.
zerg-xcode help
Then start playing with your code project.
zerg-xcode help
zerg-xcode help ls
zerg-xcode ls ProjectName
You can learn all about importing projects in
this blog post
ZergSupport is an example of a project
that you can import. You can read more about it in
this blog post
The rest of the file is useful if you’re considering tweaking the code. Here are
a few reasons to use this library:
- ruby and rubygems come pre-installed on every Mac
- full test coverage, so it’s high quality and easy to refactor
- MIT license, so your boss will not hate you
- all commands are plug-ins, so all the infrastructure is in place
It’s recommended to start by playing with the API in
lib/zerg_xcode/shortcuts.rb
moonstone:ZergSupport victor$ zerg-xcode irb ZergSupport
>> $p
*snip*
>> $p.attrs # shows the names of all the attributes of the Xcode object
=> ["isa", "buildConfigurationList", "hasScannedForEncodings", "targets", "projectDirPath", "compatibilityVersion", "projectRoot", "mainGroup"]
>> $p['targets'].first.attrs # navigates a list
=> ["name", "isa", "productType", "buildConfigurationList", "productReference", "productName", "buildRules", "dependencies", "buildPhases"]
>> $p['targets'].first['name'] # inspects attributes
=> "ZergSupport"
>> $p['targets'].map { |target| target['name'] } # more attribute inspection
=> ["ZergSupport", "ZergTestSupport", "ZergSupportTests"]
>> $p.all_files.length # call method in PBXProject
=> 116
You can up load your favorite Xcode project in irb, and understand the object
graph. Once you feel you have a decent grasp, you can start experimenting with
changing the graph, as shown below.
moonstone:ZergSupport victor$ zerg-xcode irb ZergSupport >> $p['targets'][2]['name'] => "ZergSupportTests" >> $p['targets'][2]['name'] = 'ZergSupportTestz' => "ZergSupportTestz" >> $p.save! # the project remembers where it was loaded from => 54809 >> quit # now load the project in Xcode and see the change
The set of commands accepted by the zerg-xcode tool can be extended
by adding a plug-in, which is nothing but a ruby file that exists in
lib/zerg_xcode/plugins. An easy example to get you started can be
found at lib/zerg_xcode/plugins/ls.rb. The code in there should
help you if you want to write your own command-line tool as well.
Plug-ins must implement the methods run(args) (called when the
command is executed) and help (called when the user needs help on
your plug-in), which must return a Hash with the keys :short and
:long.
If you write a plug-in that seems even remotely useful, please don’t be shy and
send a Pull Request on Github.
The code is in lib/zerg_xcode/file_format. You can safely ignore it
unless you’re handling a new file format, or you want to make the decoding
better.
A .pbxproj file is decoded by the chain Lexer → Parser → Archiver.unarchive
into an object graph. An object graph is encoded back into a .pbxproj by the
chain Archiver.archive → Encoder.
The decoding process discards comments and the order of objects in the graph, so
an encoded .pbxproj will not be the same as the original. However, Xcode will
happily open an encoded file, and that’s all that matters.
Objects in the Xcode object graph are represented by XcodeObject instances. The
code for XcodeObject is in lib/zerg_xcode/objects/xcode_object.rb.
Xcode objects use the ‘isa’ attribute to indicate their class.
XcodeObject.new implements isa-based polymorphism as follows: if
ZergXcode::Objects has a class with the same name as the ‘isa’
property, that class is instantiated instead of XcodeObject.new.
So, you can add magic methods to Xcode objects by implementing them in
XcodeObject subclasses contained in the ZergXcode::Objects module.
By convention, these classes are implemented in
lib/zerg_xcode/objects.
XcodeObject stores the attributes of the original object, and also keeps track
of subtle meta-data from the original objects, such as the object version and
archive identifier. This is done so modified Xcode files resemble the originals
as much as possible.
The test directory contains a parallel tree to
lib/zerg_xcode. Coverage must remain excellent, because this is a
tool that operates on developers’s hard work, which may not be protected by
version control.