
原文:How To Create an Xcode Plugin: Part 1/3
原作者:Derek Selander
譯者:@yohunl
譯者按:原文基於 Xcode 6.3.2,我翻譯時用的是 Xcode 7.2.1,經實測文中所述依然有效。跟完這一系列,你能收穫不少實用技能,非常值得一讀。
蘋果「一套方案打天下」的策略,讓它的產品越來越像一顆難以下嚥的藥丸。儘管蘋果已經為 iOS/OS X 開發者提供了不少工作流,但我們仍然希望能通過插件讓 Xcode 變得更順手。
雖然蘋果沒有提供任何官方文檔指導我們創建插件,但開發者社區已經做了大量工作,誕生了許多好用的工具。從自動補全圖片名、清理緩存,到把 Xcode 變成 vim 編輯器,插件社區極大地拓寬了我們的想象空間。
在這個分為三部分的教程裡,你將動手做一個用來「惡搞」同事的 Xcode 插件,看點就是——顯示出來的內容並不是他預期的樣子!別看插件輕量,你卻能學到很多:如何通過調試 Xcode 找到感興趣的元素並修改它,如何用 swizzle 技術把系統函數替換成自己的函數等等。
你會用到 x86 匯編知識、代碼注入技巧以及 LLDB 調試能力去翻閱未公開的私有 framework,探索其中的私有 API,並通過 method swizzling 完成代碼注入。內容不少,所以講解節奏會偏快。開始之前,請確認你已具備紮實的 iOS/OS X 開發基礎。
用 Swift 開發插件目前仍是個比較複雜的話題,加上 Swift 的調試工具遠不如 Objective-C 成熟。因此就目前而言,插件開發的最佳選擇(也就是本教程)依然是 Objective-C。
開始
為了慶祝「惡搞同事日」,你的插件會給受害者來一次 Rayrolling。等等,什麼是 Rayrolling?它是一段免費且無版權的雷人擺動——你所看到的並非你所期待,有點掛羊頭賣狗肉的意味。完成本系列後,你的插件將把 Xcode 的顯示內容改成:
用 Ray 的頭像替換 Xcode 的某些警示框(比如 Build 成功或失敗的提示框)

把 Xcode 的標題內容替換成 Ray 的名曲 Never Gonna Give You Up 中的一句歌詞

把 Xcode 中所有搜索文檔的內容替換成一段 Rayroll 視頻

第一部分我們聚焦於:找到負責展示「Build 成功」警示框的那個類,並把它的圖標改成 Ray 的頭像。
安裝插件管理器 Alcatraz
開始之前,需要先安裝 Xcode 插件管理工具 Alcatraz。典型方式是通过命令行安装:
curl -fsSL https://raw.github.com/supermarin/Alcatraz/master/Scripts/install.sh | sh
命令執行完後重啟 Xcode。你可能會看到一個關於 Alcatraz bundle 的提示框,點擊 Load Bundle 繼續,Xcode 才能加載 Alcatraz 插件使其生效。

注意:如果你不小心點了 "skip bundle",可以通過以下命令讓它重新出現!
defaults delete com.apple.dt.Xcode DVTPlugInManagerNonApplePlugIns-Xcode-7.2.1
其中的 Xcode 7.2.1 是你機器上的 Xcode 版本號,若不同,改成對應的即可。
你會在 Xcode 的 Window 菜單下看到新菜單項:Package Manager。創建插件需要通過設置 Build Settings 來啟動另一個新的 Xcode 實例加以加載,這是個枯燥的過程(想了解細節可參考我的《Xcode7 插件製作入門》),好在已有人替你搞定——有人開發了一個 Xcode 工程模板,讓創建插件工程變得輕鬆。
打開 Alcatraz(Window → Package Manager),在搜索框輸入 Xcode Plugin,務必確保選中了 All 和 Templates 兩個選項。搜到後,點擊左側的 Install 安裝它!

如果搜不到也沒關係,你可以前往 Xcode-Plugin-Template 自行下載並按工程說明安裝。
一旦 Alcatraz 下載完畢,你就可以創建插件工程了(File → New → Project…),選擇新的 OS X → Xcode Plugin → Xcode Plugin 模板,點擊下一步。

