• Stars
    star
    1,832
  • Rank 25,329 (Top 0.5 %)
  • Language Objective-C++
  • License
    MIT License
  • Created over 10 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Trace Objective-C method calls by class or instance

Icon Xtrace

Note: This project has been superseeded by the more rigourous SwiftTrace.

Trace Objective-C method calls by class or instance

Xtrace is a header Xtrace.h and a C++ implementation file Xtrace.mm that allows you to intercept all method calls to instances of a class or a particular instance giving you output such as this:

   [<UILabel 0x8d4f170> setCenter:{240, 160}] v16@0:4{CGPoint=ff}8
	[<UILabel 0x8d4f170> actionForLayer:<CALayer 0x8d69410> forKey:<__NSCFString 0x8a535e0>] @16@0:4@8@12
	 [<UILabel 0x8d4f170> _shouldAnimatePropertyWithKey:<__NSCFString 0x8a535e0>] c12@0:4@8
	 -> 1 (_shouldAnimatePropertyWithKey:)
	-> <NSNull 0x194d068> (actionForLayer:forKey:)
  [<UILabel 0x8d4f170> window] @8@0:4
  -> <UIWindow 0x8a69920> (window)
  [<UILabel 0x8d4f170> _isAncestorOfFirstResponder] c8@0:4
  -> 0 (_isAncestorOfFirstResponder)
 [<UILabel 0x8d4f170> layoutSublayersOfLayer:<CALayer 0x8d69410>] v12@0:4@8
  [<UILabel 0x8d4f170> _viewControllerToNotifyOnLayoutSubviews] @8@0:4
   [<UILabel 0x8d4f170> _viewDelegate] @8@0:4
   -> <nil 0x0> (_viewDelegate)

To use, add Xtrace.{h,mm} to your project and add an import of Xtrace.h to your project's ".pch" file so you can access its methods from anywhere in your project. There is a simple category based shortcut interface to start tracing:

	[MyClass xtrace]; // to trace all calls to instances of a class
	// this will intercept all methods of any superclasses as well
    // but only for instances of the class that has been traced (v2.1)
	
	[instance xtrace]; // to trace all calls to a particular instance.
	// multiple instances can by traced, use "notrace" to stop tracing
    // instance tracing takes precedence over class based filtering.

    [Xtrace traceBundleContainingClass:myClass];
    // trace your entire app's classes or those of an embedded framework
    
    [Xtrace traceClassPattern:@"^UI" excluding:nil]; // trace all of UIkit

If you have the XcodeColors plugin installed you can now color traces by selector, class or group of classes:

Icon

As an alternative to building Xtrace into your project, Xtrace is now included in the "code injection" plugin from injectionforxcode.com. Once you have injected, all xtrace methods are available for you to use in lldb.

(lldb) p [UITableView xtrace]

