doc: document how to register external bindings for snapshot

PR-URL: #37463 Refs: #35711 Reviewed-By: Juan José Arboleda <[email protected]> Reviewed-By: James M Snell <[email protected]>
nodejs · Mar 2, 2021 · cbfc6b1 · cbfc6b1
1 parent dd7a04d
commit cbfc6b1
Showing 1 changed file with 55 additions and 0 deletions.
diff --git a/src/README.md b/src/README.md
@@ -413,6 +413,55 @@ void Initialize(Local<Object> 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.
+<unresolved>
+/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.
+<unresolved>
+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<v8::Value> const&) at node_util.cc:159
+```
+
+Which explains that the unregistered external reference is
+`node::util::GetHiddenValue` defined in `node_util.cc`.
+
 <a id="per-binding-state"></a>
 #### Per-binding state
 
@@ -463,6 +512,12 @@ void InitializeHttpParser(Local<Object> 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.
+
 <a id="exception-handling"></a>
 ### Exception handling