by Itty Bitty Apps

Load the Reveal Server via an Xcode Breakpoint

Loading the Reveal Server framework via an Xcode Debugger Breakpoint is a great way to let you inspect any project with minimal or no changes to the project's files. It also means you don't need to worry about accidentally shipping a release build of your app linked with the Reveal library.

Instructions

The following steps only need to be performed once for each computer and user account you're running Reveal on:

  1. In Reveal, open the Help menu and click Install Debugger Commands…
  2. Click Continue to finish the installation.

    To learn more about Reveal Server debugger commands, please refer to the corresponding guide.

  3. Open your iOS or tvOS project in Xcode, and select View → Navigators → Show Breakpoint Navigator.

  4. In the bottom left of the pane, click the + button and select Symbolic Breakpoint…

    Adding Symbolic Breakpoint to Xcode project

  5. Enter UIApplicationMain into the Symbol field.

  6. Click the Add Action button, and ensure that Action is set to Debugger Command.
  7. Copy and paste the following command into the field below:

    reveal load --autostart
  8. Check Automatically continue after evaluating actions.

    Setting up Symbolic Breakpoint in Xcode project

  9. Right click the newly created breakpoint and select Move Breakpoint To → User.

    Moving the Breakpoint to the User

    You can enable and disable the breakpoint as you would any other. User breakpoints are available across all Xcode projects.

  10. In Xcode, build and run your application under the iOS or tvOS Simulator.

    Reveal App Chooser showing Soundstagram

    You should now be able to switch to Reveal and see your iOS or tvOS application listed. Select your app and verify that you can see a snapshot matching what you see in the simulator.

Debugging on device

The steps outlined above are sufficient for debugging any application using Reveal in the iOS or tvOS Simulator. However, if you would also like to use Reveal when debugging your applications on device (this includes macOS Catalyst and iOS apps running on Apple Silicon Macs), there are a few extra steps you'll need to perform for each project:

  1. Open your project in Xcode, then select the project's icon in Xcode's Project Navigator.

  2. Select the target you want to inspect using Reveal from the TARGETS list.

  3. Select the Build Phases tab, click the + button and add a New Run Script Phase — name it "Integrate Reveal Server". Paste in the following shell script:

     REVEAL_APP_PATH=$(mdfind kMDItemCFBundleIdentifier="com.ittybittyapps.Reveal2" | head -n 1)
     BUILD_SCRIPT_PATH="${REVEAL_APP_PATH}/Contents/SharedSupport/Scripts/reveal_server_build_phase.sh"
     if [ "${REVEAL_APP_PATH}" -a -e "${BUILD_SCRIPT_PATH}" ]; then
     "${BUILD_SCRIPT_PATH}"
     else
     echo "Reveal Server not loaded: Cannot find a compatible Reveal app."
     fi

    Add run script phase to target

    This build phase will locate Reveal on your computer and copy Reveal Server framework as a resource into your application – but only when building with Debug configuration.

    You may also need to add $(CONFIGURATION_BUILD_DIR)/$(INFOPLIST_PATH) as an entry in the Run Script Phase's Input Files list.

  4. In Xcode, build and run your application on an iOS or tvOS device using a scheme that is set to use the Debug configuration. Ensure that the device is on the same Wi-Fi network as Mac running Reveal, or connected to your Mac by its USB cable.

    Reveal App Chooser showing Soundstagram

    You should now be able to switch to Reveal and see your iOS or tvOS application listed in. Select your app and verify that you can see a snapshot matching what you see on device.

No code needs to be added, nor any headers imported for Reveal integration. The breakpoint you created earlier will load the framework automatically at launch and start the necessary Reveal services within your app.

Additional Information

The breakpoint that you set does not directly load and start Reveal Server, as we need to wait for your app to be in a ready state before doing so. The breakpoint actually sets up a second one-shot breakpoint on either -[UIViewController viewDidLoad] or UIViewController.viewDidLoad() depending on the context of your LLDB session, and that loads (and autostarts, if you've chosen to) Reveal Server. Once this is done, the second breakpoint is ignored for any subsequent calls your app makes to the view controller's "view did load" method.

Getting Help

If you have any problems or questions about using Reveal Server commands with your app, head over to our support site.

Visit Support Site