Skip to content

doc: add missing CLI options to node.1 man page #60877

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Bitshifter-9 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc: add missing CLI options to node.1 man page #60877

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 134 additions & 1 deletion doc/node.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,15 @@ Allow execution of WASI when using the permission model.
.It Fl -allow-worker
Allow creating worker threads when using the permission model.
.
.It Fl -build-snapshot
Generates a snapshot blob when the process exits and writes it to disk,
which can be loaded later with
.Fl -snapshot-blob .
.
.It Fl -build-snapshot-config Ns = Ns Ar file
Specifies the path to a JSON configuration file which configures snapshot
creation behavior.
.
.It Fl -completion-bash
Print source-able bash completion script for Node.js.
.
Expand Down Expand Up @@ -148,6 +157,14 @@ is `delete`, the property will be removed entirely. If
is `throw`, accesses to the property will throw an exception with the code
`ERR_PROTO_ACCESS`.
.
.It Fl -disable-sigusr1
Disable the ability of starting a debugging session by sending a
.Sy SIGUSR1
signal to the process.
.
.It Fl -disable-warning Ns = Ns Ar code-or-type
Disable specific process warnings by code or type.
.
.It Fl -disable-wasm-trap-handler Ns = Ns Ar mode
Disable trap-handler-based WebAssembly bound checks and fall back to
inline bound checks so that WebAssembly can be run with limited virtual
Expand All @@ -158,17 +175,38 @@ Make built-in language features like `eval` and `new Function` that generate
code from strings throw an exception instead. This does not affect the Node.js
`vm` module.
.
.It Fl -dns-result-order Ns = Ns Ar order
Set the default value of order in dns.lookup(). The value could be
.Sy ipv4first ,
.Sy ipv6first ,
or
.Sy verbatim .
.
.It Fl -enable-fips
Enable FIPS-compliant crypto at startup.
Requires Node.js to be built with
.Sy ./configure --openssl-fips .
.
.It Fl -enable-network-family-autoselection
Enables the family autoselection algorithm unless connection options
explicitly disables it.
.
.It Fl -enable-source-maps
Enable Source Map V3 support for stack traces.
.
.It Fl -entry-url
Interpret the entry point as a URL.
.
.It Fl -env-file Ns = Ns Ar file
Loads environment variables from a file relative to the current directory,
making them available to applications on
.Sy process.env .
.
.It Fl -env-file-if-exists Ns = Ns Ar file
Behavior is the same as
.Fl -env-file ,
but an error is not thrown if the file does not exist.
.
.It Fl -experimental-addon-modules
Enable experimental addon module support.
.
Expand All @@ -186,6 +224,60 @@ Specify the
.Ar module
to use as a custom module loader.
.
.It Fl -experimental-network-inspection
Enable experimental support for the network inspection with Chrome DevTools.
.
.It Fl -experimental-print-required-tla
If the ES module being require()'d contains top-level await, this flag
allows Node.js to evaluate the module, try to locate the top-level awaits,
and print their location to help users find them.
.
.It Fl -experimental-require-module
Supports loading a synchronous ES module graph in require().
.
.It Fl -experimental-sea-config Ns = Ns Ar file
Use this flag to generate a blob that can be injected into the Node.js
binary to produce a single executable application.
.
.It Fl -experimental-worker-inspection
Enable experimental support for the worker inspection with Chrome DevTools.
.
.It Fl -expose-gc
This flag will expose the gc extension from V8.
.
.It Fl -force-node-api-uncaught-exceptions-policy
Enforces uncaughtException event on Node-API asynchronous callbacks.
.
.It Fl -import Ns = Ns Ar module
Preload the specified module at startup.
Follows ECMAScript module resolution rules.
.
.It Fl -network-family-autoselection-attempt-timeout Ns = Ns Ar ms
Sets the default value for the network family autoselection attempt timeout.
.
.It Fl -no-async-context-frame
Disables the use of AsyncLocalStorage backed by AsyncContextFrame.
.
.It Fl -no-experimental-detect-module
Disable using syntax detection to determine module type.
.
.It Fl -no-experimental-global-navigator
Disable exposition of Navigator API on the global scope.
.
.It Fl -no-experimental-require-module
Disable support for loading a synchronous ES module graph in require().
.
.It Fl -no-network-family-autoselection
Disables the family autoselection algorithm unless connection options
explicitly enables it.
.
.It Fl -openssl-legacy-provider
Enable OpenSSL 3.0 legacy provider.
.
.It Fl -openssl-shared-config
Enable OpenSSL default configuration section, openssl_conf to be read from
the OpenSSL configuration file.
.
.It Fl -permission
Enable the permission model.
.
Expand Down Expand Up @@ -412,7 +504,7 @@ Write
.Sy diagnostic reports
in a compact format, single-line JSON.
.
.It Fl -report-dir Fl -report-directory
.It Fl -report-dir , Fl -report-directory
Location at which the
.Sy diagnostic report
will be generated.
Expand All @@ -421,6 +513,12 @@ be written to is controlled by the
.Fl -diagnostic-dir .
command-line option.
.
.It Fl -report-exclude-env
Exclude environment variables from the diagnostic report.
.
.It Fl -report-exclude-network
Exclude network interfaces from the diagnostic report.
.
.It Fl -report-filename
Name of the file to which the
.Sy diagnostic report
Expand Down Expand Up @@ -451,13 +549,24 @@ Enables
to be generated on un-caught exceptions. Useful when inspecting JavaScript
stack in conjunction with native stack and other runtime environment data.
.
.It Fl -run
This runs a specified command from a package.json's "scripts" object.
.
.It Fl -secure-heap Ns = Ns Ar n
Specify the size of the OpenSSL secure heap. Any value less than 2 disables
the secure heap. The default is 0. The value must be a power of two.
.
.It Fl -secure-heap-min Ns = Ns Ar n
Specify the minimum allocation from the OpenSSL secure heap. The default is 2. The value must be a power of two.
.
.It Fl -snapshot-blob Ns = Ns Ar file
When used with
.Fl -build-snapshot ,
specifies the path where the generated snapshot blob is written to.
When used without
.Fl -build-snapshot ,
specifies the path to the blob that is used to restore the application state.
.
.It Fl -test
Starts the Node.js command line test runner.
.
Expand Down Expand Up @@ -561,6 +670,20 @@ favour of TLSv1.3, which is more secure.
.It Fl -trace-deprecation
Print stack traces for deprecations.
.
.It Fl -trace-env
Print information about any access to environment variables done in the
current Node.js instance to stderr.
.
.It Fl -trace-env-js-stack
In addition to what
.Fl -trace-env
does, this prints the JavaScript stack trace of the access.
.
.It Fl -trace-env-native-stack
In addition to what
.Fl -trace-env
does, this prints the native stack trace of the access.
.
.It Fl -trace-event-categories Ar categories
A comma-separated list of categories that should be traced when trace event tracing is enabled using
.Fl -trace-events-enabled .
Expand All @@ -578,6 +701,9 @@ Enable the collection of trace event tracing information.
.It Fl -trace-exit
Prints a stack trace whenever an environment is exited proactively,
i.e. invoking `process.exit()`.
.It Fl -trace-require-module
Prints information about usage of loading ECMAScript modules using require().
.
.It Fl -trace-sigint
Prints a stack trace on SIGINT.
.
Expand Down Expand Up @@ -644,6 +770,10 @@ must have one of the following values:
`off` (the default value, meaning do not map), `on` (map and ignore failure,
reporting it to stderr), or `silent` (map and silently ignore failure).
.
.It Fl -use-system-ca
Use the trusted CA certificates present in the system store, in addition to the
certificates in the bundled Mozilla CA store and certificates from NODE_EXTRA_CA_CERTS.
.
.It Fl -v8-options
Print V8 command-line options.
.
Expand All @@ -665,6 +795,9 @@ This will turn off watching of required or imported modules, even when used in c
.It Fl -watch-kill-signal
Customizes the signal sent to the process on watch mode restarts.
.
.It Fl -watch-preserve-output
Disable the clearing of the console when watch mode restarts the process.
.
.It Fl -zero-fill-buffers
Automatically zero-fills all newly allocated Buffer instances.
.
Expand Down
55 changes: 6 additions & 49 deletions test/parallel/test-cli-node-cli-manpage-options.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,46 +18,6 @@ const cliMdContentsStream = createReadStream(cliMdPath);
const manPagePath = join(rootDir, 'doc', 'node.1');
const manPageContents = readFileSync(manPagePath, { encoding: 'utf8' });

