FLEX

FLEX (Flipboard Explorer) is a set of in-app debugging and exploration tools for iOS development. When presented, FLEX shows a toolbar that lives in a window above your application. From this toolbar, you can view and modify nearly every piece of state in your running application.

Give Yourself Debugging Superpowers

Inspect and modify views in the hierarchy.
See the properties and ivars on any object.
Dynamically modify many properties and ivars.
Dynamically call instance and class methods.
Observe detailed network request history with timing, headers, and full responses.
Add your own simulator keyboard shortcuts.
View system log messages (e.g. from NSLog).
Access any live object via a scan of the heap.
View the file system within your app's sandbox.
Browse SQLite/Realm databases in the file system.
Trigger 3D touch in the simulator using the control, shift, and command keys.
Explore all classes in your app and linked systems frameworks (public and private).
Quickly access useful objects such as [UIApplication sharedApplication], the app delegate, the root view controller on the key window, and more.
Dynamically view and modify NSUserDefaults values.

Unlike many other debugging tools, FLEX runs entirely inside your app, so you don't need to be connected to LLDB/Xcode or a different remote debugging server. It works well in the simulator and on physical devices.

Usage

In the iOS simulator, you can use keyboard shortcuts to activate FLEX. f will toggle the FLEX toolbar. Hit the ? key for a full list of shortcuts. You can also show FLEX programmatically:

Short version:

// Objective-C
[[FLEXManager sharedManager] showExplorer];

// Swift
FLEXManager.shared.showExplorer()

More complete version:

#if DEBUG
#import "FLEXManager.h"
#endif

...

- (void)handleSixFingerQuadrupleTap:(UITapGestureRecognizer *)tapRecognizer
{
#if DEBUG
    if (tapRecognizer.state == UIGestureRecognizerStateRecognized) {
        // This could also live in a handler for a keyboard shortcut, debug menu item, etc.
        [[FLEXManager sharedManager] showExplorer];
    }
#endif
}

Aside: tvOS

FLEX itself does not support tvOS out of the box. However, others have taken it upon themselves to port FLEX to tvOS. If you need tvOS support, seek out one of these forks. Here is one such fork.

Feature Examples

Modify Views

Once a view is selected, you can tap on the info bar below the toolbar to present more details about the view. From there, you can modify properties and call methods.

Network History

When enabled, network debugging allows you to view all requests made using NSURLConnection or NSURLSession. Settings allow you to adjust what kind of response bodies get cached and the maximum size limit of the response cache. You can choose to have network debugging enabled automatically on app launch. This setting is persisted across launches.

All Objects on the Heap

FLEX queries malloc for all the live allocated memory blocks and searches for ones that look like objects. You can see everything from here.

Explore-at-address

If you get your hands on an arbitrary address, you can try explore the object at that address, and FLEX will open it if it can verify the address points to a valid object. If FLEX isn't sure, it'll warn you and refuse to dereference the pointer. If you know better, however, you can choose to explore it anyway by choosing "Unsafe Explore"

Simulator Keyboard Shortcuts

Default keyboard shortcuts allow you to activate the FLEX tools, scroll with the arrow keys, and close modals using the escape key. You can also add custom keyboard shortcuts via -[FLEXManager registerSimulatorShortcutWithKey:modifiers:action:description]

File Browser

View the file system within your app's bundle or sandbox container. FLEX shows file sizes, image previews, and pretty prints .json and .plist files. You can rename and delete files and folders. You can "share" any file if you want to inspect them outside of your app.

SQLite Browser

SQLite database files (with either .db or .sqlite extensions), or Realm database files can be explored using FLEX. The database browser lets you view all tables, and individual tables can be sorted by tapping column headers.

3D Touch in the Simulator

Using a combination of the command, control, and shift keys, you can simulate different levels of 3D touch pressure in the simulator. Each key contributes 1/3 of maximum possible force. Note that you need to move the touch slightly to get pressure updates.

Explore Loaded Libraries

Go digging for all things public and private. To learn more about a class, you can create an instance of it and explore its default state. You can also type in a class name to jump to that class directly if you know which class you're looking for.

NSUserDefaults Editing

FLEX allows you to edit defaults that are any combination of strings, numbers, arrays, and dictionaries. The input is parsed as JSON. If other kinds of objects are set for a defaults key (i.e. NSDate), you can view them but not edit them.

Learning from Other Apps

The code injection is left as an exercise for the reader. :innocent:

Installation

FLEX requires an app that targets iOS 9 or higher. To run the Example project, open a Terminal window in the Example/ folder and run pod install, then open the generated workspace.

CocoaPods

FLEX is available on CocoaPods. Simply add the following line to your podfile:

pod 'FLEX', :configurations => ['Debug']

Carthage

Add the following to your Cartfile:

github "flipboard/FLEX"

Buck

If you're using Buck, you may want to silence some of the warnings emitted by FLEX. You will need to build FLEX as an apple_library and pass the -Wno-unsupported-availability-guard flag, as well as the other warning flags below to disable any other warnings FLEX may have.

Manual

Manually add the files in Classes/ to your Xcode project, or just drag in the entire FLEX/ folder. Be sure to exclude FLEX from Release builds or your app will be rejected.

Silencing warnings

Add the following flags to to Other Warnings Flags in Build Settings:

-Wno-deprecated-declarations
-Wno-strict-prototypes
-Wno-unsupported-availability-guard

Swift Package Manager

Include the dependency in the dependencies value of your Package.swift

dependencies: [
    .package(url: "https://github.com/FLEXTool/FLEX.git", .upToNextMajor(from: "4.3.0"))
]

Next, include the library in your target:

.target(
    name: "YourDependency",
    dependencies: [
        "FLEX"
    ]
)

Excluding FLEX from Release (App Store) Builds

FLEX makes it easy to explore the internals of your app, so it is not something you should expose to your users. Fortunately, it is easy to exclude FLEX files from Release builds. The strategies differ depending on how you integrated FLEX in your project, and are described below.

Wrap the places in your code where you integrate FLEX with an #if DEBUG statement to ensure the tool is only accessible in your Debug

FLEX

Install / Use

README

FLEX

Give Yourself Debugging Superpowers

Usage

Aside: tvOS

Feature Examples

Modify Views

Network History

All Objects on the Heap

Explore-at-address

Simulator Keyboard Shortcuts

File Browser

SQLite Browser

3D Touch in the Simulator

Explore Loaded Libraries

NSUserDefaults Editing

Learning from Other Apps

Installation

CocoaPods

Carthage

Buck

Manual

Silencing warnings

Swift Package Manager

Excluding FLEX from Release (App Store) Builds