diff --git a/src/README.md b/src/README.md index 7d82b5a3e7530f..dd9a9df449f147 100644 --- a/src/README.md +++ b/src/README.md @@ -417,6 +417,55 @@ void Initialize(Local target, NODE_MODULE_CONTEXT_AWARE_INTERNAL(cares_wrap, Initialize) ``` +If the C++ binding is loaded during bootstrap, it needs to be registered +with the utilities in `node_external_reference.h`, like this: + +```cpp +namespace node { +namespace utils { +void RegisterExternalReferences(ExternalReferenceRegistry* registry) { + registry->Register(GetHiddenValue); + registry->Register(SetHiddenValue); + // ... register all C++ functions used to create FunctionTemplates. +} +} // namespace util +} // namespace node + +// The first argument passed to `NODE_MODULE_EXTERNAL_REFERENCE`, +// which is `util` here, needs to be added to the +// `EXTERNAL_REFERENCE_BINDING_LIST_BASE` list in node_external_reference.h +NODE_MODULE_EXTERNAL_REFERENCE(util, node::util::RegisterExternalReferences) +``` + +Otherwise, you might see an error message like this when building the +executables: + +```console +FAILED: gen/node_snapshot.cc +cd ../../; out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc +Unknown external reference 0x107769200. + +/bin/sh: line 1: 6963 Illegal instruction: 4 out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc +``` + +You can try using a debugger to symbolicate the external reference. For example, +with lldb's `image lookup --address` command (with gdb it's `info symbol`): + +```console +$ lldb -- out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc +(lldb) run +Process 7012 launched: '/Users/joyee/projects/node/out/Release/node_mksnapshot' (x86_64) +Unknown external reference 0x1004c8200. + +Process 7012 stopped +(lldb) image lookup --address 0x1004c8200 + Address: node_mksnapshot[0x00000001004c8200] (node_mksnapshot.__TEXT.__text + 5009920) + Summary: node_mksnapshot`node::util::GetHiddenValue(v8::FunctionCallbackInfo const&) at node_util.cc:159 +``` + +Which explains that the unregistered external reference is +`node::util::GetHiddenValue` defined in `node_util.cc`. + #### Per-binding state @@ -467,6 +516,12 @@ void InitializeHttpParser(Local target, } ``` +If the binding is loaded during bootstrap, add it to the +`SERIALIZABLE_OBJECT_TYPES` list in `src/node_snapshotable.h` and +inherit from the `SnapshotableObject` class instead. See the comments +of `SnapshotableObject` on how to implement its serialization and +deserialization. + ### Exception handling