process: document the bootstrap process in node.js

PR-URL: https://github.com/nodejs/node/pull/26033
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 29 insertions, 10 deletions

diff --git a/lib/internal/bootstrap/node.js b/lib/internal/bootstrap/node.js
index afb6340570..a8bc57cd1b 100644
--- a/lib/internal/bootstrap/node.js
+++ b/lib/internal/bootstrap/node.js
@@ -1,19 +1,38 @@
 // Hello, and welcome to hacking node.js!
 //
-// This file is invoked by node::LoadEnvironment in src/node.cc, and is
-// responsible for bootstrapping the node.js core. As special caution is given
-// to the performance of the startup process, many dependencies are invoked
-// lazily.
+// This file is invoked by `node::RunBootstrapping()` in `src/node.cc`, and is
+// responsible for setting up node.js core before executing main scripts
+// under `lib/internal/main/`.
+// This file is currently run to bootstrap both the main thread and the worker
+// threads. Some setups are conditional, controlled with isMainThread and
+// ownsProcessState.
+// This file is expected not to perform any asynchronous operations itself
+// when being executed - those should be done in either
+// `lib/internal/bootstrap/pre_execution.js` or in main scripts. The majority
+// of the code here focus on setting up the global proxy and the process
+// object in a synchronous manner.
+// As special caution is given to the performance of the startup process,
+// many dependencies are invoked lazily.
 //
-// Before this file is run, lib/internal/bootstrap/loaders.js gets run first
-// to bootstrap the internal binding and module loaders, including
-// process.binding(), process._linkedBinding(), internalBinding() and
-// NativeModule. And then { internalBinding, NativeModule } will be passed
-// into this bootstrapper to bootstrap Node.js core.
+// Scripts run before this file:
+// - `lib/internal/bootstrap/context.js`: to setup the v8::Context with
+//   Node.js-specific tweaks - this is also done in vm contexts.
+// - `lib/internal/bootstrap/primordials.js`: to save copies of JavaScript
+//   builtins that won't be affected by user land monkey-patching for internal
+//   modules to use.
+// - `lib/internal/bootstrap/loaders.js`: to setup internal binding and
+//   module loaders, including `process.binding()`, `process._linkedBinding()`,
+//   `internalBinding()` and `NativeModule`.
+//
+// After this file is run, one of the main scripts under `lib/internal/main/`
+// will be selected by C++ to start the actual execution. The main scripts may
+// run additional setups exported by `lib/internal/bootstrap/pre_execution.js`,
+// depending on the execution mode.
+
 'use strict';
 
 // This file is compiled as if it's wrapped in a function with arguments
-// passed by node::LoadEnvironment()
+// passed by node::RunBootstrapping()
 /* global process, loaderExports, isMainThread, ownsProcessState */
 
 const { internalBinding, NativeModule } = loaderExports;