Skip to content

Commit 8a67c00

Browse files
joyeecheungaduh95
authored andcommitted
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. PR-URL: #60954 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
1 parent 18e3b91 commit 8a67c00

File tree

1 file changed

+32
-16
lines changed

1 file changed

+32
-16
lines changed

doc/api/cli.md

Lines changed: 32 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -367,10 +367,13 @@ Error: Access to this API has been restricted
367367

368368
<!-- YAML
369369
added: v18.8.0
370+
changes:
371+
- version:
372+
- REPLACEME
373+
pr-url: https://github.com/nodejs/node/pull/60954
374+
description: The snapshot building process is no longer experimental.
370375
-->
371376

372-
> Stability: 1 - Experimental
373-
374377
Generates a snapshot blob when the process exits and writes it to
375378
disk, which can be loaded later with `--snapshot-blob`.
376379

@@ -406,29 +409,39 @@ I am from the snapshot
406409

407410
For more information, check out the [`v8.startupSnapshot` API][] documentation.
408411

409-
Currently the support for run-time snapshot is experimental in that:
410-
411-
1. User-land modules are not yet supported in the snapshot, so only
412-
one single file can be snapshotted. Users can bundle their applications
413-
into a single script with their bundler of choice before building
414-
a snapshot, however.
415-
2. Only a subset of the built-in modules work in the snapshot, though the
416-
Node.js core test suite checks that a few fairly complex applications
417-
can be snapshotted. Support for more modules are being added. If any
418-
crashes or buggy behaviors occur when building a snapshot, please file
419-
a report in the [Node.js issue tracker][] and link to it in the
420-
[tracking issue for user-land snapshots][].
412+
The snapshot currently only supports loding a single entrypoint during the
413+
snapshot building process, which can load built-in modules, but not additional user-land modules.
414+
Users can bundle their applications into a single script with their bundler
415+
of choice before building a snapshot.
416+
417+
As it's complicated to ensure the serializablility of all built-in modules,
418+
which are also growing over time, only a subset of the built-in modules are
419+
well tested to be serializable during the snapshot building process.
420+
The Node.js core test suite checks that a few fairly complex applications
421+
can be snapshotted. The list of built-in modules being
422+
[captured by the built-in snapshot of Node.js][] is considered supported.
423+
When the snapshot builder encounters a built-in module that cannot be
424+
serialized, it may crash the snapshot building process. In that case a typical
425+
workaround would be to delay loading that module until
426+
runtime, using either [`v8.startupSnapshot.setDeserializeMainFunction()`][] or
427+
[`v8.startupSnapshot.addDeserializeCallback()`][]. If serialization for
428+
an additional module during the snapshot building process is needed,
429+
please file a request in the [Node.js issue tracker][] and link to it in the
430+
[tracking issue for user-land snapshots][].
421431

422432
### `--build-snapshot-config`
423433

424434
<!-- YAML
425435
added:
426436
- v21.6.0
427437
- v20.12.0
438+
changes:
439+
- version:
440+
- REPLACEME
441+
pr-url: https://github.com/nodejs/node/pull/60954
442+
description: The snapshot building process is no longer experimental.
428443
-->
429444

430-
> Stability: 1 - Experimental
431-
432445
Specifies the path to a JSON configuration file which configures snapshot
433446
creation behavior.
434447

@@ -4075,7 +4088,10 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
40754088
[`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version
40764089
[`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version
40774090
[`unhandledRejection`]: process.md#event-unhandledrejection
4091+
[`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data
4092+
[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
40784093
[`v8.startupSnapshot` API]: v8.md#startup-snapshot-api
4094+
[captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24
40794095
[collecting code coverage from tests]: test.md#collecting-code-coverage
40804096
[conditional exports]: packages.md#conditional-exports
40814097
[context-aware]: addons.md#context-aware-addons

0 commit comments

Comments
 (0)