From 4cb8476bb5941d52b8e795a1137809d96782c14b Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Tue, 3 Dec 2019 18:18:37 +0800 Subject: [PATCH] doc: add documentation about node_mksnapshot and mkcodecache PR-URL: https://github.com/nodejs/node/pull/30773 Reviewed-By: Anna Henningsen Reviewed-By: Gireesh Punathil --- tools/code_cache/README.md | 38 ++++++++++++++++++++++++++++++++++ tools/snapshot/README.md | 42 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 tools/code_cache/README.md create mode 100644 tools/snapshot/README.md diff --git a/tools/code_cache/README.md b/tools/code_cache/README.md new file mode 100644 index 00000000000000..f8428c24b0dd4b --- /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 00000000000000..34dc574d56cc30 --- /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.