給工程取名 Rayrolling,組織標識符填 com.raywenderlich(這步很重要),語言選 Objective-C,保存到你喜歡的目錄。

Hello World 插件模板
編譯並運行 Rayroll 工程,你會看到一個新的 Xcode 實例彈出。這個實例在 Edit 菜單欄下多了一個菜單項 Do Action:

選擇它,會彈出一個模態框:

從 Xcode 5 起,插件只能在特定版本的 Xcode 中運行。這意味著每次 Xcode 更新後,所有第三方插件都會失效,除非你補上該版本的 UUID。如果模板沒生效、菜單項也沒出現,很可能就是缺了對應版本的 UUID,需要手動添加支持。
添加 UUID 的第一步,在命令行運行:
defaults read /Applications/Xcode.app/Contents/Info DVTPlugInCompatibilityUUID
這條命令會輸出當前版本 Xcode 的 UUID。打開 Rayroll 工程的 Info.plist,定位到 DVTPlugInCompatibilityUUID,把它加進去。

注意:接下來你會運行並修改已安裝的插件,這會改變 Xcode 的默認行為,甚至可能導致 Xcode 崩潰!若想禁用某個插件,可以通過終端手動刪除:
cd ~/Library/Application\ Support/Developer/Shared/Xcode/Plug-ins/ rm -r Rayrolling.xcplugin/
然後重啟 Xcode 即可。
定位要修改的 Xcode 特性
窺探幕後最直接有效的方式,是註冊一個 NSNotification 觀察者來監聽所有 Xcode 事件。通過監聽這些通知,你就能深入某些內部類的內部。
打開 Rayrolling.m,在類中添加如下屬性:
@property (nonatomic, strong) NSMutableSet *notificationSet;
這個集合用來存儲所有 Xcode 控制台打印出來的通知名。
接著,在 initWithBundle: 中 if (self = [super init]) { 之後,添加:
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(handleNotification:)
name:nil
object:nil];
self.notificationSet = [NSMutableSet new];給 name 傳 nil,表示我們要監聽 Xcode 的所有 NSNotification。
現在實現 handleNotification: 方法:
- (void)handleNotification:(NSNotification *)notification {
if (![self.notificationSet containsObject:notification.name]) {
NSLog(@"%@, %@", notification.name, [notification.object class]);
[self.notificationSet addObject:notification.name];
}
}該方法會檢查通知名是否已記錄過,若沒有則打印它的名稱與對應類,然後加入集合。這樣每種類型的通知你只會看到一次。
接著找到添加菜單項的聲明,替換成:
NSMenuItem *actionMenuItem = [[NSMenuItem alloc] initWithTitle:@"Reset Logger"
action:@selector(doMenuAction)
keyEquivalent:@""];這裡只是改了菜單標題,提醒你點擊它會重置存放通知的集合。
最後把 doMenuAction 的實現替換為:
- (void)doMenuAction {
[self.notificationSet removeAllObjects];
}這個菜單項會清空 notificationSet,目的是讓你在控制台裡不被重複消息刷屏,能更專注地觀察感興趣的通知。
再次編譯運行,請務必分清哪個是你工程的 Xcode(父 Xcode),哪個是調試出來的 Xcode 實例(子 Xcode)。因為每次改動重新調試後,子 Xcode 裡已生效,而父 Xcode 得等你重啟後才能看到效果。
在子 Xcode 裡隨便點點按鈕、開開窗口、瀏覽程序,你會在父 Xcode 的控制台看到通知被觸發。
查找並監測編譯提示框
現在你已學會查看 Xcode 自身發出的通知,接下來要精確找出顯示編譯狀態提示框所關聯的類。
運行插件,在子 Xcode 中打開任意工程,確保開啟了設置中的 bezel notifications,Succeeds 和 Fails 的選項都要打開。當然,請再次確認你操作的是子 Xcode 實例!

