From f7d3d30442ea7933ed0e3bcc35be4317260010da Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Sun, 21 Feb 2021 22:46:58 +0800
Subject: [PATCH 1/3] doc: document how to register external bindings for
 snapshot

---
 src/README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/src/README.md b/src/README.md
index a3b54416a0d2f5..8e1529544ce56c 100644
--- a/src/README.md
+++ b/src/README.md
@@ -413,6 +413,52 @@ 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
+
+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 +509,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
 

From 4c4d86993c7963c70100351c09e2dc417fd39e33 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Wed, 24 Feb 2021 23:38:11 +0800
Subject: [PATCH 2/3] fixup! doc: document how to register external bindings
 for snapshot

---
 src/README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/README.md b/src/README.md
index 8e1529544ce56c..c6466f3c461733 100644
--- a/src/README.md
+++ b/src/README.md
@@ -427,6 +427,9 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
 }  // 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)
 ```
 

From b996af707020990cad895d5e4fed8d2d89da418a Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Thu, 25 Feb 2021 23:51:45 +0800
Subject: [PATCH 3/3] fixup! doc: document how to register external bindings
 for snapshot

Co-authored-by: akhil marsonya <16393876+marsonya@users.noreply.github.com>
---
 src/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/README.md b/src/README.md
index c6466f3c461733..d811a6280273c6 100644
--- a/src/README.md
+++ b/src/README.md
@@ -433,7 +433,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
 NODE_MODULE_EXTERNAL_REFERENCE(util, node::util::RegisterExternalReferences)
 ```
 
-Otherwise you might see an error message like this when building the
+Otherwise, you might see an error message like this when building the
 executables:
 
 ```console