1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc, src: sort + fill up cli options and env vars

Browse Source 
* Alphabetize the command line options and environment
  variables in doc/api/cli.md for consistency and readability.

* Update doc/api/cli.md to include command line options
  being printed in the `node.PrintHelp()` function in src/node.cc
  but weren't otherwise documented in the cli spec. Options added
  include:

  --napi-modules
  --v8-pool-size=num
  --experimental-modules
  --experimental-vm-modules

* ASCII sort the node man page command line options.
  This change brings sort order consistency between the
  cli options displayed in doc/node.1 and the cli options
  enumerated in other areas of the project.

  Also rearrange the language for `--use-bundled-ca`, `--use-openssl-ca`
  to correspond with the order of the options as displayed.

* Update `node.PrintHelp()` function to return command line options
  and environment variables sorted in ASCII order. Additionally,
  add missing options as sourced from doc/api/cli.md. Options
  added include `--`, `--help` and the `NODE_PRESERVE_SYMLINKS`
  environment variable.

  Also update the comments in the `node.PrintHelp()` method
  to C++ style.

* Create tests to validate that the newly ASCII sorted
  cli options in the `node.PrintHelp()` function are being
  returned according to build configurations as expected.

PR-URL: https://github.com/nodejs/node/pull/19878
Refs: https://github.com/nodejs/node/issues/19814
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Khaidi Chu <i@2333.moe>
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
willhayslett 2018-04-08 01:33:19 -05:00 committed by Vse Mozhet Byt
parent 6376d430f4
commit a43e8896f2
4 changed files with 570 additions and 430 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

503
doc/api/cli.md
View File

