amis-rpc-design/node_modules/react-native/ReactCommon/hermes/inspector/README.md

hermes-inspector provides a bridge between the low-level debugging API exposed by Hermes and higher-level debugging protocols such as the Chrome DevTools protocol.

Targets

• chrome: classes that implement the Chrome DevTools Protocol adapter. Sits on top of classes provided by the inspector target.
• detail: utility classes and functions
• inspector: protocol-independent classes that sit on top of the low-level Hermes debugging API.

Testing

Tests are implemented using gtest. Debug logging is enabled for tests, and you can get debug logs to show even when tests are passing by running the test executable directly:

$ buck build //xplat/js/react-native-github/packages/react-native/ReactCommon/hermes/inspector:chrome-tests
$ buck-out/gen/xplat/js/react-native-github/packages/react-native/ReactCommon/hermes/inspector/chrome-tests
[...]

You can use standard gtest filters to only execute a particular set of tests:

$ buck-out/gen/xplat/js/react-native-github/packages/react-native/ReactCommon/hermes/inspector/chrome-tests \
    --gtest_filter='ConnectionTests.testSetBreakpoint'

You can debug the tests using lldb or gdb:

$ lldb buck-out/gen/xplat/js/react-native-github/packages/react-native/ReactCommon/hermes/inspector/chrome-tests
$ gdb buck-out/gen/xplat/js/react-native-github/packages/react-native/ReactCommon/hermes/inspector/chrome-tests

Formatting

Make sure the code is formatted using the hermes clang-format rules before committing:

$ xplat/js/react-native-github/packages/react-native/ReactCommon/hermes/inspector/tools/format

We follow the clang format rules used by the rest of the Hermes project.

Adding Support For New Message Types

To add support for a new Chrome DevTools protocol message, add the message you want to add to tools/message_types.txt, and re-run the message types generator:

$ xplat/js/react-native-github/packages/react-native/ReactCommon/hermes/inspector/tools/run_msggen

This will generate C++ structs for the new message type in chrome/MessageTypes.{h,cpp}.

You'll then need to:

1. Implement a message handler for the new message type in chrome::Connection.
2. Implement a public API for the new message type in Inspector. This will most likely return a folly::Future that the message handler in (1) can use for chaining.
3. Implement a private API for the new message type in Inspector that performs the logic in Inspector's executor. (Inspector.cpp contains a comment explaining why the executor is necessary.)
4. Optionally, implement a method for the new message type in InspectorState. In most cases this is probably not necessary--one of the existing methods in InspectorState will work.

For a diff that illustrates these steps, take a look at D6601459.

Testing Integration With Nuclide and Apps

For now, the quickest way to use hermes-inspector in an app is with Eats. First, make sure the packager is running:

$ js1 run

Then, on Android, build the fbeats target:

$ buck install --run fbeats

On iOS, build the //Apps/Internal/Eats:Eats target:

$ buck install --run //Apps/Internal/Eats:Eats

You can also build Eats in Xcode using arc focus if you prefer an IDE:

$ arc focus --force-build \
    -b //Apps/Internal/Eats:Eats \
    cxxreact //xplat/hermes/API:HermesAPI //xplat/hermes/lib/VM:VM jsi \
    jsinspector hermes-inspector FBReactKit FBReactModule FBCatalystWrapper \
    //xplat/js:React //xplat/js/react-native-github:ReactInternal

For all the above commands, if you want to build the inspector -O0 for better debug info, add the argument --config hermes.build_mode=dbg.

You should then be able to launch the app and see it listed in the list of Mobile JS contexts in the Nuclide debugger.