用菜單項 Reset Logger 重置集合,然後在子 Xcode 裡編譯運行剛打開的工程。
當子 Xcode 的編譯結果出來後(成功失敗都行),留意父 Xcode 控制台的輸出,粗略瀏覽一遍,看有沒有能引起你注意的通知。下面幾項值得進一步關注:
NSWindowWillOrderOffScreenNotification,DVTBezelAlertPanel
NSWindowDidOrderOffScreenNotification,DVTBezelAlertPanel
NSWindowDidOrderOffScreenAndFinishAnimatingNotification,DVTBezelAlertPanel

挑其中一個深入探索。比如 NSWindowWillOrderOffScreenNotification 是幹什麼的?很好,就選它。
回到父 Xcode 的 Rayrolling.m,定位到 handleNotification: 方法,在第一行加一個斷點,並這樣設置:

右鍵點擊斷點,選擇 Edit Breakpoint
在 Condition 輸入框中填入 [notification.name isEqualToString:@"NSWindowWillOrderOffScreenNotification"]
在 Action 部分添加 po notification.object
若父 Xcode 正在運行,重新 debug 啟動,然後在子 Xcode 中再編譯運行一個工程。父 Xcode 的斷點應會停在該通知處,觀察控制台輸出的 -[notification object] 值 DVTBezelAlertPanel——這正是第一個值得深挖的私有類。
現在你知道有個類叫 DVTBezelAlertPanel,更重要的是,你知道內存中存在它的實例。遺憾的是,你找不到任何頭文件來確認它是否就是顯示 Xcode 警示框的那個類。
但其實信息還是可以拿到的。儘管沒有頭文件,可你有調試器連著子 Xcode,內存中的信息足以像讀頭文件那樣告訴你這個類的相關情況。
注意:本系列中 LLDB 的輸出通常伴隨標準控制台輸出。凡是以 (lldb) 打頭的行代表輸入行;三個點…表示控制台輸出太多而被省略。若打印過多,可按 Cmd+K 清屏並重新接收輸出。
確保父 Xcode 處於調試狀態並停在斷點,向父 Xcode 的 LLDB 控制台輸入:
(lldb) image lookup -rn DVTBezelAlertPanel 17 matches found in /Applications/Xcode.app/Contents/SharedFrameworks/DVTKit.framework/Versions/A/DVTKit: ...(此處省略大量輸出)
這條命令會搜索所有加載進 Xcode 進程的 frameworks、libraries、plugins,查找名為 DVTBezelAlertPanel 的類並輸出結果。觀察列出的方法,你能否找到一些能把 DVTBezelAlertPanel 和編譯成功/失敗警示框關聯起來的方法?下面這些方法值得進一步探索:
initWithIcon:message:parentWindow:duration:
initWithIcon:message:controlView:duration:
controlView
上述兩個初始化方法中的任意一個,基本都能幫你驗證 DVTBezelAlertPanel 與提示框內容的關聯。
注意:LLDB 的 image lookup 命令只列出內存中「自己實現了」的方法,不包含那些繼承自父類但子類未重寫的方法。
確保仍停在父 Xcode 的斷點,輸入以下命令檢測 controlView:
(lldb) po [notification.object controlView] [nil]
控制台輸出 nil——可能是此刻 contentView 尚未初始化。沒關係,我們試下一個:initWithIcon:message:parentWindow:duration: 和 initWithIcon:message:controlView:duration:。既然內存中已存在 DVTBezelAlertPanel 的實例,說明這兩個初始化方法已被調用過。由於沒有實現文件,我們用 LLDB 控制台來添加斷點,然後再次觸發該類的初始化。
父 Xcode 仍停在斷點,輸入:
(lldb) rb 'DVTBezelAlertPanel initWithIcon:message:' Breakpoint 2: 4 locations. (lldb) br l ...
這個正則表達式斷點會給上面兩個初始化方法都加上斷點,因為它們有相同的起始字符。別忘了空格前的反斜槓 \,並用單引號 ' 包住整個表達式,這樣 LLDB 才知道如何解析。
切換到子 Xcode,重新編譯(Cmd+B)。父 Xcode 將會命中 initWithIcon:message:parentWindow:duration: 斷點。

