Skip to main content

Development

Building & Running the idb cli​

The idb cli is python based and can simply be built using pip

pip3 install .

Building & Running the idb_companion​

This is a native macOS executable, built via Xcode.

Firstly, there are system level build dependencies that needed, these can be installed via homebrew:

# Tap for grpc
brew tap grpc/grpc
# The grpc compiler is used to generate C++ bindings from the idb.proto definition
brew install grpc
# cocoapods is needed to resolve dependencies for the Xcode project
brew install cocoapods
# cocoapods is used to resolve the grpc runtime library for the companion
# This must be run from the root of the idb repository to use the appropriate Podfile
pod install

This will open an Xcode project that you can build and run:

open idb_companion.xcworkspace

After opening the Xcode project you will need to add a --udid argument for launch.

  • Get the UDID of either your device or simulator
    • Window -> Devices and Simulators
    • Select the device or simulator you care about
    • Copy the value in the Identifier section of the header
  • Project -> Scheme -> Edit Scheme (or cmd + <)
  • Run -> Arguments
  • Click the + under the Arguments Passed on Launch section
  • Enter --udid <UDID copied above>
  • Run the idb_companion target on My Mac

Once idb_companion has launched, it will output the TCP port upon which the companion has bound to stdout:

{"grpc_port":10882}

By default this port is 10882, it can be bound on a random port with --port 0 or a port of your choosing. You'll now be able to direct idb commands against this companion with the IDB_COMPANION environment variable passed to the cli:

$ IDB_COMPANION=localhost:10882 idb describe

As long as you prefix this environment variable before all commands, you'll be able to run commands against the companion that you're currently debugging within Xcode.