// TODO(dario-piotrowicz): add the missing flags to the node.1 and remove this set
// (refs: https://github.com/nodejs/node/issues/58895)
const knownFlagsMissingFromManPage = new Set([
'build-snapshot',
'build-snapshot-config',
'disable-sigusr1',
'disable-warning',
'dns-result-order',
'enable-network-family-autoselection',
'env-file-if-exists',
'env-file',
'experimental-network-inspection',
'experimental-print-required-tla',
'experimental-require-module',
'experimental-sea-config',
'experimental-worker-inspection',
'expose-gc',
'force-node-api-uncaught-exceptions-policy',
'import',
'network-family-autoselection-attempt-timeout',
'no-async-context-frame',
'no-experimental-detect-module',
'no-experimental-global-navigator',
'no-experimental-require-module',
'no-network-family-autoselection',
'openssl-legacy-provider',
'openssl-shared-config',
'report-dir',
'report-directory',
'report-exclude-env',
'report-exclude-network',
'run',
'snapshot-blob',
'trace-env',
'trace-env-js-stack',
'trace-env-native-stack',
'trace-require-module',
'use-system-ca',
'watch-preserve-output',
]);

const optionsEncountered = { dash: 0, dashDash: 0, named: 0 };
let insideOptionsSection = false;
Expand Down Expand Up @@ -105,19 +65,16 @@ for await (const line of rl) {
optionsEncountered.named += flagNames.length;

const manLine = `.It ${flagNames
.map((flag) => `Fl ${flag.length > 1 ? '-' : ''}${flag}`)
.join(' , ')}`;
.map((flag) => `Fl ${flag.length > 1 ? '-' : ''}${flag}`)
.join(' , ')}`;

if (
// Note: we don't check the full line (note the EOL only at the beginning) because
// options can have arguments and we do want to ignore those
!manPageContents.includes(`${EOL}${manLine}`) &&
!flagNames.every((flag) => knownFlagsMissingFromManPage.has(flag))) {
!manPageContents.includes(`${EOL}${manLine}`)) {
assert.fail(
`The following flag${
flagNames.length === 1 ? '' : 's'
} (present in \`doc/api/cli.md\`) ${flagNames.length === 1 ? 'is' : 'are'} missing in the \`doc/node.1\` file: ${
flagNames.map((flag) => `"${flag}"`).join(', ')
`The following flag${flagNames.length === 1 ? '' : 's'
} (present in \`doc/api/cli.md\`) ${flagNames.length === 1 ? 'is' : 'are'} missing in the \`doc/node.1\` file: ${flagNames.map((flag) => `"${flag}"`).join(', ')
}`
);
}
Expand All @@ -129,7 +86,7 @@ assert.strictEqual(optionsEncountered.dash, 1);
assert.strictEqual(optionsEncountered.dashDash, 1);

assert(optionsEncountered.named > 0,
'Unexpectedly not even a single cli flag/option was detected when scanning the `doc/cli.md` file'
'Unexpectedly not even a single cli flag/option was detected when scanning the `doc/cli.md` file'
);

/**
Expand Down