Skip to content

Commit 3cbbaa5

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 3cbbaa5

File tree

1 file changed

+31
-17
lines changed

1 file changed

+31
-17
lines changed

doc/api/cli.md

Lines changed: 31 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -403,10 +403,13 @@ Error: Access to this API has been restricted
403403

404404
<!-- YAML
405405
added: v18.8.0
406+
changes:
407+
- version:
408+
- REPLACEME
409+
pr-url: https://github.com/nodejs/node/pull/60954
410+
description: The snapshot building process is no longer experimental.
406411
-->
407412

408-
> Stability: 1 - Experimental
409-
410413
Generates a snapshot blob when the process exits and writes it to
411414
disk, which can be loaded later with `--snapshot-blob`.
412415

@@ -442,29 +445,38 @@ I am from the snapshot
442445

443446
For more information, check out the [`v8.startupSnapshot` API][] documentation.
444447

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][].
448+
The snapshot currently only supports loding a single entrypoint during the
449+
snapshot building process, which can load built-in modules, but not additional user-land modules.
450+
Users can bundle their applications into a single script with their bundler
451+
of choice before building a snapshot.
452+
453+
As it's complicated to ensure the serializablility of all built-in modules,
454+
which are also growing over time, only a subset of the built-in modules are
455+
well tested to be serializable during the snapshot building process.
456+
The Node.js core test suite checks that a few fairly complex applications
457+
can be snapshotted. The list of built-in modules being
458+
[captured by the built-in snapshot of Node.js][] is considered supported.
459+
When the snapshot builder encounters a built-in module that cannot be
460+
serialized, it may crash the snapshot building process. In that case a typical
461+
workaround would be to delay loading that module until
462+
runtime, using either [`v8.startupSnapshot.setDeserializeMainFunction()`][] or
463+
[`v8.startupSnapshot.addDeserializeCallback()`][]. If serialization for
464+
an additional module during the snapshot building process is needed,
465+
please file a request in the [tracking issue for user-land snapshots][].
457466

458467
### `--build-snapshot-config`
459468

460469
<!-- YAML
461470
added:
462471
- v21.6.0
463472
- v20.12.0
473+
changes:
474+
- version:
475+
- REPLACEME
476+
pr-url: https://github.com/nodejs/node/pull/60954
477+
description: The snapshot building process is no longer experimental.
464478
-->
465479

466-
> Stability: 1 - Experimental
467-
468480
Specifies the path to a JSON configuration file which configures snapshot
469481
creation behavior.
470482

@@ -4127,7 +4139,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
41274139
[Module customization hooks: enabling]: module.md#enabling
41284140
[Module resolution and loading]: packages.md#module-resolution-and-loading
41294141
[Navigator API]: globals.md#navigator
4130-
[Node.js issue tracker]: https://github.com/nodejs/node/issues
41314142
[OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html
41324143
[Permission Model]: permissions.md#permission-model
41334144
[REPL]: repl.md
@@ -4183,7 +4194,10 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
41834194
[`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version
41844195
[`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version
41854196
[`unhandledRejection`]: process.md#event-unhandledrejection
4197+
[`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data
4198+
[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
41864199
[`v8.startupSnapshot` API]: v8.md#startup-snapshot-api
4200+
[captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24
41874201
[collecting code coverage from tests]: test.md#collecting-code-coverage
41884202
[conditional exports]: packages.md#conditional-exports
41894203
[context-aware]: addons.md#context-aware-addons

0 commit comments

Comments
 (0)