Commit 8a67c00
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
1 file changed
Lines changed: 32 additions & 16 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -367,10 +367,13 @@ Error: Access to this API has been restricted | |||
| 367 | 367 | ||
| 368 | 368 | <!-- YAML | |
| 369 | 369 | 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. | ||
| 370 | 375 | --> | |
| 371 | 376 | ||
| 372 | - > Stability: 1 - Experimental | ||
| 373 | - | ||
| 374 | 377 | Generates a snapshot blob when the process exits and writes it to | |
| 375 | 378 | disk, which can be loaded later with `--snapshot-blob`. | |
| 376 | 379 | ||
@@ -406,29 +409,39 @@ I am from the snapshot | |||
| 406 | 409 | ||
| 407 | 410 | For more information, check out the [`v8.startupSnapshot` API][] documentation. | |
| 408 | 411 | ||
| 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][]. | ||
| 421 | 431 | ||
| 422 | 432 | ### `--build-snapshot-config` | |
| 423 | 433 | ||
| 424 | 434 | <!-- YAML | |
| 425 | 435 | added: | |
| 426 | 436 | - v21.6.0 | |
| 427 | 437 | - 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. | ||
| 428 | 443 | --> | |
| 429 | 444 | ||
| 430 | - > Stability: 1 - Experimental | ||
| 431 | - | ||
| 432 | 445 | Specifies the path to a JSON configuration file which configures snapshot | |
| 433 | 446 | creation behavior. | |
| 434 | 447 | ||
@@ -4075,7 +4088,10 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 | |||
| 4075 | 4088 | [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version | |
| 4076 | 4089 | [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version | |
| 4077 | 4090 | [`unhandledRejection`]: process.md#event-unhandledrejection | |
| 4091 | + [`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data | ||
| 4092 | + [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data | ||
| 4078 | 4093 | [`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 | ||
| 4079 | 4095 | [collecting code coverage from tests]: test.md#collecting-code-coverage | |
| 4080 | 4096 | [conditional exports]: packages.md#conditional-exports | |
| 4081 | 4097 | [context-aware]: addons.md#context-aware-addons | |
0 commit comments