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. The Xcode projects are generated from project.yml files with XcodeGen and everything is driven by the build.sh script at the root of the repository.

Firstly, there are system level build dependencies, which can be installed via homebrew:

# XcodeGen generates the Xcode projects from the project.yml files
brew install xcodegen
# protobuf and swift-protobuf are used to generate the gRPC Swift bindings from
# idb.proto (grpc-swift itself is resolved as a Swift Package dependency)
brew install protobuf swift-protobuf

Build the companion (and the frameworks, shims and helpers it needs) with:

./build.sh build

This produces a self-contained distribution at Build/Distribution, containing idb_companion alongside a Resources directory with the shim dylibs and the SimulatorFrameworkBridge helper — the layout idb_companion expects at runtime. You can then run it directly:

./Build/Distribution/idb_companion --udid <UDID>

Get the UDID of either your device or simulator from idb list-targets, or from Xcode under Window -> Devices and Simulators (the value in the Identifier section of the header).

If you prefer to build and debug inside Xcode, generate the projects with ./build.sh generate and open idb_companion/idb_companion.xcodeproj. Edit the idb_companion scheme (Product -> Scheme -> Edit Scheme, or cmd + <), and under Run -> Arguments add --udid <UDID> to "Arguments Passed on Launch" before running 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.