Integrating Reveal via Linking

Linking Reveal's Server framework into your iOS or tvOS application is a quick and easy way to enable Reveal introspection.

WARNING: Never ship a product which has been linked with the Reveal Server framework. The instructions below outline a way to use build configurations to isolate linking the framework to Debug builds.

You'll need to perform the following steps for each target that you wish to use with Reveal:

  1. Launch Reveal and select either "iOS Library" or "tvOS Library" from the Help → Show Reveal Library in Finder menu. This will open a Finder window with the appropriate framework selected.

    show-reveal-library-in-finder.jpg

  2. Copy RevealServer.xcframework to the root directory of your project in Finder by holding the Option (⌥) key while dragging it.

    Note: It is important to copy RevealServer.xcframework into your project. Make sure that you press and hold the Option key while dragging the file, otherwise the Finder will create an alias, not a copy.

    It is also very important to use Finder for this step. Adding the framework using Xcode's "Embedded Binaries" or "Linked Frameworks & Libraries" settings introduces build settings that we'll be customizing later in this guide.

    You can also place the framework in a subdirectory to keep things organized. Just make sure to update the path environment variable on the run script phase (below) accordingly.

  3. Open your project in Xcode, then select the project's icon in Xcode's Project Navigator.
  4. Select the target you want to inspect using Reveal from the TARGETS list.
  5. Select the General tab, and scroll down to the Frameworks, Libraries and Embedded Content section.

  6. Drag the copy of RevealServer.xcframework from the Finder into the Frameworks, Libraries and Embedded Content step, then set the Embed value to to Embed & Sign .
    drag-in-finder-reveal-framework.jpg

  7. Now select the Build Phases tab, and ensure that you have a Link Binary with Libraries step. Expand it.

  8. Find RevealServer.xcframework in the list, and set the Status to Optional . We do this so that the framework is weakly linked into your application binary, and can be removed in Release builds without any effect.

  9. Still in the Build Settings tab, add the following to the Debug configuration of the Runpath Search Paths (LD_RUNPATH_SEARCH_PATHS) if it is not already present:

    $(inherited) @executable_path/Frameworks
  10. Still in 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:

    export REVEAL_SERVER_FILENAME="RevealServer.xcframework"
    
    # Update this path to point to the location of RevealServer.xcframework in your project.
    export REVEAL_SERVER_PATH="${SRCROOT}/${REVEAL_SERVER_FILENAME}"
    
    # If RevealServer.xcframework exists at the specified path, run the integration script.
    if [ -d "${REVEAL_SERVER_PATH}" ]; then
      "${REVEAL_SERVER_PATH}/Scripts/integrate_revealserver.sh"
    else
      echo "Reveal Server not loaded into ${TARGET_NAME}: ${REVEAL_SERVER_FILENAME} could not be found."
    fi

    Note : If you choose to keep RevealServer.xcframework elsewhere, follow the comments in the script to update the REVEAL_SERVER_PATH environment variable.

    add-run-script-phase-breakpoint.jpg

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

    reveal-app-chooser.jpg

    If everything worked, you should be able to switch to Reveal and see your iOS or tvOS application listed in Reveal. Select your app and verify that you can see a snapshot of the app matching what you see in the simulator (or device).

  12. Run your application again, this time using a scheme set to use the Release configuration. Verify that Reveal cannot connect to your application.

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