如果沒命中,檢查一下斷點是不是設在了父 Xcode(設在子 Xcode 當然沒用),以及是否在子 Xcode 中編譯了工程。由於找不到源碼文件,Xcode 會把斷點停在方法的匯編代碼中。
現在,你在沒有源代碼的情況下斷點進入了一個方法,需要一個方式打印傳入的參數。是時候聊聊……匯編了。

匯編之旅
面對私有 API 時,你要做的往往是分析寄存器(registers),而非像有源碼時那樣依賴調試符號。了解 x86-64 架構下寄存器的行為,會給你帶來很大幫助。
以下寄存器及其工作方式值得關注:
$rdi:傳入方法的 self,也是第一個傳遞的參數。
$rsi:Selector,傳入的第二個參數。
$rdx:第三個參數,也就是我們在 Objective-C 中看到的「第一個」參數(因為 self 和 Selector 是隱含的)。
$rcx:第四個參數,即 Objective-C 中看到的第二個參數。
$r8:第五個參數;若需更多,$r9 將作為第六個參數的棧幀。
$rax:存放函數返回值。例如執行完 -[aClass description] 後,$rax 會存放該對象的描述字符串。
注意:以上並非絕對。某些二進制會用不同寄存器存放不同類型參數,比如 double 用 $xmm 寄存器組,這裡僅作快速參考。
下面用一個例子把理論落到實踐:
@interface aClass : NSObject
- (NSString *)aMethodWithMessage:(NSString *)message;
@end
@implementation aClass
- (NSString *)aMethodWithMessage:(NSString *)message {
return [NSString stringWithFormat:@"Hey the message is: %@", message];
}
@end執行:
aClass *aClassInstance = [[aClass alloc] init]; [aClassInstance aMethodWithMessage:@"Hello World"];
編譯後,對 aMethodWithMessage 的調用會被 Runtime 轉為對 objc_msgSend 的調用,大致如下:
objc_msgSend(aClassInstance, @selector(aMethodWithMessage:), @"Hello World")
調用前,寄存器內容為:
$rdi:存放 aClass 的實例
$rsi:存放 SEL 類型的 aMethodWithMessage:(本質是 char *,可用 po (SEL)$rsi 驗證)
$rdx:包含傳入的 message,此處為 @"Hello World"
調用結束後:
$rax:存放返回值 NSString,此例為 @"Hey the message is: Hello World"
x86 寄存器實戰
有了這份寄存器指南,是时候重新审视 DVTBezelAlertPanel 的初始化方法了。希望你的父 Xcode 斷點還停在該方法;若不是,重新運行子 Xcode 再次命中即可。記住,你在尋找把 DVTBezelAlertPanel 和編譯提示框關聯起來的線索。
斷點停在 initWithIcon:message:parentWindow:duration: 處時,在 LLDB 控制台輸入:
(lldb) re re
這是 register read 的縮寫,用來輸出當前可見的重要寄存器內容。運用你學到的 x86 寄存器知識,找出哪個寄存器存放 message 參數(也就是 objc_msgSend 的第四個參數),看看它是否就是我們期待的提示框內容。
沒錯,你應該查看 $rcx,它的內容正是 message 參數,也就是顯示在編譯提示框裡的信息。
進一步深入:
(lldb) po $rcx Build Failed
注意:Xcode 輸出寄存器內容默認採用 AT&T 匯編格式,這種格式中源操作數與目標操作數位置是相反的(先源後目標,從左到右),與 Intel 格式正好相反。
看來這就是我們要找的寄存器!試著把 $rcx 的內容改成一個新字符串,看提示框內容是否改變:
(lldb) po [$rcx class] __NSCFConstantString (lldb) po id $a = @"Womp womp!"; (lldb) p/x $a (id) $a = 0x000061800203faa0 (lldb) re w $rcx 0x000061800203faa0 (lldb) c
程序恢復運行,注意觀察編譯提示框的內容是否變成了你修改的字符串。它確實變了,這也驗證了我們的假設——DVTBezelAlertPanel 正是用來顯示該提示信息的類。
代碼注入(Injection)
找到目標類後,我們通過代碼注入來擴展 DVTBezelAlertPanel 的行為,在提示框中展示可愛的 Rayrolling 頭像,採用 method swizzling 技術。
你可能要 swizzle 來自多個類的大量方法,因此最佳做法是創建一個 NSObject 的 category,在其中提供一個便捷方法來統一建立所有 swizzle 邏輯。
在 Xcode 中選擇 File → New → File…,再選 OS X → Source → Objective-C File,命名為 MethodSwizzler,形式選 NSObject 的 category。
打開 NSObject+MethodSwizzler.m,替換為:
#import "NSObject+MethodSwizzler.h" #import@implementation NSObject (MethodSwizzler) + (void)swizzleWithOriginalSelector:(SEL)originalSelector swizzledSelector:(SEL)swizzledSelector isClassMethod:(BOOL)isClassMethod { Class cls = [self class]; Method originalMethod; Method swizzledMethod; if (isClassMethod) { originalMethod = class_getClassMethod(cls, originalSelector); swizzledMethod = class_getClassMethod(cls, swizzledSelector); } else { originalMethod = class_getInstanceMethod(cls, originalSelector); swizzledMethod = class_getInstanceMethod(cls, swizzledSelector); } if (!originalMethod) { NSLog(@"Error: originalMethod is nil, did you spell it incorrectly? %@", originalMethod); return; } method_exchangeImplementations(originalMethod, swizzledMethod); } @end
關鍵代碼已加序號,逐條解釋:
引入 method swizzle 所需的頭文件
isClassMethod 指示方法是實例方法還是類方法
沒有編譯器提示時很容易拼錯方法名,這段用來檢查拼寫是否正確
關鍵函數,用來交換兩個方法的實現
在 NSObject+MethodSwizzler.h 中添加聲明:
#import@interface NSObject (MethodSwizzler) + (void)swizzleWithOriginalSelector:(SEL)originalSelector swizzledSelector:(SEL)swizzledSelector isClassMethod:(BOOL)isClassMethod; @end
接著完成實際的 swizzle。新建一個名為 Rayrolling_DVTBezelAlertPanel 的 NSObject category,把 NSObject+Rayrolling_DVTBezelAlertPanel.m 替換為:
#import@interface NSObject () - (id)initWithIcon:(id)arg1 message:(id)arg2 parentWindow:(id)arg3 duration:(double)arg4; @end @implementation NSObject (Rayrolling_DVTBezelAlertPanel) + (void)load { static dispatch_once_t onceToken; dispatch_once(&onceToken, ^{ [NSClassFromString(@"DVTBezelAlertPanel") swizzleWithOriginalSelector:@selector(initWithIcon:message:parentWindow:duration:) swizzledSelector:@selector(Rayrolling_initWithIcon:message:parentWindow:duration:) isClassMethod:NO]; }); } - (id)Rayrolling_initWithIcon:(id)icon message:(id)message parentWindow:(id)window duration:(double)duration { NSLog(@"Swizzle success! %@", self); return [self Rayrolling_initWithIcon:icon message:message parentWindow:window duration:duration]; } @end
逐條分析:
引入 swizzling 頭文件
前向聲明所有要用到的方法,雖非必須,但能獲得代碼補全並消除警告
這是你實際要 swizzle 的方法
因為不想重新聲明私有類,改用 category 的方式
load 是觸發代碼注入的地方。它是唯一「一對多」的方法——多個 category 都有 load,都能被執行
load 可能被多次執行,用 dispatch_once 確保只跑一次
把前面聲明的方法 swizzle 成自己的實現,並用 NSClassFromString 動態獲取內存中的類
這是你用來取代原方法的方法,建議採用獨特命名,一眼就知道用途
打印確認 swizzle 成功
因為已 swizzle 了原方法,調用 [self Rayrolling_initWithIcon:...] 時實際會執行原方法,這意味著你可以在原方法執行前後插入任意代碼,甚至修改傳入的參數
恭喜,你已成功把代碼注入到了一個私有類的私有方法中!編譯父 Xcode,然後在子 Xcode 中編譯運行一個工程,查看父 Xcode 控制台,看是否成功 swizzle:
Swizzle success! [DVTBezelAlertPanel: 0x11e42d300]
接下來,就可以把編譯成功/失敗提示框的圖標替換成 Rayrolling 頭像了。下載頭像資源並加入工程,記得勾選 Copy Items if Needed。
導航到 Rayrolling_initWithIcon:message:parentWindow:duration:,改為:
- (id)Rayrolling_initWithIcon:(id)arg1 message:(id)arg2 parentWindow:(id)arg3 duration:(double)arg4 {
if (arg1) {
NSBundle *bundle = [NSBundle bundleWithIdentifier:@"com.raywenderlich.Rayrolling"];
NSImage *newImage = [bundle imageForResource:@"IDEAlertBezel_Generic_Rayrolling.pdf"];
return [self Rayrolling_initWithIcon:newImage message:arg2 parentWindow:arg3 duration:arg4];
}
return [self Rayrolling_initWithIcon:arg1 message:arg2 parentWindow:arg3 duration:arg4];
}該方法先檢查是否傳入了圖片參數,若有則替換成自定義圖片。注意:這裡用 [NSBundle bundleWithIdentifier:@"com.raywenderlich.Rayrolling"] 加載圖片,因為 Xcode 的 MainBundle 並不包含我們的資源。
重新編譯父 Xcode,再在子 Xcode 中編譯一個工程,你就能看到效果。

