summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJoyee Cheung <joyeec9h3@gmail.com>2019-12-03 18:18:37 +0800
committerJoyee Cheung <joyeec9h3@gmail.com>2019-12-05 18:57:33 +0800
commit3a4d916ea7b9c36971df66fbdf9d4e68d2e20111 (patch)
treee9df4d0a9cebf1101abd4cd3bd7c586f8f637f7f
parent781e41df618a8d8878fb1c819855a31ef75115d1 (diff)
downloadandroid-node-v8-3a4d916ea7b9c36971df66fbdf9d4e68d2e20111.tar.gz
android-node-v8-3a4d916ea7b9c36971df66fbdf9d4e68d2e20111.tar.bz2
android-node-v8-3a4d916ea7b9c36971df66fbdf9d4e68d2e20111.zip
doc: add documentation about node_mksnapshot and mkcodecache
PR-URL: https://github.com/nodejs/node/pull/30773 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
-rw-r--r--tools/code_cache/README.md38
-rw-r--r--tools/snapshot/README.md42
2 files changed, 80 insertions, 0 deletions
diff --git a/tools/code_cache/README.md b/tools/code_cache/README.md
new file mode 100644
index 0000000000..f8428c24b0
--- /dev/null
+++ b/tools/code_cache/README.md
@@ -0,0 +1,38 @@
+# Node.js code cache builder
+
+This is the V8 code cache builder of Node.js. It pre-compiles all the
+JavaScript native modules of Node.js and serializes the code cache (including
+the bytecodes) that will be embeded into the Node.js executable. When a Node.js
+JavaScript native module is `require`d at runtime, Node.js can deserialize from
+the code cache instead of parsing the source code and generating the bytecode
+for it before execution, which should reduce the load time of these JavaScript
+native modules.
+
+## How it's built and used
+
+The code cache builder is built with the `mkcodecache` target in `node.gyp`
+when `node_use_node_code_cache` is set to true, which is currently done by
+default.
+
+In the default build of the Node.js executable, to embed the V8 code cache of
+the native modules into the Node.js executable, `libnode` is first built with
+these unresolved symbols:
+
+- `node::native_module::has_code_cache`
+- `node::native_module::NativeModuleEnv::InitializeCodeCache`
+
+Then the `mkcodecache` executable is built with C++ files in this directory,
+as well as `src/node_code_cache_stub.cc` which defines the unresolved symbols.
+
+`mkcodecache` is run to generate a C++ file
+`<(SHARED_INTERMEDIATE_DIR)/node_code_cache.cc` that is similar to
+`src/node_code_cache_stub.cc` in structure, but contains the code cache data
+written as static char array literals. Then `libnode` is built with
+`node_code_cache.cc` to produce the final Node.js executable with the code
+cache data embedded.
+
+For debugging, Node.js can be built without code cache if
+`--without-node-code-cache` is passed to `configure`. Note that even if the
+code cache is not pre-compiled and embedded into the Node.js executable, the
+internal infrastructure is still used to share code cache between the main
+thread and worker threads (if there is any).
diff --git a/tools/snapshot/README.md b/tools/snapshot/README.md
new file mode 100644
index 0000000000..34dc574d56
--- /dev/null
+++ b/tools/snapshot/README.md
@@ -0,0 +1,42 @@
+# Node.js startup snapshot builder
+
+This is the V8 startup snapshot builder of Node.js. Not to be confused with
+V8's own snapshot builder, which builds a snapshot containing JavaScript
+builtins, this builds a snapshot containing Node.js builtins that can be
+deserialized on top of V8's own startup snapshot. When Node.js is launched,
+instead of executing code to bootstrap, it can deserialize the context from
+an embedded snapshot, which readily contains the result of the bootstrap, so
+that Node.js can start up faster.
+
+Currently only the main context of the main Node.js instance supports snapshot
+deserialization, and the snapshot does not yet cover the entire bootstrap
+process. Work is being done to expand the support.
+
+## How it's built and used
+
+The snapshot builder is built with the `node_mksnapshot` target in `node.gyp`
+when `node_use_node_snapshot` is set to true, which is currently done by
+default.
+
+In the default build of the Node.js executable, to embed a V8 startup snapshot
+into the Node.js executable, `libnode` is first built with these unresolved
+symbols:
+
+- `node::NodeMainInstance::GetEmbeddedSnapshotBlob`
+- `node::NodeMainInstance::GetIsolateDataIndexes`
+
+Then the `node_mksnapshot` executable is built with C++ files in this
+directory, as well as `src/node_snapshot_stub.cc` which defines the unresolved
+symbols.
+
+`node_mksnapshot` is run to generate a C++ file
+`<(SHARED_INTERMEDIATE_DIR)/node_snapshot.cc` that is similar to
+`src/node_snapshot_stub.cc` in structure, but contains the snapshot data
+written as static char array literals. Then `libnode` is built with
+`node_snapshot.cc` to produce the final Node.js executable with the snapshot
+data embedded.
+
+For debugging, Node.js can be built without Node.js's own snapshot if
+`--without-node-snapshot` is passed to `configure`. A Node.js executable
+with Node.js snapshot embedded can also be launched without deserializing
+from it if the command line argument `--no-node-snapshot` is passed.