Commit 77faa14
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 92649e2 commit 77faa14
1 file changed
Lines changed: 32 additions & 16 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -403,10 +403,13 @@ Error: Access to this API has been restricted | |||
| 403 | 403 | ||
| 404 | 404 | <!-- YAML | |
| 405 | 405 | 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. | ||
| 406 | 411 | --> | |
| 407 | 412 | ||
| 408 | - > Stability: 1 - Experimental | ||
| 409 | - | ||
| 410 | 413 | Generates a snapshot blob when the process exits and writes it to | |
| 411 | 414 | disk, which can be loaded later with `--snapshot-blob`. | |
| 412 | 415 | ||
@@ -442,29 +445,39 @@ I am from the snapshot | |||
| 442 | 445 | ||
| 443 | 446 | For more information, check out the [`v8.startupSnapshot` API][] documentation. | |
| 444 | 447 | ||
| 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 [Node.js issue tracker][] and link to it in the | ||
| 466 | + [tracking issue for user-land snapshots][]. | ||
| 457 | 467 | ||
| 458 | 468 | ### `--build-snapshot-config` | |
| 459 | 469 | ||
| 460 | 470 | <!-- YAML | |
| 461 | 471 | added: | |
| 462 | 472 | - v21.6.0 | |
| 463 | 473 | - v20.12.0 | |
| 474 | + changes: | ||
| 475 | + - version: | ||
| 476 | + - REPLACEME | ||
| 477 | + pr-url: https://github.com/nodejs/node/pull/60954 | ||
| 478 | + description: The snapshot building process is no longer experimental. | ||
| 464 | 479 | --> | |
| 465 | 480 | ||
| 466 | - > Stability: 1 - Experimental | ||
| 467 | - | ||
| 468 | 481 | Specifies the path to a JSON configuration file which configures snapshot | |
| 469 | 482 | creation behavior. | |
| 470 | 483 | ||
@@ -4175,7 +4188,10 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 | |||
| 4175 | 4188 | [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version | |
| 4176 | 4189 | [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version | |
| 4177 | 4190 | [`unhandledRejection`]: process.md#event-unhandledrejection | |
| 4191 | + [`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data | ||
| 4192 | + [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data | ||
| 4178 | 4193 | [`v8.startupSnapshot` API]: v8.md#startup-snapshot-api | |
| 4194 | + [captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24 | ||
| 4179 | 4195 | [collecting code coverage from tests]: test.md#collecting-code-coverage | |
| 4180 | 4196 | [conditional exports]: packages.md#conditional-exports | |
| 4181 | 4197 | [context-aware]: addons.md#context-aware-addons | |
0 commit comments