Home

Awesome

Icon Injection Plugin for Xcode

Copyright (c) John Holdsworth 2012-19

TLDR:

Xcode is an integrated development environment (IDE) for macOS containing a suite of software development tools developed by Apple for developing software for macOS, iOS, iPadOS, watchOS, and tvOS. Injection for Xcode is an Xcode plugin (available via Alcatraz) or AppCode that dynamically inserts new Swift / Objective-C code into a running app in order to speed up your build process. It does this without making any changes to your project.

An up-to-date overview by Rob Norback of how to incorporate it into your workflow is here

This repo is no longer maintained. The current version of Injection is InjectionIII in the Mac App Store.

Injection Example

Announcements of major additions to the project will be made on twitter @Injection4Xcode.

Stop Press

If you know the trick which I won't detail here plugins still load in Xcode 8 GM and injection has been updated for it and Swift 3. Patched injection works fine and unpatched injection works if the "InjectionLoader" bundle is codesigned for the simulator. This is done in a "Run Script" build phase in this project if you need to update the code signing identity to dis-ambiguate it. Please raise issues with any problems or look at this blog. One thing I have noticed is you can no longer add methods using injection which was proably never a particularly good idea in Swift.

Stop Stop Press

Injection is now available as a standalone app rather than have to build the plugin which you can download here. As injection no longer works on the deivce due to sandboxing in iOS10 this is the recommended route going forward. For more information consult the FAQ.

For TDD, there is a interesting fork of the injection plugin you can download here. It runs all tests covering a source file each time you inject. It's on the 'tdd' branch.

How to Use Injection for Xcode

For installation and usage for AppCode see below. If you're a visual learner, you may appreciate this video post from @Orta covering the basics.

With Xcode, either install via Alcatraz, or install by cloning this repo and build InjectionPluginLite/InjectionPlugin.xcodeproj. If you are building locally, note that you need to restart Xcode to load the plugin. A popup should appear asking to confirm loading a plugin not signed by Apple, that signals that the plugin is set up.

The plugin can be removed either via Alcatraz, or by running: rm -rf ~/Library/Application\ Support/Developer/Shared/Xcode/Plug-ins/InjectionPlugin.xcplugin

Simple Proof of Concept Once Installed

Once it is installed, compile and run a project as normal. From here you should take any class that would exist when your app is loaded, add a new function - injected and add a breakpoint on that line.

- (void)injected
{
    NSLog(@"I've been injected: %@", self);
}

or

@objc func injected() {
    print("I've been injected: \(self)")
}

Then press <kbd>ctrl</kbd>+<kbd>=</kbd>, and you'll see Xcode stop at the breakpoint. You've just injected new code into a running app. Awesome right?

Callbacks in Your Code

You can build on top of Injection from three callbacks:

If you are interested in diving even deeper into callbacks, check out Tunable Parameters.

Tunable Example

Swift Support

Swift support works great when working with a collection of classes. However, there are a number of cases where re-injection won't work elegantly with Swift:

In day-to-day development against Cocoa/UIKit, it's rare, but possible to hit these cases, for more information see What Happens With Swift?

How it Works

Injection for Xcode is an extension to the Xcode IDE that allows you to patch the implementation of a class's method without having to restart the application.

It performs this by parsing the build logs of the application to determine how a source file was last compiled. With this it wraps the result of re-compiling into a bundle which is injected into the application using the dynamic loader. At this point there are two versions of a class in the app, the original and a new modified version from the bundle. The modified version is then "swizzled" onto the original class so changes take effect.

This swizzling takes advantage of the fact that Objective-C binds method invocations to implementations at run time. This can also be performed on Swift classes provided that the method or class is not final or private (i.e. the method can be overridden) by patching the class' "vtable". This excludes the injection of methods of structs.

What Else Does This Plugin Do?

What Happens with Swift?

Icon

Swift, presents a few more stumbling blocks for the uninitiated. Provided that methods are of a non final class and are non final (this excludes structs alas) they can be injected. In this example the sharedInstance variable is declared static rather than "class" to make sure it is not injected to ensure there is only ever one singleton. For the "injected" methods to work your class must inherit from NSObject.

More problematic is the more common use of variables or functions outside a class which are referred to across the files of a bundle. Swift 1.2+ takes the view these "internal" scope symbols should not be available across bundles and are made "private extern" in their object file making them unavailable at run time. This means that the above code will inject but injecting another file referring to the dispatch_on_main function will fail with obscure dynamic loading errors.

The simplest solution is to make these variables and functions public though, for a framework, this may be unsatisfactory. The alternative is to patch the object files of the project to remove the private extern flag and relink the bundle. In order to do this a script ~/bin/unhide.sh is created by the plugin build which should be called as an additional "Run Script" build phase after linking your app to perform this patch and relink.

Use with AppCode

Injection can be used from inside AppCode provided the application has been patched and you have previously injected that project from inside Xcode to set up a link to the build logs.

To install, download the jar file InjectionPluginAppCode/Injection.jar from this repo and go to AppCode preferences, choose "Install plugin from disk" and locate the .jar. Then restart the IDE. Now you will get new menu options under the Run menu. You’ll need to re-patch the project from inside AppCode as it uses a different port number to connect.

Limitations of Injection

There are limitations of course, largely centering around static variables, static or global functions and their Swift equivalents. Consider the following Objective-C code.

Icon