// dump pseudo-header for class
(lldb) p [UITableView xdump]
@interface UITableView : UIScrollView {
    id<UITableViewDataSource> _dataSource; // @"<UITableViewDataSource>"
    UITableViewRowData * _rowData; // @"UITableViewRowData"
    float _rowHeight; // f
    float _sectionHeaderHeight; // f
    float _sectionFooterHeight; // f
    float _estimatedRowHeight; // f
    float _estimatedSectionHeaderHeight; // f
    float _estimatedSectionFooterHeight; // f
    CGRect _visibleBounds; // {CGRect="origin"{CGPoint="x"f"y"f}"size"{CGSize="width"f"height"f}}
...

The example project, originally called "Xray" will show you how to use the Xtrace module to get up and running. Your milage will vary though the source should build and work for 32 bit configurations on an iOS device or 64 bit OS X applications or the simulator. The starting point is the XRAppDelegate.m class. The XRDetailViewController.m then switches to instance viewing of a specific UILabel when the detail view loads.

Display of method arguments is now on by default, but if you have problems:

[Xtrace showArguments:NO];

You can display the calling function on entry by setting:

[Xtrace showCaller:YES];

You should also be able to switch to log the "description" of all values using:

[Xtrace describeValues:YES];

Other features are a method name filtering regular expression. These filters are applied as the class is "swizzled" when you request tracing.

[Xtrace includeMethods:@"a|regular|expression"];
[Xtrace excludeMethods:@"WithObjects:$"]; // varargs methods don't work
[Xtrace excludeTypes:@"CGRect|CGSize"]; // stack frame problems on 64 bits
[Xtrace excludeTypes:nil]; // reset filter after class is set up.

Classes can also be excluded (again before other classes are traced) by calling:

[UIView notrace]; // or alternatively..
[Xtrace dontTrace:[UIView class]];

A rudimentary profiling interface is also available:

[Xtrace dumpProfile:100 dp:6]; // top 100 elapsed time to 6 decimal places

1.318244/2    [UIApplication sendAction:to:from:forEvent:]
0.725028/2    [UIWindow sendEvent:]
0.706975/2    [UIWindow _sendTouchesForEvent:]
0.701802/1    [UIControl touchesEnded:withEvent:]
0.699627/2    [UIControl _sendActionsForEvents:withEvent:]
0.659325/1    [UIControl sendAction:to:forEvent:]
0.659292/1    [UIApplication sendAction:toTarget:fromSender:forEvent:]
0.659204/1    [UIBarButtonItem _sendAction:withEvent:]
0.659082/1    [UIViewController _toggleEditing:]
0.659071/1    [UITableViewController setEditing:animated:]
0.593577/53   [CALayer layoutSublayers]
0.592025/53   [UIView layoutSublayersOfLayer:]
...

Aspect oriented features

Finally, callbacks can also be registered on a delegate to be called before or after any method is called:

[Xtrace setDelegate:delegate]; // delegate must not be traced itself
[Xtrace forClass:[UILabel class] after:@selector(setText:) callback:@selector(label:setText:)];

// void method signature for UILabel
- (void)setText:(NSString *)text;

// "before" and "after" callback implementation in delegate
- (void)label:(id)receiver setText:(NSString *)text {
    ...
}

Callbacks for specific methods can be used independently of full Class or instance tracing. "after" callbacks for methods that return a value can replace the value returned to the caller something like a variation on "aspect oriented programming".

// non-void method signature in class "AClass"
- (NSString *)appendString:(NSString *)string;

// code to inject "after" method callback
[Xtrace forClass:[AClass class] after:@selector(appendString:) callback:@selector(out:object:appendString:)];

// "after" callback implementation in delegate
- (NSString *)out:(NSString *)originalReturnValue object:(id)receiver appendString:(NSString *)string {
    ...
    return newReturnValue; // could be originalReturnValue
}

The callback selector names are arbitrary. It's the order and type of arguments that is critical. Expect some trouble passing structs on 64 bit builds. The signature for intercepting a "getter" is a little contrived:

// setup callback
[Xtrace forClass:[UILabel class] after:@selector(text) callback:@selector(out:labelText:)];

// implementation of callback
- (NSString *)out:(NSString *)text labelText:(UILabel *)label {
    ...
    return text;
}

There is also a block based api for callbacks which can be called at any time:

[Xtrace forClass:[UIView class] before:@selector(sizeToFit) callbackBlock:^( UILabel *label ) {
    NSLog( @"%@ sizeToFit before: %@", label, NSStringFromCGRect(label.frame) );
}];
[Xtrace forClass:[UIView class] after:@selector(sizeToFit) callbackBlock:^( UILabel *label ) {
    NSLog( @"%@ sizeToFit after: %@", label, NSStringFromCGRect(label.frame) );
}];

What works:

Icon

Reliability is now quite good for 32 bit builds considering.. I've had to introduce a method exclusion blacklist of a few methods causing problems. On 64 bit OS X you can expect some stack frame complications for methods with "struct" argument or return types - in particular for arguments to callbacks to the delegate. Xtrace does not currently work on the ARM64 abi - rebuild for 32 bits.

The ordering of calls to the api is: 1) Any class exclusions, 2) any method selector filter then 3) Class tracing or instance tracing and 4) any callbacks. That's about it. If you encounter problems drop me a line on xtrace (at) johnholdsworth.com. The developer of Xtrace and the "Injection Plugin" is available for Cocoa/iOS development work in the London area.

Announcements of major commits to the repo will be made on twitter @Injection4Xcode.

As ever:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

More Repositories

1

injectionforxcode

Runtime Code Injection for Objective-C & Swift
Objective-C
6,551
star
2

InjectionIII

Re-write of Injection for Xcode in (mostly) Swift
Objective-C
3,995
star
3

Refactorator

Xcode Plugin that Refactors Swift & Objective-C
Swift
991
star
4

GitDiff

Highlights deltas against git repo in Xcode
Objective-C
891
star
5

Remote

Control your iPhone from inside Xcode for end-to-end testing.
Objective-C
853
star
6

