Skip to content

Commit 3f9f322

Browse files
committed
doc: mark --build-snapshot and --build-snapshot-config as stable
While the support for serialization of built-in modules is likely to be open-ended, the CLI flags themselves have been very stable. Mark them as stable and update the documentation about the support status of built-in module serialization.
1 parent 85852a3 commit 3f9f322

File tree

1 file changed

+23
-17
lines changed

1 file changed

+23
-17
lines changed

doc/api/cli.md

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,6 @@ changes:
5252
Node.js options as well, in addition to V8 options.
5353
-->
5454

55-
> Stability: 2 - Stable
56-
5755
All options, including V8 options, allow words to be separated by both
5856
dashes (`-`) or underscores (`_`). For example, `--pending-deprecation` is
5957
equivalent to `--pending_deprecation`.
@@ -405,7 +403,7 @@ Error: Access to this API has been restricted
405403
added: v18.8.0
406404
-->
407405

408-
> Stability: 1 - Experimental
406+
> Stability: 2 - Stable
409407
410408
Generates a snapshot blob when the process exits and writes it to
411409
disk, which can be loaded later with `--snapshot-blob`.
@@ -442,18 +440,24 @@ I am from the snapshot
442440

443441
For more information, check out the [`v8.startupSnapshot` API][] documentation.
444442

445-
Currently the support for run-time snapshot is experimental in that:
446-
447-
1. User-land modules are not yet supported in the snapshot, so only
448-
one single file can be snapshotted. Users can bundle their applications
449-
into a single script with their bundler of choice before building
450-
a snapshot, however.
451-
2. Only a subset of the built-in modules work in the snapshot, though the
452-
Node.js core test suite checks that a few fairly complex applications
453-
can be snapshotted. Support for more modules are being added. If any
454-
crashes or buggy behaviors occur when building a snapshot, please file
455-
a report in the [Node.js issue tracker][] and link to it in the
456-
[tracking issue for user-land snapshots][].
443+
The snapshot currently only supports loding a single entrypoint during the
444+
snapshot building process, which can load built-in modules, but not additional user-land modules.
445+
Users can bundle their applications into a single script with their bundler
446+
of choice before building a snapshot.
447+
448+
As it's complicated to ensure the serializablility of all built-in modules,
449+
which are also growing over time, only a subset of the built-in modules are
450+
well tested to be serializable during the snapshot building process.
451+
The Node.js core test suite checks that a few fairly complex applications
452+
can be snapshotted. The list of built-in modules being
453+
[captured by the built-in snapshot of Node.js][] is considered supported.
454+
When the snapshot builder encounters a built-in module that cannot be
455+
serialized, it may crash the snapshot building process. In that case a typical
456+
workaround would be to delay loading that module until
457+
runtime, using either [`v8.startupSnapshot.setDeserializeMainFunction()`][] or
458+
[`v8.startupSnapshot.addDeserializeCallback()`][]. If serialization for
459+
an additional module during the snapshot building process is needed,
460+
please file a request in the [tracking issue for user-land snapshots][].
457461

458462
### `--build-snapshot-config`
459463

@@ -463,7 +467,7 @@ added:
463467
- v20.12.0
464468
-->
465469

466-
> Stability: 1 - Experimental
470+
> Stability: 2 - Stable
467471
468472
Specifies the path to a JSON configuration file which configures snapshot
469473
creation behavior.
@@ -4127,7 +4131,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
41274131
[Module customization hooks: enabling]: module.md#enabling
41284132
[Module resolution and loading]: packages.md#module-resolution-and-loading
41294133
[Navigator API]: globals.md#navigator
4130-
[Node.js issue tracker]: https://github.com/nodejs/node/issues
41314134
[OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html
41324135
[Permission Model]: permissions.md#permission-model
41334136
[REPL]: repl.md
@@ -4183,7 +4186,10 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
41834186
[`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version
41844187
[`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version
41854188
[`unhandledRejection`]: process.md#event-unhandledrejection
4189+
[`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data
4190+
[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
41864191
[`v8.startupSnapshot` API]: v8.md#startup-snapshot-api
4192+
[captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24
41874193
[collecting code coverage from tests]: test.md#collecting-code-coverage
41884194
[conditional exports]: packages.md#conditional-exports
41894195
[context-aware]: addons.md#context-aware-addons

0 commit comments

Comments
 (0)