添加開關與持久化
這個插件是用來娛樂的,所以你需要一個開關來控制它是否生效,並用 NSUserDefaults 持久化保存狀態。
導航到 Rayrolling.h,添加:
+ (BOOL)isEnabled;
在 Rayrolling.m 中添加:
+ (BOOL)isEnabled {
return [[NSUserDefaults standardUserDefaults] boolForKey:@"com.raywenderlich.Rayrolling.shouldbeEnable"];
}
+ (void)setIsEnabled:(BOOL)shouldBeEnabled {
[[NSUserDefaults standardUserDefaults] setBool:shouldBeEnabled forKey:@"com.raywenderlich.Rayrolling.shouldbeEnable"];
}有了持久化邏輯,接下來把它關聯到 GUI。回到 Rayrolling.m,把 doMenuAction 改為:
- (void)doMenuAction:(NSMenuItem *)menuItem {
[Rayrolling setIsEnabled:![Rayrolling isEnabled]];
menuItem.title = [Rayrolling isEnabled] ? @"Disable Rayrolling" : @"Enable Rayrolling";
}這是一個用來切換啟用/禁用的布爾值。
最後,修改 didApplicationFinishLaunchingNotification: 中的菜單項初始化:
NSMenuItem *menuItem = [[NSApp mainMenu] itemWithTitle:@"Edit"];
if (menuItem) {
[[menuItem submenu] addItem:[NSMenuItem separatorItem]];
NSString *title = [Rayrolling isEnabled] ? @"Disable Rayrolling" : @"Enable Rayrolling";
NSMenuItem *actionMenuItem = [[NSMenuItem alloc] initWithTitle:title
action:@selector(doMenuAction:)
keyEquivalent:@""];
[actionMenuItem setTarget:self];
[[menuItem submenu] addItem:actionMenuItem];
}這樣即使 Xcode 重啟,你的啟用狀態也會被保留,因為選擇已持久化。
導航到 NSObject+Rayrolling_DVTBezelAlertPanel.m,添加一行:
#import "Rayrolling.h"
最後打開 Rayrolling_initWithIcon:message:parentWindow:duration:,把 if (arg1) { 替換為 if ([Rayrolling isEnabled] && arg1) {,構建並運行以更新插件行為。
至此,你做出了一個能改變 Xcode 編譯成功/失敗提示框圖標與內容、且可自由開關的插件。這一天的工作成果相當不錯,不是嗎?
接下來做什麼?
你可以下載完整的 demo 工程。你已取得了很大進展,但仍有不少可學!本系列第二部分,你將學習 DTrace 基礎,並深入 LLDB 的一些高級特性,比如查找正在運行的進程(如 Xcode 進程)。
若想更進一步,在進入第三部分(會有大量匯編代碼)之前,建議先了解 x86_64 匯編知識。Mike Ash 有兩篇介紹匯編的系列文章,能給你提供不少幫助。