SwiftTrace

Trace Swift and Objective-C method invocations
Swift
695
star
7

HotReloading

Hot reloading as a Swift Package
Swift
536
star
8

XprobePlugin

Live Memory Browser for Apps & Xcode
Objective-C++
395
star
9

RefactoratorApp

App version of Refactorator plugin
Swift
255
star
10

Accelerator

Inline frameworks of Swift CocoaPods projects for faster launch
Ruby
174
star
11

InjectionApp

Issue Tracking Repo for Injection as an App
Swift
111
star
12

Fortify

Making Swift more robust
Swift
95
star
13

HotSwiftUI

Utilities for Hot Reloading SwiftUI apps.
Swift
94
star
14

Diamond

Diamond - Swift scripting made easy
Objective-C
94
star
15

SwiftPython

Experiments in bridging Swift to Python
Swift
88
star
16

Dynamo

High Performance (nearly)100% Swift Web server supporting dynamic content.
Swift
68
star
17

SwiftRegex

Some regular expression operators for Swift
Swift
67
star
18

NSLinux

NSString and libdispatch compatibility code for Swift on Linux
Swift
47
star
19

InstantSyntax

SwiftSyntax binary frameworks
Swift
47
star
20

InjectionNext

Fourth evolution of Code Injection for Xcode
Swift
47
star
21

WatchkitCurrency

Swift Currency Convertor for iWatch with flexible interface
Swift
40
star
22

TwoWayMirror

Adapt Swift’s Mirror functionality to make it bidirectional.
Swift
38
star
23

InjectionLite

Swift package re-write of InjectionIII app
Swift
34
star
24

Smuggler

Smuggle code bundles into an app running in the Simulator
Objective-C++
32
star
25

SwiftRegex5

5th incarnation of Swift Regex library using generic subscripts
Swift
32
star
26

SwiftAspects

Experiments in Aspects with Swift (Xtrace for Swift)
Assembly
30
star
27

unhide

export symbols with “hidden” visibility for Swift frameworks
Objective-C++
25
star
28

Symbolicate

Symbolicate for OS X
Objective-C
23
star
29

DLKit

A rather subscript oriented interface to the dynamic linker.
Swift
22
star
30

SwiftTryCatch

Try/Catch for Swift?
Swift
15
star
31

ApportablePlugin

Simple Plugin for work with Apportable
Objective-C
14
star
32

Compilertron

InjectionIII for the Swift compiler
C++
14
star
33

SearchLight

SpotLight on Steroids
Objective-C++
14
star
34

siteify

Build web site from a project’s Swift sources.
HTML
13
star
35

SwiftPlugin

A way to import classes from plugins
Swift
12
star
36

SwiftKeyPath

valueForKeyPath: for Swift
Swift
12
star
37

DynamoLinux

100% Swift Linux Web Server
Swift
11
star
38

ProfileSwiftUI

InstrumentSwiftUI
Swift
10
star
39

SwiftUIPlaygrounds

Alternative to Xcode previews.
Swift
9
star
40

SwiftRegex4

Basic regex operations for Swift4
Swift
9
star
41

StringIndex

Sensible indexing into Swift Strings
Swift
8
star
42

SwiftView

Curated Xcode Project as a means of navigating Swift Sources
7
star
43

Parallel

Some primitives for concurrent processing
Swift
6
star
44

Popen

Reading and writing processes and files
Swift
6
star
45

WatchkitSundial

Sundial for Apple Watch
Objective-C
6
star
46

SwiftierJSON

Memory efficient version of SwiftyJSON
Swift
6
star
47

objectivecpp

HTML
5
star
48

YieldGenerator

Python's "yield" generators for Swift
Swift
5
star
49

opaqueify

Greater use of Opaque types (SE0335)
Swift
5
star
50

SwiftMock

Mock structs and classes without code modification for testing.
Swift
4
star
51

Unwrap

Self documenting alternatives to force unwrap operator.
Swift
4
star
52

InjectionScratch

InjectionScratch
Objective-C++
3
star
53

EasyPointer

Rounding off some of the rough edges of Swift's pointer model
Swift
2
star
54

TestRunner

Example of calling Swift methods using name pattern (XCTest?)
Swift
2
star
55

binary-Swallow0

Swift
1
star
56

Character

Integer conversions and operators for Swift Characters.
Swift
1
star
57

ASCII

Facilitating operations on ASCII in Swift
Swift
1
star