FLEX Deployment and Usage Guide

Prerequisites

• iOS Development Environment: Xcode 9.0 or later
• macOS: macOS 10.13 or later
• iOS: iOS 9.0 or later
• Swift/Objective-C: Compatible with both languages
• CocoaPods (optional): For dependency management
• Carthage (optional): For dependency management

Installation

Using CocoaPods (Recommended)

1. Add FLEX to your Podfile:

pod 'FLEX', '~> 2.4'

2. Run the installation command:

pod install

3. Open your workspace file (.xcworkspace) in Xcode.

Using Carthage

1. Add FLEX to your Cartfile:

github "Flipboard/FLEX" ~> 2.4

2. Run Carthage to build the framework:

carthage update --platform iOS

3. Drag the built FLEX.framework into your Xcode project.

Manual Installation

1. Clone the repository:

git clone https://github.com/Flipboard/FLEX.git

2. Add the FLEX source files to your Xcode project.

Configuration

Enabling FLEX in Debug Builds

To ensure FLEX is only available in debug builds, wrap the import and usage in preprocessor directives:

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

Showing FLEX Programmatically

Add a gesture recognizer or debug menu item to trigger FLEX:

- (void)handleSixFingerQuadrupleTap:(UITapGestureRecognizer *)tapRecognizer
{
#if DEBUG
    if (tapRecognizer.state == UIGestureRecognizerStateRecognized) {
        [[FLEXManager sharedManager] showExplorer];
    }
#endif
}

Simulator Keyboard Shortcuts

FLEX includes default keyboard shortcuts for the simulator:

• f: Toggle FLEX toolbar
• ?: Show help for all shortcuts

You can register custom shortcuts:

[FLEXManager.sharedManager registerSimulatorShortcutWithKey:'d'
                                                  modifiers:NSShiftKeyMask
                                                    action:@selector(yourActionMethod)
                                                description:@"Your custom action"];

Build & Run

Development

1. Open your Xcode project or workspace.
2. Ensure the target is set to your app.
3. Select a simulator or connected device.
4. Build and run using Cmd+R or the Run button.

Testing FLEX

1. Build and run your app in the simulator.
2. Use the f key to toggle the FLEX toolbar.
3. Explore the various debugging tools available.

Production Considerations

• Remove FLEX: Ensure FLEX is disabled or removed from release builds using the #if DEBUG preprocessor directive.
• Performance: FLEX may impact app performance; use it only during development.

Deployment

iOS App Store

Since FLEX is a development tool, it should not be included in App Store builds. Use conditional compilation to exclude it:

#if DEBUG
// FLEX code here
#endif

Enterprise Distribution

For enterprise builds, follow the same approach as App Store distribution to exclude FLEX from release builds.

Troubleshooting

Common Issues and Solutions

FLEX Not Showing Up

Issue: FLEX toolbar doesn't appear when pressing f in the simulator.

Solution:

1. Ensure you're running in the simulator, not on a physical device.
2. Verify that the #if DEBUG directive is correctly wrapping FLEX imports and usage.
3. Check that your keyboard focus is on the simulator window.

Build Errors with CocoaPods

Issue: Build fails with CocoaPods integration.

Solution:

1. Run pod repo update to ensure your CocoaPods repository is up to date.
2. Delete the Podfile.lock and Pods directory, then run pod install again.
3. Ensure you're opening the .xcworkspace file, not the .xcodeproj.

Carthage Build Failures

Issue: Carthage fails to build FLEX.

Solution:

1. Ensure Carthage is installed: brew install carthage
2. Run carthage update --platform iOS --no-use-binaries to force a fresh build.
3. Check for any missing dependencies in your Cartfile.

FLEX Crashes on Launch

Issue: App crashes when trying to show FLEX.

Solution:

1. Verify that FLEX is properly linked in your project settings.
2. Check for any conflicts with other debugging tools.
3. Ensure you're using a compatible version of FLEX with your iOS version.

Network History Not Working

Issue: Network requests are not appearing in FLEX.

Solution:

1. Ensure network debugging is enabled in FLEX settings.
2. Verify that your app is using NSURLSession or NSURLConnection for network requests.
3. Check that the requests are not being made before FLEX is initialized.

Memory Issues with Heap Explorer

Issue: Heap explorer causes memory warnings or crashes.

Solution:

1. Limit the number of objects displayed in the heap explorer.
2. Use the heap explorer sparingly, especially with large apps.
3. Ensure your app has sufficient memory available before using this feature.

File Browser Not Showing Files

Issue: File browser is empty or missing expected files.

Solution:

1. Verify that the files exist in your app's sandbox.
2. Check file permissions and ensure FLEX has access to the directories.
3. Look for any filters that might be hiding files.

SQLite Browser Issues

Issue: SQLite database files are not being recognized.

Solution:

1. Ensure the database files have .db or .sqlite extensions.
2. Verify that the files are not corrupted.
3. Check that the database is not currently locked by another process.

Realm Database Support

Issue: Realm databases are not being recognized.

Solution:

1. Ensure you have Realm integrated into your project.
2. Verify that the Realm files have the correct .realm extension.
3. Check that the Realm files are not encrypted or otherwise inaccessible.

Keyboard Shortcuts Not Working

Issue: Custom keyboard shortcuts are not responding.

Solution:

1. Verify that the shortcut keys are not already in use by the system or Xcode.
2. Ensure the modifiers (Shift, Command, etc.) are correctly specified.
3. Check that the action method exists and is properly implemented.

FLEX Toolbar Overlapping UI

Issue: FLEX toolbar covers important parts of your app's UI.

Solution:

1. Adjust the FLEX toolbar position in the settings.
2. Use the FLEXManager API to programmatically control FLEX visibility.
3. Consider using FLEX in a secondary window or modal presentation.

Performance Impact

Issue: App performance degrades when FLEX is active.

Solution:

1. Use FLEX only during development and disable it in release builds.
2. Limit the use of resource-intensive features like the heap explorer.
3. Consider using FLEX in a separate debug build configuration.

Integration with Other Debugging Tools

Issue: Conflicts with other debugging tools like Xcode's view debugger.

Solution:

1. Disable conflicting tools when using FLEX.
2. Use FLEX and other tools in separate debugging sessions.
3. Check for any overlapping functionality and use one tool at a time.

Updating FLEX

Issue: Need to update to a newer version of FLEX.

Solution:

1. For CocoaPods: Update your Podfile to the desired version and run pod update.
2. For Carthage: Update your Cartfile and run carthage update.
3. For manual installation: Replace the FLEX source files with the newer version.

Contributing to FLEX

Issue: Want to contribute to FLEX development.

Solution:

1. Fork the repository on GitHub.
2. Make your changes and ensure they pass the existing tests.
3. Submit a pull request with a clear description of your changes.

By following this guide, you should be able to successfully integrate, use, and troubleshoot FLEX in your iOS development workflow. Remember to use FLEX responsibly and only in development environments to avoid any issues in production apps.