@ -24,95 +24,79 @@ _For more info about `node debug`, please see the [debugger][] documentation._
## Options ## Options
### `-v`, `--version` ### `-`
<!-- YAML <!-- YAML
added: v0.1.3 added: v8.0.0
--> -->
Print node's version. Alias for stdin, analogous to the use of - in other command line utilities,
meaning that the script will be read from stdin, and the rest of the options
are passed to that script.
### `-h`, `--help` ### `--`
<!-- YAML <!-- YAML
added: v0.1.3 added: v6.11.0
--> -->
Print node command line options. Indicate the end of node options. Pass the rest of the arguments to the script.
The output of this option is less detailed than this document. If no script filename or eval/print script is supplied prior to this, then
the next argument will be used as a script filename.
### `-e`, `--eval "script"` ### `--abort-on-uncaught-exception`
<!-- YAML <!-- YAML
added: v0.5.2 added: v0.10
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
--> -->
Evaluate the following argument as JavaScript. The modules which are Aborting instead of exiting causes a core file to be generated for post-mortem
predefined in the REPL can also be used in `script`. analysis using a debugger (such as `lldb`, `gdb`, and `mdb`).
On Windows, using `cmd.exe` a single quote will not work correctly because it If this flag is passed, the behavior can still be set to not abort through
only recognizes double `"` for quoting. In Powershell or Git bash, both `'` [`process.setUncaughtExceptionCaptureCallback()`][] (and through usage of the
and `"` are usable. `domain` module that uses it).
### `-p`, `--print "script"` ### `--enable-fips`
<!-- YAML <!-- YAML
added: v0.6.4 added: v6.0.0
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
--> -->
Identical to `-e` but prints the result. Enable FIPS-compliant crypto at startup. (Requires Node.js to be built with
`./configure --openssl-fips`)
### `-c`, `--check` ### `--experimental-modules`
<!-- YAML <!-- YAML
added: added: v8.5.0
- v5.0.0
- v4.2.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/19600
description: The `--require` option is now supported when checking a file.
--> -->
Syntax check the script without executing. Enable experimental ES module support and caching modules.
### `-i`, `--interactive` ### `--experimental-vm-modules`
<!-- YAML <!-- YAML
added: v0.7.7 added: v9.6.0
--> -->
Opens the REPL even if stdin does not appear to be a terminal. Enable experimental ES Module support in the `vm` module.
### `-r`, `--require module` ### `--force-fips`
<!-- YAML <!-- YAML
added: v1.6.0 added: v6.0.0
--> -->
Preload the specified module at startup. Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.)
(Same requirements as `--enable-fips`)
Follows `require()`'s module resolution
rules. `module` may be either a path to a file, or a node module name.
### `--inspect[=[host:]port]` ### `--icu-data-dir=file`
<!-- YAML <!-- YAML
added: v6.3.0 added: v0.11.15
--> -->
Activate inspector on host:port. Default is 127.0.0.1:9229. Specify ICU data load path. (overrides `NODE_ICU_DATA`)
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug
and profile Node.js instances. The tools attach to Node.js instances via a
tcp port and communicate using the [Chrome Debugging Protocol][].
### `--inspect-brk[=[host:]port]` ### `--inspect-brk[=[host:]port]`
@ -135,6 +119,27 @@ Useful when activating the inspector by sending the `SIGUSR1` signal.
Default host is 127.0.0.1. Default host is 127.0.0.1.
### `--inspect[=[host:]port]`
<!-- YAML
added: v6.3.0
-->
Activate inspector on host:port. Default is 127.0.0.1:9229.
V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug
and profile Node.js instances. The tools attach to Node.js instances via a
tcp port and communicate using the [Chrome Debugging Protocol][].
### `--napi-modules`
<!-- YAML
added: v7.10.0
-->
Enable loading native modules compiled with the ABI-stable Node.js API (N-API)
(experimental).
### `--no-deprecation` ### `--no-deprecation`
<!-- YAML <!-- YAML
added: v0.8.0 added: v0.8.0
@ -143,20 +148,32 @@ added: v0.8.0
Silence deprecation warnings. Silence deprecation warnings.
### `--trace-deprecation` ### `--no-force-async-hooks-checks`
<!-- YAML <!-- YAML
added: v0.8.0 added: v9.0.0
--> -->
Print stack traces for deprecations. Disables runtime checks for `async_hooks`. These will still be enabled
dynamically when `async_hooks` is enabled.
### `--throw-deprecation` ### `--no-warnings`
<!-- YAML <!-- YAML
added: v0.11.14 added: v6.0.0
--> -->
Throw errors for deprecations. Silence all process warnings (including deprecations).
### `--openssl-config=file`
<!-- YAML
added: v6.9.0
-->
Load an OpenSSL configuration file on startup. Among other uses, this can be
used to enable FIPS-compliant crypto if Node.js is built with
`./configure --openssl-fips`.
### `--pending-deprecation` ### `--pending-deprecation`
<!-- YAML <!-- YAML
@ -172,89 +189,6 @@ unless either the `--pending-deprecation` command line flag, or the
are used to provide a kind of selective "early warning" mechanism that are used to provide a kind of selective "early warning" mechanism that
developers may leverage to detect deprecated API usage. developers may leverage to detect deprecated API usage.
### `--no-warnings`
<!-- YAML
added: v6.0.0
-->
Silence all process warnings (including deprecations).
### `--abort-on-uncaught-exception`
<!-- YAML
added: v0.10
-->
Aborting instead of exiting causes a core file to be generated for post-mortem
analysis using a debugger (such as `lldb`, `gdb`, and `mdb`).
If this flag is passed, the behavior can still be set to not abort through
[`process.setUncaughtExceptionCaptureCallback()`][] (and through usage of the
`domain` module that uses it).
### `--trace-warnings`
<!-- YAML
added: v6.0.0
-->
Print stack traces for process warnings (including deprecations).
### `--redirect-warnings=file`
<!-- YAML
added: v8.0.0
-->
Write process warnings to the given file instead of printing to stderr. The
file will be created if it does not exist, and will be appended to if it does.
If an error occurs while attempting to write the warning to the file, the
warning will be written to stderr instead.
### `--trace-sync-io`
<!-- YAML
added: v2.1.0
-->
Prints a stack trace whenever synchronous I/O is detected after the first turn
of the event loop.
### `--no-force-async-hooks-checks`
<!-- YAML
added: v9.0.0
-->
Disables runtime checks for `async_hooks`. These will still be enabled
dynamically when `async_hooks` is enabled.
### `--trace-events-enabled`
<!-- YAML
added: v7.7.0
-->
Enables the collection of trace event tracing information.
### `--trace-event-categories`
<!-- YAML
added: v7.7.0
-->
A comma separated list of categories that should be traced when trace event
tracing is enabled using `--trace-events-enabled`.
### `--trace-event-file-pattern`
<!-- YAML
added: v9.8.0
-->
Template string specifying the filepath for the trace event data, it
supports `${rotation}` and `${pid}`.
### `--zero-fill-buffers`
<!-- YAML
added: v6.0.0
-->
Automatically zero-fills all newly allocated [Buffer][] and [SlowBuffer][]
instances.
### `--preserve-symlinks` ### `--preserve-symlinks`
<!-- YAML <!-- YAML
@ -296,6 +230,94 @@ are linked from more than one location in the dependency tree (Node.js would
see those as two separate modules and would attempt to load the module multiple see those as two separate modules and would attempt to load the module multiple
times, causing an exception to be thrown). times, causing an exception to be thrown).
### `--prof-process`
<!-- YAML
added: v5.2.0
-->
Process V8 profiler output generated using the V8 option `--prof`.
### `--redirect-warnings=file`
<!-- YAML
added: v8.0.0
-->
Write process warnings to the given file instead of printing to stderr. The
file will be created if it does not exist, and will be appended to if it does.
If an error occurs while attempting to write the warning to the file, the
warning will be written to stderr instead.
### `--throw-deprecation`
<!-- YAML
added: v0.11.14
-->
Throw errors for deprecations.
### `--tls-cipher-list=list`
<!-- YAML
added: v4.0.0
-->
Specify an alternative default TLS cipher list. (Requires Node.js to be built
with crypto support. (Default))
### `--trace-deprecation`
<!-- YAML
added: v0.8.0
-->
Print stack traces for deprecations.
### `--trace-event-categories`
<!-- YAML
added: v7.7.0
-->
A comma separated list of categories that should be traced when trace event
tracing is enabled using `--trace-events-enabled`.
### `--trace-event-file-pattern`
<!-- YAML
added: v9.8.0
-->
Template string specifying the filepath for the trace event data, it
supports `${rotation}` and `${pid}`.
### `--trace-events-enabled`
<!-- YAML
added: v7.7.0
-->
Enables the collection of trace event tracing information.
### `--trace-sync-io`
<!-- YAML
added: v2.1.0
-->
Prints a stack trace whenever synchronous I/O is detected after the first turn
of the event loop.
### `--trace-warnings`
<!-- YAML
added: v6.0.0
-->
Print stack traces for process warnings (including deprecations).
### `--track-heap-objects` ### `--track-heap-objects`
<!-- YAML <!-- YAML
added: v2.4.0 added: v2.4.0
@ -304,12 +326,25 @@ added: v2.4.0
Track heap object allocations for heap snapshots. Track heap object allocations for heap snapshots.
### `--prof-process` ### `--use-bundled-ca`, `--use-openssl-ca`
<!-- YAML <!-- YAML
added: v5.2.0 added: v6.11.0
--> -->
Process V8 profiler output generated using the V8 option `--prof`. Use bundled Mozilla CA store as supplied by current Node.js version
or use OpenSSL's default CA store. The default store is selectable
at build-time.
The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store
that is fixed at release time. It is identical on all supported platforms.
Using OpenSSL store allows for external modifications of the store. For most
Linux and BSD distributions, this store is maintained by the distribution
maintainers and system administrators. OpenSSL CA store location is dependent on
configuration of the OpenSSL library but this can be altered at runtime using
environment variables.
See `SSL_CERT_DIR` and `SSL_CERT_FILE`.
### `--v8-options` ### `--v8-options`
@ -324,87 +359,107 @@ underscores (`_`).
For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`. For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`.
### `--tls-cipher-list=list`
### `--v8-pool-size=num`
<!-- YAML <!-- YAML
added: v4.0.0 added: v5.10.0
--> -->
Specify an alternative default TLS cipher list. (Requires Node.js to be built Set V8's thread pool size which will be used to allocate background jobs.
with crypto support. (Default))
If set to `0` then V8 will choose an appropriate size of the thread pool based
on the number of online processors.
If the value provided is larger than V8's maximum, then the largest value
will be chosen.
### `--enable-fips` ### `--zero-fill-buffers`
<!-- YAML <!-- YAML
added: v6.0.0 added: v6.0.0
--> -->
Enable FIPS-compliant crypto at startup. (Requires Node.js to be built with Automatically zero-fills all newly allocated [Buffer][] and [SlowBuffer][]
`./configure --openssl-fips`) instances.
### `--force-fips` ### `-c`, `--check`
<!-- YAML <!-- YAML
added: v6.0.0 added:
- v5.0.0
- v4.2.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/19600
description: The `--require` option is now supported when checking a file.
--> -->
Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.) Syntax check the script without executing.
(Same requirements as `--enable-fips`)
### `--openssl-config=file` ### `-e`, `--eval "script"`
<!-- YAML <!-- YAML
added: v6.9.0 added: v0.5.2
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
--> -->
Load an OpenSSL configuration file on startup. Among other uses, this can be Evaluate the following argument as JavaScript. The modules which are
used to enable FIPS-compliant crypto if Node.js is built with predefined in the REPL can also be used in `script`.
`./configure --openssl-fips`.
### `--use-openssl-ca`, `--use-bundled-ca` On Windows, using `cmd.exe` a single quote will not work correctly because it
only recognizes double `"` for quoting. In Powershell or Git bash, both `'`
and `"` are usable.
### `-h`, `--help`
<!-- YAML <!-- YAML
added: v6.11.0 added: v0.1.3
--> -->
Use OpenSSL's default CA store or use bundled Mozilla CA store as supplied by Print node command line options.
current Node.js version. The default store is selectable at build-time. The output of this option is less detailed than this document.
Using OpenSSL store allows for external modifications of the store. For most
Linux and BSD distributions, this store is maintained by the distribution
maintainers and system administrators. OpenSSL CA store location is dependent on
configuration of the OpenSSL library but this can be altered at runtime using
environment variables.
The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store ### `-i`, `--interactive`
that is fixed at release time. It is identical on all supported platforms.
See `SSL_CERT_DIR` and `SSL_CERT_FILE`.
### `--icu-data-dir=file`
<!-- YAML <!-- YAML
added: v0.11.15 added: v0.7.7
--> -->
Specify ICU data load path. (overrides `NODE_ICU_DATA`) Opens the REPL even if stdin does not appear to be a terminal.
### `-` ### `-p`, `--print "script"`
<!-- YAML <!-- YAML
added: v8.0.0 added: v0.6.4
changes:
- version: v5.11.0
pr-url: https://github.com/nodejs/node/pull/5348
description: Built-in libraries are now available as predefined variables.
--> -->
Alias for stdin, analogous to the use of - in other command line utilities, Identical to `-e` but prints the result.
meaning that the script will be read from stdin, and the rest of the options
are passed to that script.
### `--` ### `-r`, `--require module`
<!-- YAML <!-- YAML
added: v6.11.0 added: v1.6.0
--> -->
Indicate the end of node options. Pass the rest of the arguments to the script. Preload the specified module at startup.
If no script filename or eval/print script is supplied prior to this, then
the next argument will be used as a script filename. Follows `require()`'s module resolution
rules. `module` may be either a path to a file, or a node module name.
### `-v`, `--version`
<!-- YAML
added: v0.1.3
-->
Print node's version.
## Environment Variables ## Environment Variables
@ -416,16 +471,6 @@ added: v0.1.32
`','`-separated list of core modules that should print debug information. `','`-separated list of core modules that should print debug information.
### `NODE_PATH=path[:…]`
<!-- YAML
added: v0.1.32
-->
`':'`-separated list of directories prefixed to the module search path.
On Windows, this is a `';'`-separated list instead.
### `NODE_DISABLE_COLORS=1` ### `NODE_DISABLE_COLORS=1`
<!-- YAML <!-- YAML
added: v0.3.0 added: v0.3.0
@ -434,6 +479,21 @@ added: v0.3.0
When set to `1` colors will not be used in the REPL. When set to `1` colors will not be used in the REPL.
### `NODE_EXTRA_CA_CERTS=file`
<!-- YAML
added: v7.3.0
-->
When set, the well known "root" CAs (like VeriSign) will be extended with the
extra certificates in `file`. The file should consist of one or more trusted
certificates in PEM format. A message will be emitted (once) with
[`process.emitWarning()`][emit_warning] if the file is missing or
malformed, but any errors are otherwise ignored.
Note that neither the well known nor extra certificates are used when the `ca`
options property is explicitly specified for a TLS or HTTPS client or server.
### `NODE_ICU_DATA=file` ### `NODE_ICU_DATA=file`
<!-- YAML <!-- YAML
added: v0.11.15 added: v0.11.15
@ -442,6 +502,7 @@ added: v0.11.15
Data path for ICU (Intl object) data. Will extend linked-in data when compiled Data path for ICU (Intl object) data. Will extend linked-in data when compiled
with small-icu support. with small-icu support.
### `NODE_NO_WARNINGS=1` ### `NODE_NO_WARNINGS=1`
<!-- YAML <!-- YAML
added: v6.11.0 added: v6.11.0
@ -449,6 +510,7 @@ added: v6.11.0
When set to `1`, process warnings are silenced. When set to `1`, process warnings are silenced.
### `NODE_OPTIONS=options...` ### `NODE_OPTIONS=options...`
<!-- YAML <!-- YAML
added: v8.0.0 added: v8.0.0
@ -492,6 +554,17 @@ V8 options that are allowed are:
- `--perf-prof` - `--perf-prof`
- `--stack-trace-limit` - `--stack-trace-limit`
### `NODE_PATH=path[:…]`
<!-- YAML
added: v0.1.32
-->
`':'`-separated list of directories prefixed to the module search path.
On Windows, this is a `';'`-separated list instead.
### `NODE_PENDING_DEPRECATION=1` ### `NODE_PENDING_DEPRECATION=1`
<!-- YAML <!-- YAML
added: v8.0.0 added: v8.0.0
@ -506,6 +579,7 @@ unless either the `--pending-deprecation` command line flag, or the
are used to provide a kind of selective "early warning" mechanism that are used to provide a kind of selective "early warning" mechanism that
developers may leverage to detect deprecated API usage. developers may leverage to detect deprecated API usage.
### `NODE_PRESERVE_SYMLINKS=1` ### `NODE_PRESERVE_SYMLINKS=1`
<!-- YAML <!-- YAML
added: v7.1.0 added: v7.1.0
@ -514,6 +588,19 @@ added: v7.1.0
When set to `1`, instructs the module loader to preserve symbolic links when When set to `1`, instructs the module loader to preserve symbolic links when
resolving and caching modules. resolving and caching modules.
### `NODE_REDIRECT_WARNINGS=file`
<!-- YAML
added: v8.0.0
-->
When set, process warnings will be emitted to the given file instead of
printing to stderr. The file will be created if it does not exist, and will be
appended to if it does. If an error occurs while attempting to write the
warning to the file, the warning will be written to stderr instead. This is
equivalent to using the `--redirect-warnings=file` command-line flag.
### `NODE_REPL_HISTORY=file` ### `NODE_REPL_HISTORY=file`
<!-- YAML <!-- YAML
added: v3.0.0 added: v3.0.0
@ -524,20 +611,6 @@ Path to the file used to store the persistent REPL history. The default path is
to an empty string (`''` or `' '`) disables persistent REPL history. to an empty string (`''` or `' '`) disables persistent REPL history.
### `NODE_EXTRA_CA_CERTS=file`
<!-- YAML
added: v7.3.0
-->
When set, the well known "root" CAs (like VeriSign) will be extended with the
extra certificates in `file`. The file should consist of one or more trusted
certificates in PEM format. A message will be emitted (once) with
[`process.emitWarning()`][emit_warning] if the file is missing or
malformed, but any errors are otherwise ignored.
Note that neither the well known nor extra certificates are used when the `ca`
options property is explicitly specified for a TLS or HTTPS client or server.
### `OPENSSL_CONF=file` ### `OPENSSL_CONF=file`
<!-- YAML <!-- YAML
added: v6.11.0 added: v6.11.0
@ -550,6 +623,7 @@ used to enable FIPS-compliant crypto if Node.js is built with `./configure
If the [`--openssl-config`][] command line option is used, the environment If the [`--openssl-config`][] command line option is used, the environment
variable is ignored. variable is ignored.
### `SSL_CERT_DIR=dir` ### `SSL_CERT_DIR=dir`
<!-- YAML <!-- YAML
added: v7.7.0 added: v7.7.0
@ -562,6 +636,7 @@ Be aware that unless the child environment is explicitly set, this environment
variable will be inherited by any child processes, and if they use OpenSSL, it variable will be inherited by any child processes, and if they use OpenSSL, it
may cause them to trust the same CAs as node. may cause them to trust the same CAs as node.
### `SSL_CERT_FILE=file` ### `SSL_CERT_FILE=file`
<!-- YAML <!-- YAML
added: v7.7.0 added: v7.7.0
@ -574,16 +649,6 @@ Be aware that unless the child environment is explicitly set, this environment
variable will be inherited by any child processes, and if they use OpenSSL, it variable will be inherited by any child processes, and if they use OpenSSL, it
may cause them to trust the same CAs as node. may cause them to trust the same CAs as node.
### `NODE_REDIRECT_WARNINGS=file`
<!-- YAML
added: v8.0.0
-->
When set, process warnings will be emitted to the given file instead of
printing to stderr. The file will be created if it does not exist, and will be
appended to if it does. If an error occurs while attempting to write the
warning to the file, the warning will be written to stderr instead. This is
equivalent to using the `--redirect-warnings=file` command-line flag.
### `UV_THREADPOOL_SIZE=size` ### `UV_THREADPOOL_SIZE=size`

255
doc/node.1
View File

@ -61,46 +61,41 @@ without arguments to start a REPL.
. .
.Sh OPTIONS .Sh OPTIONS
.Bl -tag -width 6n .Bl -tag -width 6n
.It Fl v , Fl -version .It Sy \-
Print node's version. Alias for stdin, analogous to the use of - in other command-line utilities.
The executed script is read from stdin, and remaining arguments are passed to the script.
. .
.It Fl h , Fl -help .It Fl \-
Print node command line options. Indicate the end of node options.
The output of this option is less detailed than this document. Pass the rest of the arguments to the script.
.
.It Fl e , Fl -eval Ar string
Evaluate
.Ar string
as JavaScript.
.
.It Fl p , Fl -print Ar string
Identical to
.Fl e ,
but prints the result.
.
.It Fl c , Fl -check
Check the script's syntax without executing it.
Exits with an error code if script is invalid.
.
.It Fl i , Fl -interactive
Open the REPL even if stdin does not appear to be a terminal.
.
.It Fl r , Fl -require Ar module
Preload the specified
.Ar module
at startup.
Follows `require()`'s module resolution rules.
.Ar module
may be either a path to a file, or a node module name.
.
.It Fl -inspect Ns = Ns Ar [host:]port
Activate inspector on
.Ar host:port .
Default is
.Sy 127.0.0.1:9229 .
.Pp .Pp
V8 Inspector integration allows attaching Chrome DevTools and IDEs to Node.js instances for debugging and profiling. If no script filename or eval/print script is supplied prior to this, then
It uses the Chrome Debugging Protocol. the next argument will be used as a script filename.
.
.It Fl -abort-on-uncaught-exception
Aborting instead of exiting causes a core file to be generated for analysis.
.
.It Fl -enable-fips
Enable FIPS-compliant crypto at startup.
Requires Node.js to be built with
.Sy ./configure --openssl-fips .
.
.It Fl \-experimental-modules
Enable experimental ES module support and caching modules.
.
.It Fl \-experimental-vm-modules
Enable experimental ES module support in VM module.
.
.It Fl -force-fips
Force FIPS-compliant crypto on startup
(Cannot be disabled from script code).
Same requirements as
.Fl -enable-fips .
.
.It Fl -icu-data-dir Ns = Ns Ar file
Specify ICU data load path.
Overrides
.Ev NODE_ICU_DATA .
. .
.It Fl -inspect-brk Ns = Ns Ar [host:]port .It Fl -inspect-brk Ns = Ns Ar [host:]port
Activate inspector on Activate inspector on
@ -112,45 +107,58 @@ Set the
.Ar host:port .Ar host:port
to be used when the inspector is activated. to be used when the inspector is activated.
. .
.It Fl -no-deprecation .It Fl -inspect Ns = Ns Ar [host:]port
Silence deprecation warnings. Activate inspector on
. .Ar host:port .
.It Fl -trace-deprecation Default is
Print stack traces for deprecations. .Sy 127.0.0.1:9229 .
. .Pp
.It Fl -throw-deprecation V8 Inspector integration allows attaching Chrome DevTools and IDEs to Node.js instances for debugging and profiling.
Throw errors for deprecations. It uses the Chrome Debugging Protocol.
.
.It Fl -pending-deprecation
Emit pending deprecation warnings.
.
.It Fl -no-warnings
Silence all process warnings (including deprecations).
. .
.It Fl -napi-modules .It Fl -napi-modules
Enable loading native modules compiled with the ABI-stable Node.js API (N-API) Enable loading native modules compiled with the ABI-stable Node.js API (N-API)
(experimental). (experimental).
. .
.It Fl -abort-on-uncaught-exception .It Fl -no-deprecation
Aborting instead of exiting causes a core file to be generated for analysis. Silence deprecation warnings.
. .
.It Fl -trace-warnings .It Fl -no-force-async-hooks-checks
Print stack traces for process warnings (including deprecations). Disable runtime checks for `async_hooks`.
These will still be enabled dynamically when `async_hooks` is enabled.
.
.It Fl -no-warnings
Silence all process warnings (including deprecations).
.
.It Fl -openssl-config Ns = Ns Ar file
Load an OpenSSL configuration file on startup.
Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is built with
.Sy ./configure --openssl-fips .
.
.It Fl -pending-deprecation
Emit pending deprecation warnings.
.
.It Fl -preserve-symlinks
Instructs the module loader to preserve symbolic links when resolving and caching modules.
.
.It Fl -prof-process
Process V8 profiler output generated using the V8 option
.Fl -prof .
. .
.It Fl -redirect-warnings Ns = Ns Ar file .It Fl -redirect-warnings Ns = Ns Ar file
Write process warnings to the given Write process warnings to the given
.Ar file .Ar file
instead of printing to stderr. instead of printing to stderr.
. .
.It Fl -trace-sync-io .It Fl -throw-deprecation
Print a stack trace whenever synchronous I/O is detected after the first turn of the event loop. Throw errors for deprecations.
. .
.It Fl -no-force-async-hooks-checks .It Fl -tls-cipher-list Ns = Ns Ar list
Disable runtime checks for `async_hooks`. Specify an alternative default TLS cipher list.
These will still be enabled dynamically when `async_hooks` is enabled. Requires Node.js to be built with crypto support. (Default)
. .
.It Fl -trace-events-enabled .It Fl -trace-deprecation
Enable the collection of trace event tracing information. Print stack traces for deprecations.
. .
.It Fl -trace-event-categories Ar categories .It Fl -trace-event-categories Ar categories
A comma-separated list of categories that should be traced when trace event tracing is enabled using A comma-separated list of categories that should be traced when trace event tracing is enabled using
@ -160,18 +168,33 @@ A comma-separated list of categories that should be traced when trace event trac
Template string specifying the filepath for the trace event data, it Template string specifying the filepath for the trace event data, it
supports \fB${rotation}\fR and \fB${pid}\fR. supports \fB${rotation}\fR and \fB${pid}\fR.
. .
.It Fl -zero-fill-buffers .It Fl -trace-events-enabled
Automatically zero-fills all newly allocated Buffer and SlowBuffer instances. Enable the collection of trace event tracing information.
. .
.It Fl -preserve-symlinks .It Fl -trace-sync-io
Instructs the module loader to preserve symbolic links when resolving and caching modules. Print a stack trace whenever synchronous I/O is detected after the first turn of the event loop.
.
.It Fl -trace-warnings
Print stack traces for process warnings (including deprecations).
. .
.It Fl -track-heap-objects .It Fl -track-heap-objects
Track heap object allocations for heap snapshots. Track heap object allocations for heap snapshots.
. .
.It Fl -prof-process .It Fl -use-bundled\-ca, Fl -use-openssl-ca
Process V8 profiler output generated using the V8 option Use bundled Mozilla CA store as supplied by current Node.js version or use OpenSSL's default CA store.
.Fl -prof . The default store is selectable at build-time.
.Pp
The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store that is fixed at release time.
It is identical on all supported platforms.
.Pp
Using OpenSSL store allows for external modifications of the store.
For most Linux and BSD distributions, this store is maintained by the distribution maintainers and system administrators.
OpenSSL CA store location is dependent on configuration of the OpenSSL library but this can be altered at runtime using environment variables.
.Pp
See
.Ev SSL_CERT_DIR
and
.Ev SSL_CERT_FILE .
. .
.It Fl -v8-options .It Fl -v8-options
Print V8 command-line options. Print V8 command-line options.
@ -188,63 +211,40 @@ Set V8's thread pool size which will be used to allocate background jobs.
If set to 0 then V8 will choose an appropriate size of the thread pool based on the number of online processors. If set to 0 then V8 will choose an appropriate size of the thread pool based on the number of online processors.
If the value provided is larger than V8's maximum, then the largest value will be chosen. If the value provided is larger than V8's maximum, then the largest value will be chosen.
. .
.It Fl -tls-cipher-list Ns = Ns Ar list .It Fl -zero-fill-buffers
Specify an alternative default TLS cipher list. Automatically zero-fills all newly allocated Buffer and SlowBuffer instances.
Requires Node.js to be built with crypto support. (Default)
. .
.It Fl -enable-fips .It Fl c , Fl -check
Enable FIPS-compliant crypto at startup. Check the script's syntax without executing it.
Requires Node.js to be built with Exits with an error code if script is invalid.
.Sy ./configure --openssl-fips .
. .
.It Fl -force-fips .It Fl e , Fl -eval Ar string
Force FIPS-compliant crypto on startup Evaluate
(Cannot be disabled from script code). .Ar string
Same requirements as as JavaScript.
.Fl -enable-fips .
. .
.It Fl -openssl-config Ns = Ns Ar file .It Fl h , Fl -help
Load an OpenSSL configuration file on startup. Print node command line options.
Among other uses, this can be used to enable FIPS-compliant crypto if Node.js is built with The output of this option is less detailed than this document.
.Sy ./configure --openssl-fips .
. .
.It Fl -use-openssl-ca , Fl -use-bundled\-ca .It Fl i , Fl -interactive
Use OpenSSL's default CA store or use bundled Mozilla CA store as supplied by current Node.js version. Open the REPL even if stdin does not appear to be a terminal.
The default store is selectable at build-time.
.Pp
Using OpenSSL store allows for external modifications of the store.
For most Linux and BSD distributions, this store is maintained by the distribution maintainers and system administrators.
OpenSSL CA store location is dependent on configuration of the OpenSSL library but this can be altered at runtime using environment variables.
.Pp
The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store that is fixed at release time.
It is identical on all supported platforms.
.Pp
See
.Ev SSL_CERT_DIR
and
.Ev SSL_CERT_FILE .
. .
.It Fl -icu-data-dir Ns = Ns Ar file .It Fl p , Fl -print Ar string
Specify ICU data load path. Identical to
Overrides .Fl e ,
.Ev NODE_ICU_DATA . but prints the result.
. .
.It Fl \-experimental-modules .It Fl r , Fl -require Ar module
Enable experimental ES module support and caching modules. Preload the specified
.Ar module
at startup.
Follows `require()`'s module resolution rules.
.Ar module
may be either a path to a file, or a node module name.
. .
.It Fl \-experimental-vm-modules .It Fl v , Fl -version
Enable experimental ES module support in VM module. Print node's version.
.
.It Sy \-
Alias for stdin, analogous to the use of - in other command-line utilities.
The executed script is read from stdin, and remaining arguments are passed to the script.
.
.It Fl \-
Indicate the end of node options.
Pass the rest of the arguments to the script.
.Pp
If no script filename or eval/print script is supplied prior to this, then
the next argument will be used as a script filename.
.El .El
. .
.\" ===================================================================== .\" =====================================================================
@ -298,6 +298,13 @@ When set to
.Ar 1 , .Ar 1 ,
emit pending deprecation warnings. emit pending deprecation warnings.
. .
.It Ev NODE_REDIRECT_WARNINGS Ar file
Write process warnings to the given
.Ar file
instead of printing to stderr.
Equivalent to passing
.Fl -redirect-warnings Ar file
on command-line.
.It Ev NODE_REPL_HISTORY Ar file .It Ev NODE_REPL_HISTORY Ar file
Path to the Path to the
.Ar file .Ar file
@ -325,14 +332,6 @@ is enabled, this overrides and sets OpenSSL's directory containing trusted certi
If If
.Fl -use-openssl-ca .Fl -use-openssl-ca
is enabled, this overrides and sets OpenSSL's file containing trusted certificates. is enabled, this overrides and sets OpenSSL's file containing trusted certificates.
.
.It Ev NODE_REDIRECT_WARNINGS Ar file
Write process warnings to the given
.Ar file
instead of printing to stderr.
Equivalent to passing
.Fl -redirect-warnings Ar file
on command-line.
.El .El
. .
.\"===================================================================== .\"=====================================================================

184
src/node.cc
View File

@ -3445,62 +3445,79 @@ static void PrintHelp() {
" node inspect script.js [arguments]\n" " node inspect script.js [arguments]\n"
"\n" "\n"
"Options:\n" "Options:\n"
" -v, --version print Node.js version\n" " - script read from stdin (default; \n"
" -e, --eval script evaluate script\n" " interactive mode if a tty)\n"
" -p, --print evaluate script and print result\n" " -- indicate the end of node options\n"
" -c, --check syntax check script without executing\n" " --abort-on-uncaught-exception\n"
" -i, --interactive always enter the REPL even if stdin\n" " aborting instead of exiting causes a\n"
" does not appear to be a terminal\n" " core file to be generated for analysis\n"
" -r, --require module to preload (option can be " #if HAVE_OPENSSL && NODE_FIPS_MODE
"repeated)\n" " --enable-fips enable FIPS crypto at startup\n"
" - script read from stdin (default; " #endif // NODE_FIPS_MODE && NODE_FIPS_MODE
"interactive mode if a tty)\n" #if defined(NODE_HAVE_I18N_SUPPORT)
" --experimental-modules experimental ES Module support\n"
" and caching modules\n"
" --experimental-vm-modules experimental ES Module support\n"
" in vm module\n"
#endif // defined(NODE_HAVE_I18N_SUPPORT)
#if HAVE_OPENSSL && NODE_FIPS_MODE
" --force-fips force FIPS crypto (cannot be disabled)\n"
#endif // HAVE_OPENSSL && NODE_FIPS_MODE
#if defined(NODE_HAVE_I18N_SUPPORT)
" --icu-data-dir=dir set ICU data load path to dir\n"
" (overrides NODE_ICU_DATA)\n"
#if !defined(NODE_HAVE_SMALL_ICU)
" note: linked-in ICU data is present\n"
#endif
#endif // defined(NODE_HAVE_I18N_SUPPORT)
#if HAVE_INSPECTOR #if HAVE_INSPECTOR
" --inspect[=[host:]port] activate inspector on host:port\n"
" (default: 127.0.0.1:9229)\n"
" --inspect-brk[=[host:]port]\n" " --inspect-brk[=[host:]port]\n"
" activate inspector on host:port\n" " activate inspector on host:port\n"
" and break at start of user script\n" " and break at start of user script\n"
" --inspect-port=[host:]port\n" " --inspect-port=[host:]port\n"
" set host:port for inspector\n" " set host:port for inspector\n"
#endif " --inspect[=[host:]port] activate inspector on host:port\n"
" --no-deprecation silence deprecation warnings\n" " (default: 127.0.0.1:9229)\n"
" --trace-deprecation show stack traces on deprecations\n" #endif // HAVE_INSPECTOR
" --throw-deprecation throw an exception on deprecations\n"
" --pending-deprecation emit pending deprecation warnings\n"
" --no-warnings silence all process warnings\n"
" --napi-modules load N-API modules (no-op - option\n" " --napi-modules load N-API modules (no-op - option\n"
" kept for compatibility)\n" " kept for compatibility)\n"
" --abort-on-uncaught-exception\n" " --no-deprecation silence deprecation warnings\n"
" aborting instead of exiting causes a\n" " --no-force-async-hooks-checks\n"
" core file to be generated for analysis\n" " disable checks for async_hooks\n"
" --trace-warnings show stack traces on process warnings\n" " --no-warnings silence all process warnings\n"
#if HAVE_OPENSSL
" --openssl-config=file load OpenSSL configuration from the\n"
" specified file (overrides\n"
" OPENSSL_CONF)\n"
#endif // HAVE_OPENSSL
" --pending-deprecation emit pending deprecation warnings\n"
#if defined(NODE_HAVE_I18N_SUPPORT)
" --preserve-symlinks preserve symbolic links when resolving\n"
#endif
" --prof-process process v8 profiler output generated\n"
" using --prof\n"
" --redirect-warnings=file\n" " --redirect-warnings=file\n"
" write warnings to file instead of\n" " write warnings to file instead of\n"
" stderr\n" " stderr\n"
" --trace-sync-io show stack trace when use of sync IO\n" " --throw-deprecation throw an exception on deprecations\n"
" is detected after the first tick\n" #if HAVE_OPENSSL
" --no-force-async-hooks-checks\n" " --tls-cipher-list=val use an alternative default TLS cipher "
" disable checks for async_hooks\n" "list\n"
" --trace-events-enabled track trace events\n" #endif // HAVE_OPENSSL
" --trace-deprecation show stack traces on deprecations\n"
" --trace-event-categories comma separated list of trace event\n" " --trace-event-categories comma separated list of trace event\n"
" categories to record\n" " categories to record\n"
" --trace-event-file-pattern Template string specifying the\n" " --trace-event-file-pattern Template string specifying the\n"
" filepath for the trace-events data, it\n" " filepath for the trace-events data, it\n"
" supports ${rotation} and ${pid}\n" " supports ${rotation} and ${pid}\n"
" log-rotation id. %%2$u is the pid.\n" " log-rotation id. %%2$u is the pid.\n"
" --trace-events-enabled track trace events\n"
" --trace-sync-io show stack trace when use of sync IO\n"
" is detected after the first tick\n"
" --trace-warnings show stack traces on process warnings\n"
" --track-heap-objects track heap object allocations for heap " " --track-heap-objects track heap object allocations for heap "
"snapshots\n" "snapshots\n"
" --prof-process process v8 profiler output generated\n"
" using --prof\n"
" --zero-fill-buffers automatically zero-fill all newly "
"allocated\n"
" Buffer and SlowBuffer instances\n"
" --v8-options print v8 command line options\n"
" --v8-pool-size=num set v8's thread pool size\n"
#if HAVE_OPENSSL #if HAVE_OPENSSL
" --tls-cipher-list=val use an alternative default TLS cipher "
"list\n"
" --use-bundled-ca use bundled CA store" " --use-bundled-ca use bundled CA store"
#if !defined(NODE_OPENSSL_CERT_STORE) #if !defined(NODE_OPENSSL_CERT_STORE)
" (default)" " (default)"
@ -3510,27 +3527,23 @@ static void PrintHelp() {
#if defined(NODE_OPENSSL_CERT_STORE) #if defined(NODE_OPENSSL_CERT_STORE)
" (default)" " (default)"
#endif #endif
#endif // HAVE_OPENSSL
"\n" "\n"
#if NODE_FIPS_MODE " --v8-options print v8 command line options\n"
" --enable-fips enable FIPS crypto at startup\n" " --v8-pool-size=num set v8's thread pool size\n"
" --force-fips force FIPS crypto (cannot be disabled)\n" " --zero-fill-buffers automatically zero-fill all newly "
#endif /* NODE_FIPS_MODE */ "allocated\n"
" --openssl-config=file load OpenSSL configuration from the\n" " Buffer and SlowBuffer instances\n"
" specified file (overrides\n" " -c, --check syntax check script without executing\n"
" OPENSSL_CONF)\n" " -e, --eval script evaluate script\n"
#endif /* HAVE_OPENSSL */ " -h, --help print node command line options\n"
#if defined(NODE_HAVE_I18N_SUPPORT) " -i, --interactive always enter the REPL even if stdin\n"
" --icu-data-dir=dir set ICU data load path to dir\n" " does not appear to be a terminal\n"
" (overrides NODE_ICU_DATA)\n" " -p, --print evaluate script and print result\n"
#if !defined(NODE_HAVE_SMALL_ICU) " -r, --require module to preload (option can be "
" note: linked-in ICU data is present\n" "repeated)\n"
#endif " -v, --version print Node.js version\n"
" --preserve-symlinks preserve symbolic links when resolving\n"
" --experimental-modules experimental ES Module support\n"
" and caching modules\n"
" --experimental-vm-modules experimental ES Module support\n"
" in vm module\n"
#endif
"\n" "\n"
"Environment variables:\n" "Environment variables:\n"
"NODE_DEBUG ','-separated list of core modules\n" "NODE_DEBUG ','-separated list of core modules\n"
@ -3543,12 +3556,12 @@ static void PrintHelp() {
#if !defined(NODE_HAVE_SMALL_ICU) #if !defined(NODE_HAVE_SMALL_ICU)
" (will extend linked-in data)\n" " (will extend linked-in data)\n"
#endif #endif
#endif #endif // defined(NODE_HAVE_I18N_SUPPORT)
"NODE_NO_WARNINGS set to 1 to silence process warnings\n" "NODE_NO_WARNINGS set to 1 to silence process warnings\n"
#if !defined(NODE_WITHOUT_NODE_OPTIONS) #if !defined(NODE_WITHOUT_NODE_OPTIONS)
"NODE_OPTIONS set CLI options in the environment\n" "NODE_OPTIONS set CLI options in the environment\n"
" via a space-separated list\n" " via a space-separated list\n"
#endif #endif // !defined(NODE_WITHOUT_NODE_OPTIONS)
#ifdef _WIN32 #ifdef _WIN32
"NODE_PATH ';'-separated list of directories\n" "NODE_PATH ';'-separated list of directories\n"
#else #else
@ -3557,10 +3570,14 @@ static void PrintHelp() {
" prefixed to the module search path\n" " prefixed to the module search path\n"
"NODE_PENDING_DEPRECATION set to 1 to emit pending deprecation\n" "NODE_PENDING_DEPRECATION set to 1 to emit pending deprecation\n"
" warnings\n" " warnings\n"
"NODE_REPL_HISTORY path to the persistent REPL history\n" #if defined(NODE_HAVE_I18N_SUPPORT)
" file\n" "NODE_PRESERVE_SYMLINKS set to 1 to preserve symbolic links\n"
" when resolving and caching modules\n"
#endif
"NODE_REDIRECT_WARNINGS write warnings to path instead of\n" "NODE_REDIRECT_WARNINGS write warnings to path instead of\n"
" stderr\n" " stderr\n"
"NODE_REPL_HISTORY path to the persistent REPL history\n"
" file\n"
"OPENSSL_CONF load OpenSSL configuration from file\n" "OPENSSL_CONF load OpenSSL configuration from file\n"
"\n" "\n"
"Documentation can be found at https://nodejs.org/\n"); "Documentation can be found at https://nodejs.org/\n");
@ -3597,43 +3614,44 @@ static void CheckIfAllowedInEnv(const char* exe, bool is_env,
static const char* whitelist[] = { static const char* whitelist[] = {
// Node options, sorted in `node --help` order for ease of comparison. // Node options, sorted in `node --help` order for ease of comparison.
"--require", "-r", "--enable-fips",
"--experimental-modules",
"--experimental-vm-modules",
"--expose-http2", // keep as a non-op through v9.x
"--force-fips",
"--icu-data-dir",
"--inspect", "--inspect",
"--inspect-brk", "--inspect-brk",
"--inspect-port", "--inspect-port",
"--no-deprecation",
"--trace-deprecation",
"--throw-deprecation",
"--pending-deprecation",
"--no-warnings",
"--napi-modules",
"--expose-http2", // keep as a non-op through v9.x
"--experimental-modules",
"--experimental-vm-modules",
"--loader", "--loader",
"--trace-warnings", "--napi-modules",
"--redirect-warnings", "--no-deprecation",
"--trace-sync-io",
"--no-force-async-hooks-checks", "--no-force-async-hooks-checks",
"--trace-events-enabled", "--no-warnings",
"--openssl-config",
"--pending-deprecation",
"--redirect-warnings",
"--require",
"--throw-deprecation",
"--tls-cipher-list",
"--trace-deprecation",
"--trace-event-categories", "--trace-event-categories",
"--trace-event-file-pattern", "--trace-event-file-pattern",
"--trace-events-enabled",
"--trace-sync-io",
"--trace-warnings",
"--track-heap-objects", "--track-heap-objects",
"--zero-fill-buffers",
"--v8-pool-size",
"--tls-cipher-list",
"--use-bundled-ca", "--use-bundled-ca",
"--use-openssl-ca", "--use-openssl-ca",
"--enable-fips", "--v8-pool-size",
"--force-fips", "--zero-fill-buffers",
"--openssl-config", "-r",
"--icu-data-dir",
// V8 options (define with '_', which allows '-' or '_') // V8 options (define with '_', which allows '-' or '_')
"--perf_prof",
"--perf_basic_prof",
"--abort_on_uncaught_exception", "--abort_on_uncaught_exception",
"--max_old_space_size", "--max_old_space_size",
"--perf_basic_prof",
"--perf_prof",
"--stack_trace_limit", "--stack_trace_limit",
}; };

58
test/parallel/test-cli-node-print-help.js Normal file
View File

@ -0,0 +1,58 @@
'use strict';
const common = require('../common');
// The following tests assert that the node.cc PrintHelp() function
// returns the proper set of cli options when invoked
const assert = require('assert');
const { exec } = require('child_process');
let stdOut;
function startPrintHelpTest() {
exec(`${process.execPath} --help`, common.mustCall((err, stdout, stderr) => {
assert.ifError(err);
stdOut = stdout;
validateNodePrintHelp();
}));
}
function validateNodePrintHelp() {
const config = process.config;
const HAVE_OPENSSL = common.hasCrypto;
const NODE_FIPS_MODE = common.hasFipsCrypto;
const NODE_HAVE_I18N_SUPPORT = common.hasIntl;
const HAVE_INSPECTOR = config.variables.v8_enable_inspector === 1;
const cliHelpOptions = [
{ compileConstant: HAVE_OPENSSL,
flags: [ '--openssl-config=file', '--tls-cipher-list=val',
'--use-bundled-ca', '--use-openssl-ca' ] },
{ compileConstant: NODE_FIPS_MODE,
flags: [ '--enable-fips', '--force-fips' ] },
{ compileConstant: NODE_HAVE_I18N_SUPPORT,
flags: [ '--experimental-modules', '--experimental-vm-modules',
'--icu-data-dir=dir', '--preserve-symlinks',
'NODE_ICU_DATA', 'NODE_PRESERVE_SYMLINKS' ] },
{ compileConstant: HAVE_INSPECTOR,
flags: [ '--inspect-brk[=[host:]port]', '--inspect-port=[host:]port',
'--inspect[=[host:]port]' ] },
];
cliHelpOptions.forEach(testForSubstring);
}
function testForSubstring(options) {
if (options.compileConstant) {
options.flags.forEach((flag) => {
assert.strictEqual(stdOut.indexOf(flag) !== -1, true);
});
} else {
options.flags.forEach((flag) => {
assert.strictEqual(stdOut.indexOf(flag), -1);
});
}
}
startPrintHelpTest();