Skip to main content

Development

Building & Running the idb cli​

The idb cli is python based and can simply be built using pip from the root of the repository:

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. build.sh builds the protoc-gen-grpc-swift plugin itself,
# from a pinned checkout of grpc-swift.
brew install protobuf swift-protobuf

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

./build.sh build

You can also build a subset, or run the test suites:

./build.sh build frameworks       # just the frameworks
./build.sh build idb_companion    # just the companion
./build.sh build FBControlCore    # a single framework
./build.sh test                   # run all tests
./build.sh test FBSimulatorControl
./build.sh help                   # all options

A full ./build.sh build 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 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.

Note that project.yml at the root of the repository is generated — regenerate it rather than editing it by hand; the other project.yml specs are maintained manually.

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 --grpc-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.