mirror of
https://github.com/nodejs/node.git
synced 2024-11-21 10:59:27 +00:00
doc: harmonize fenced code snippet flags
We had a few code snippets that were using a non-descriptive tag (e.g. `console` or `text`), whereas the actual language it's using describes it better, and improves the syntax highlighting. This commit also removes non-necessary leading chars (e.g. `$`, `>`, or `%`) to make it easier for readers to copy and paste to try the command themselves. PR-URL: https://github.com/nodejs/node/pull/48082 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
This commit is contained in:
parent
66fbe7fb23
commit
260092eca3
196
BUILDING.md
196
BUILDING.md
@ -261,9 +261,9 @@ fail.
|
||||
|
||||
To build Node.js:
|
||||
|
||||
```console
|
||||
$ ./configure
|
||||
$ make -j4
|
||||
```bash
|
||||
./configure
|
||||
make -j4
|
||||
```
|
||||
|
||||
We can speed up the builds by using [Ninja](https://ninja-build.org/). For more
|
||||
@ -284,8 +284,8 @@ Running the following script on macOS will add the firewall rules for the
|
||||
executable `node` in the `out` directory and the symbolic `node` link in the
|
||||
project's root directory.
|
||||
|
||||
```console
|
||||
$ sudo ./tools/macos-firewall.sh
|
||||
```bash
|
||||
sudo ./tools/macos-firewall.sh
|
||||
```
|
||||
|
||||
#### Installing Node.js
|
||||
@ -300,16 +300,16 @@ To install this version of Node.js into a system directory:
|
||||
|
||||
To verify the build:
|
||||
|
||||
```console
|
||||
$ make test-only
|
||||
```bash
|
||||
make test-only
|
||||
```
|
||||
|
||||
At this point, you are ready to make code changes and re-run the tests.
|
||||
|
||||
If you are running tests before submitting a pull request, use:
|
||||
|
||||
```console
|
||||
$ make -j4 test
|
||||
```bash
|
||||
make -j4 test
|
||||
```
|
||||
|
||||
`make -j4 test` does a full check on the codebase, including running linters and
|
||||
@ -321,29 +321,29 @@ To run the linter without running tests, use
|
||||
If you are updating tests and want to run tests in a single test file
|
||||
(e.g. `test/parallel/test-stream2-transform.js`):
|
||||
|
||||
```text
|
||||
$ tools/test.py test/parallel/test-stream2-transform.js
|
||||
```bash
|
||||
tools/test.py test/parallel/test-stream2-transform.js
|
||||
```
|
||||
|
||||
You can execute the entire suite of tests for a given subsystem
|
||||
by providing the name of a subsystem:
|
||||
|
||||
```text
|
||||
$ tools/test.py child-process
|
||||
```bash
|
||||
tools/test.py child-process
|
||||
```
|
||||
|
||||
You can also execute the tests in a test suite directory
|
||||
(such as `test/message`):
|
||||
|
||||
```text
|
||||
$ tools/test.py test/message
|
||||
```bash
|
||||
tools/test.py test/message
|
||||
```
|
||||
|
||||
If you want to check the other options, please refer to the help by using
|
||||
the `--help` option:
|
||||
|
||||
```text
|
||||
$ tools/test.py --help
|
||||
```bash
|
||||
tools/test.py --help
|
||||
```
|
||||
|
||||
> Note: On Windows you should use `python3` executable.
|
||||
@ -351,8 +351,8 @@ $ tools/test.py --help
|
||||
|
||||
You can usually run tests directly with node:
|
||||
|
||||
```text
|
||||
$ ./node test/parallel/test-stream2-transform.js
|
||||
```bash
|
||||
./node test/parallel/test-stream2-transform.js
|
||||
```
|
||||
|
||||
> Info: `./node` points to your local Node.js build.
|
||||
@ -379,9 +379,9 @@ to run/debug tests if your IDE configs are present.
|
||||
It's good practice to ensure any code you add or change is covered by tests.
|
||||
You can do so by running the test suite with coverage enabled:
|
||||
|
||||
```console
|
||||
$ ./configure --coverage
|
||||
$ make coverage
|
||||
```bash
|
||||
./configure --coverage
|
||||
make coverage
|
||||
```
|
||||
|
||||
A detailed coverage report will be written to `coverage/index.html` for
|
||||
@ -391,33 +391,33 @@ If you only want to run the JavaScript tests then you do not need to run
|
||||
the first command (`./configure --coverage`). Run `make coverage-run-js`,
|
||||
to execute JavaScript tests independently of the C++ test suite:
|
||||
|
||||
```text
|
||||
$ make coverage-run-js
|
||||
```bash
|
||||
make coverage-run-js
|
||||
```
|
||||
|
||||
If you are updating tests and want to collect coverage for a single test file
|
||||
(e.g. `test/parallel/test-stream2-transform.js`):
|
||||
|
||||
```text
|
||||
$ make coverage-clean
|
||||
$ NODE_V8_COVERAGE=coverage/tmp tools/test.py test/parallel/test-stream2-transform.js
|
||||
$ make coverage-report-js
|
||||
```bash
|
||||
make coverage-clean
|
||||
NODE_V8_COVERAGE=coverage/tmp tools/test.py test/parallel/test-stream2-transform.js
|
||||
make coverage-report-js
|
||||
```
|
||||
|
||||
You can collect coverage for the entire suite of tests for a given subsystem
|
||||
by providing the name of a subsystem:
|
||||
|
||||
```text
|
||||
$ make coverage-clean
|
||||
$ NODE_V8_COVERAGE=coverage/tmp tools/test.py --mode=release child-process
|
||||
$ make coverage-report-js
|
||||
```bash
|
||||
make coverage-clean
|
||||
NODE_V8_COVERAGE=coverage/tmp tools/test.py --mode=release child-process
|
||||
make coverage-report-js
|
||||
```
|
||||
|
||||
The `make coverage` command downloads some tools to the project root directory.
|
||||
To clean up after generating the coverage reports:
|
||||
|
||||
```console
|
||||
$ make coverage-clean
|
||||
```bash
|
||||
make coverage-clean
|
||||
```
|
||||
|
||||
#### Building the documentation
|
||||
@ -473,9 +473,9 @@ If you run into an issue where the information provided by the JS stack trace
|
||||
is not enough, or if you suspect the error happens outside of the JS VM, you
|
||||
can try to build a debug enabled binary:
|
||||
|
||||
```console
|
||||
$ ./configure --debug
|
||||
$ make -j4
|
||||
```bash
|
||||
./configure --debug
|
||||
make -j4
|
||||
```
|
||||
|
||||
`make` with `./configure --debug` generates two binaries, the regular release
|
||||
@ -485,9 +485,9 @@ release version is actually installed when you run `make install`.
|
||||
To use the debug build with all the normal dependencies overwrite the release
|
||||
version in the install directory:
|
||||
|
||||
```console
|
||||
$ make install PREFIX=/opt/node-debug/
|
||||
$ cp -a -f out/Debug/node /opt/node-debug/node
|
||||
```bash
|
||||
make install PREFIX=/opt/node-debug/
|
||||
cp -a -f out/Debug/node /opt/node-debug/node
|
||||
```
|
||||
|
||||
When using the debug binary, core dumps will be generated in case of crashes.
|
||||
@ -501,9 +501,9 @@ was captured on (i.e. 64-bit `gdb` for `node` built on a 64-bit system, Linux
|
||||
|
||||
Example of generating a backtrace from the core dump:
|
||||
|
||||
```console
|
||||
```bash
|
||||
$ gdb /opt/node-debug/node core.node.8.1535359906
|
||||
$ backtrace
|
||||
(gdb) backtrace
|
||||
```
|
||||
|
||||
#### Building an ASan build
|
||||
@ -517,9 +517,9 @@ on Linux, you can try [Docker](https://www.docker.com/products/docker-desktop)
|
||||
The `--debug` is not necessary and will slow down build and testing, but it can
|
||||
show clear stacktrace if ASan hits an issue.
|
||||
|
||||
```console
|
||||
$ ./configure --debug --enable-asan && make -j4
|
||||
$ make test-only
|
||||
```bash
|
||||
./configure --debug --enable-asan && make -j4
|
||||
make test-only
|
||||
```
|
||||
|
||||
#### Speeding up frequent rebuilds when developing
|
||||
@ -548,8 +548,8 @@ This will allow for near-instantaneous rebuilds even when switching branches.
|
||||
When modifying only the JS layer in `lib`, it is possible to externally load it
|
||||
without modifying the executable:
|
||||
|
||||
```console
|
||||
$ ./configure --node-builtin-modules-path "$(pwd)"
|
||||
```bash
|
||||
./configure --node-builtin-modules-path "$(pwd)"
|
||||
```
|
||||
|
||||
The resulting binary won't include any JS files and will try to load them from
|
||||
@ -638,20 +638,20 @@ disk space.
|
||||
If the path to your build directory contains a space or a non-ASCII character,
|
||||
the build will likely fail.
|
||||
|
||||
```console
|
||||
> .\vcbuild
|
||||
```powershell
|
||||
.\vcbuild
|
||||
```
|
||||
|
||||
To run the tests:
|
||||
|
||||
```console
|
||||
> .\vcbuild test
|
||||
```powershell
|
||||
.\vcbuild test
|
||||
```
|
||||
|
||||
To test if Node.js was built correctly:
|
||||
|
||||
```console
|
||||
> Release\node -e "console.log('Hello from Node.js', process.version)"
|
||||
```powershell
|
||||
Release\node -e "console.log('Hello from Node.js', process.version)"
|
||||
```
|
||||
|
||||
### Android
|
||||
@ -665,9 +665,9 @@ Be sure you have downloaded and extracted
|
||||
[Android NDK](https://developer.android.com/ndk) before in
|
||||
a folder. Then run:
|
||||
|
||||
```console
|
||||
$ ./android-configure <path to the Android NDK> <Android SDK version> <target architecture>
|
||||
$ make -j4
|
||||
```bash
|
||||
./android-configure <path to the Android NDK> <Android SDK version> <target architecture>
|
||||
make -j4
|
||||
```
|
||||
|
||||
The Android SDK version should be at least 24 (Android 7.0) and the target
|
||||
@ -684,14 +684,14 @@ This is the default option.
|
||||
|
||||
#### Unix/macOS
|
||||
|
||||
```console
|
||||
$ ./configure --with-intl=full-icu
|
||||
```bash
|
||||
./configure --with-intl=full-icu
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
```console
|
||||
> .\vcbuild full-icu
|
||||
```powershell
|
||||
.\vcbuild full-icu
|
||||
```
|
||||
|
||||
### Trimmed: `small-icu` (English only) support
|
||||
@ -702,14 +702,14 @@ any dependencies to function. You can add full data at runtime.
|
||||
|
||||
#### Unix/macOS
|
||||
|
||||
```console
|
||||
$ ./configure --with-intl=small-icu
|
||||
```bash
|
||||
./configure --with-intl=small-icu
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
```console
|
||||
> .\vcbuild small-icu
|
||||
```powershell
|
||||
.\vcbuild small-icu
|
||||
```
|
||||
|
||||
### Building without Intl support
|
||||
@ -719,20 +719,20 @@ The `Intl` object will not be available, nor some other APIs such as
|
||||
|
||||
#### Unix/macOS
|
||||
|
||||
```console
|
||||
$ ./configure --without-intl
|
||||
```bash
|
||||
./configure --without-intl
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
```console
|
||||
> .\vcbuild without-intl
|
||||
```powershell
|
||||
.\vcbuild without-intl
|
||||
```
|
||||
|
||||
### Use existing installed ICU (Unix/macOS only)
|
||||
|
||||
```console
|
||||
$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
|
||||
```bash
|
||||
pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
|
||||
```
|
||||
|
||||
If you are cross-compiling, your `pkg-config` must be able to supply a path
|
||||
@ -753,20 +753,20 @@ during configuration if the ICU version is too old.
|
||||
|
||||
From an already-unpacked ICU:
|
||||
|
||||
```console
|
||||
$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu
|
||||
```bash
|
||||
./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu
|
||||
```
|
||||
|
||||
From a local ICU tarball:
|
||||
|
||||
```console
|
||||
$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
|
||||
```bash
|
||||
./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
|
||||
```
|
||||
|
||||
From a tarball URL:
|
||||
|
||||
```console
|
||||
$ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
|
||||
```bash
|
||||
./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
|
||||
```
|
||||
|
||||
#### Windows
|
||||
@ -775,8 +775,8 @@ First unpack latest ICU to `deps/icu`
|
||||
[icu4c-**##.#**-src.tgz](http://site.icu-project.org/download) (or `.zip`)
|
||||
as `deps/icu` (You'll have: `deps/icu/source/...`)
|
||||
|
||||
```console
|
||||
> .\vcbuild full-icu
|
||||
```powershell
|
||||
.\vcbuild full-icu
|
||||
```
|
||||
|
||||
### Configure OpenSSL appname
|
||||
@ -788,8 +788,8 @@ configuration file `openssl.cnf`. Node.js will only read a section that is by
|
||||
default named `nodejs_conf`, but this name can be overridden using the following
|
||||
configure option:
|
||||
|
||||
```console
|
||||
$ ./configure --openssl-conf-name=<some_conf_name>
|
||||
```bash
|
||||
./configure --openssl-conf-name=<some_conf_name>
|
||||
```
|
||||
|
||||
## Building Node.js with FIPS-compliant OpenSSL
|
||||
@ -802,9 +802,9 @@ dynamically linking with OpenSSL 3.0.0 by using the configuration flag
|
||||
|
||||
FIPS can be supported by specifying the configuration flag `--openssl-is-fips`:
|
||||
|
||||
```console
|
||||
$ ./configure --openssl-is-fips
|
||||
$ make -j8
|
||||
```bash
|
||||
./configure --openssl-is-fips
|
||||
make -j8
|
||||
```
|
||||
|
||||
The above command will build and install the FIPS module into the out directory.
|
||||
@ -872,7 +872,7 @@ will publish the OpenSSL libraries and such. We will also use this path
|
||||
|
||||
**compile and install OpenSSL**
|
||||
|
||||
```console
|
||||
```bash
|
||||
make -j8
|
||||
make install
|
||||
make install_ssldirs
|
||||
@ -909,7 +909,7 @@ using relative paths did not work on my system!
|
||||
|
||||
**alter openssl.cnf using a script**
|
||||
|
||||
```console
|
||||
```bash
|
||||
cat <<EOT >> /path/to/install/dir/ssl/openssl.cnf
|
||||
.include /path/to/install/dir/ssl/fipsmodule.cnf
|
||||
|
||||
@ -929,14 +929,14 @@ As you might have picked a non-custom path for your OpenSSL install dir, we
|
||||
have to export the following two environment variables in order for Node.js to
|
||||
find our OpenSSL modules we built beforehand:
|
||||
|
||||
```console
|
||||
```bash
|
||||
export OPENSSL_CONF=/path/to/install/dir/ssl/openssl.cnf
|
||||
export OPENSSL_MODULES=/path/to/install/dir/lib/ossl-modules
|
||||
```
|
||||
|
||||
**build Node.js**
|
||||
|
||||
```console
|
||||
```bash
|
||||
./configure \
|
||||
--shared-openssl \
|
||||
--shared-openssl-libpath=/path/to/install/dir/lib \
|
||||
@ -952,7 +952,7 @@ make -j8
|
||||
**verify the produced executable**
|
||||
|
||||
```console
|
||||
ldd ./node
|
||||
$ ldd ./node
|
||||
linux-vdso.so.1 (0x00007ffd7917b000)
|
||||
libcrypto.so.81.3 => /path/to/install/dir/lib/libcrypto.so.81.3 (0x00007fd911321000)
|
||||
libssl.so.81.3 => /path/to/install/dir/lib/libssl.so.81.3 (0x00007fd91125e000)
|
||||
@ -972,17 +972,17 @@ If the `ldd` command says that `libcrypto` cannot be found one needs to set
|
||||
**verify the OpenSSL version**
|
||||
|
||||
```console
|
||||
./node -p process.versions.openssl
|
||||
$ ./node -p process.versions.openssl
|
||||
3.0.0-alpha16+quic
|
||||
```
|
||||
|
||||
**verify that FIPS is available**
|
||||
|
||||
```console
|
||||
./node -p 'process.config.variables.openssl_is_fips'
|
||||
$ ./node -p 'process.config.variables.openssl_is_fips'
|
||||
true
|
||||
|
||||
./node --enable-fips -p 'crypto.getFips()'
|
||||
$ ./node --enable-fips -p 'crypto.getFips()'
|
||||
1
|
||||
```
|
||||
|
||||
@ -997,8 +997,8 @@ executable. See sections
|
||||
This is done using one of the Node.js options `--enable-fips` or
|
||||
`--force-fips`, for example:
|
||||
|
||||
```console
|
||||
$ node --enable-fips -p 'crypto.getFips()'
|
||||
```bash
|
||||
node --enable-fips -p 'crypto.getFips()'
|
||||
```
|
||||
|
||||
### Enabling FIPS using OpenSSL config
|
||||
@ -1012,7 +1012,7 @@ for details.
|
||||
For this to work the OpenSSL configuration file (default openssl.cnf) needs to
|
||||
be updated. The following shows an example:
|
||||
|
||||
```console
|
||||
```text
|
||||
openssl_conf = openssl_init
|
||||
|
||||
.include /path/to/install/dir/ssl/fipsmodule.cnf
|
||||
@ -1046,8 +1046,8 @@ This command will make `/root/myModule.js` available via
|
||||
`require('/root/myModule')` and `./myModule2.js` available via
|
||||
`require('myModule2')`.
|
||||
|
||||
```console
|
||||
$ ./configure --link-module '/root/myModule.js' --link-module './myModule2.js'
|
||||
```bash
|
||||
./configure --link-module '/root/myModule.js' --link-module './myModule2.js'
|
||||
```
|
||||
|
||||
### Windows
|
||||
@ -1055,8 +1055,8 @@ $ ./configure --link-module '/root/myModule.js' --link-module './myModule2.js'
|
||||
To make `./myModule.js` available via `require('myModule')` and
|
||||
`./myModule2.js` available via `require('myModule2')`:
|
||||
|
||||
```console
|
||||
> .\vcbuild link-module './myModule.js' link-module './myModule2.js'
|
||||
```powershell
|
||||
.\vcbuild link-module './myModule.js' link-module './myModule2.js'
|
||||
```
|
||||
|
||||
## Building to use shared dependencies at runtime
|
||||
|
16
README.md
16
README.md
@ -98,15 +98,15 @@ files.
|
||||
|
||||
To download `SHASUMS256.txt` using `curl`:
|
||||
|
||||
```console
|
||||
$ curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt
|
||||
```bash
|
||||
curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt
|
||||
```
|
||||
|
||||
To check that a downloaded file matches the checksum, run
|
||||
it through `sha256sum` with a command such as:
|
||||
|
||||
```console
|
||||
$ grep node-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c -
|
||||
```bash
|
||||
grep node-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c -
|
||||
```
|
||||
|
||||
For Current and LTS, the GPG detached signature of `SHASUMS256.txt` is in
|
||||
@ -115,16 +115,16 @@ For Current and LTS, the GPG detached signature of `SHASUMS256.txt` is in
|
||||
[the GPG keys of individuals authorized to create releases](#release-keys). To
|
||||
import the keys:
|
||||
|
||||
```console
|
||||
$ gpg --keyserver hkps://keys.openpgp.org --recv-keys 4ED778F539E3634C779C87C6D7062848A1AB005C
|
||||
```bash
|
||||
gpg --keyserver hkps://keys.openpgp.org --recv-keys 4ED778F539E3634C779C87C6D7062848A1AB005C
|
||||
```
|
||||
|
||||
See [Release keys](#release-keys) for a script to import active release keys.
|
||||
|
||||
Next, download the `SHASUMS256.txt.sig` for the release:
|
||||
|
||||
```console
|
||||
$ curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt.sig
|
||||
```bash
|
||||
curl -O https://nodejs.org/dist/vx.y.z/SHASUMS256.txt.sig
|
||||
```
|
||||
|
||||
Then use `gpg --verify SHASUMS256.txt.sig SHASUMS256.txt` to verify
|
||||
|
@ -532,8 +532,8 @@ filename to the `sources` array:
|
||||
Once the `binding.gyp` file is ready, the example addons can be configured and
|
||||
built using `node-gyp`:
|
||||
|
||||
```console
|
||||
$ node-gyp configure build
|
||||
```bash
|
||||
node-gyp configure build
|
||||
```
|
||||
|
||||
### Function arguments
|
||||
|
@ -184,8 +184,8 @@ Error: Access to this API has been restricted
|
||||
|
||||
The process needs to have access to the `index.js` module:
|
||||
|
||||
```console
|
||||
$ node --experimental-permission --allow-fs-read=/path/to/index.js index.js
|
||||
```bash
|
||||
node --experimental-permission --allow-fs-read=/path/to/index.js index.js
|
||||
```
|
||||
|
||||
### `--allow-fs-write`
|
||||
@ -314,9 +314,9 @@ added: v10.12.0
|
||||
|
||||
Print source-able bash completion script for Node.js.
|
||||
|
||||
```console
|
||||
$ node --completion-bash > node_bash_completion
|
||||
$ source node_bash_completion
|
||||
```bash
|
||||
node --completion-bash > node_bash_completion
|
||||
source node_bash_completion
|
||||
```
|
||||
|
||||
### `-C condition`, `--conditions=condition`
|
||||
@ -339,8 +339,8 @@ The default Node.js conditions of `"node"`, `"default"`, `"import"`, and
|
||||
|
||||
For example, to run a module with "development" resolutions:
|
||||
|
||||
```console
|
||||
$ node -C development app.js
|
||||
```bash
|
||||
node -C development app.js
|
||||
```
|
||||
|
||||
### `--cpu-prof`
|
||||
@ -1854,8 +1854,8 @@ Use `--watch-path` to specify what paths to watch.
|
||||
This flag cannot be combined with
|
||||
`--check`, `--eval`, `--interactive`, or the REPL.
|
||||
|
||||
```console
|
||||
$ node --watch index.js
|
||||
```bash
|
||||
node --watch index.js
|
||||
```
|
||||
|
||||
### `--watch-path`
|
||||
@ -1877,8 +1877,8 @@ combination with `--watch`.
|
||||
This flag cannot be combined with
|
||||
`--check`, `--eval`, `--interactive`, `--test`, or the REPL.
|
||||
|
||||
```console
|
||||
$ node --watch-path=./src --watch-path=./tests index.js
|
||||
```bash
|
||||
node --watch-path=./src --watch-path=./tests index.js
|
||||
```
|
||||
|
||||
This option is only supported on macOS and Windows.
|
||||
@ -1889,8 +1889,8 @@ when the option is used on a platform that does not support it.
|
||||
|
||||
Disable the clearing of the console when watch mode restarts the process.
|
||||
|
||||
```console
|
||||
$ node --watch --watch-preserve-output test.js
|
||||
```bash
|
||||
node --watch --watch-preserve-output test.js
|
||||
```
|
||||
|
||||
### `--zero-fill-buffers`
|
||||
@ -2525,8 +2525,8 @@ garbage collection in an effort to free unused memory.
|
||||
On a machine with 2 GiB of memory, consider setting this to
|
||||
1536 (1.5 GiB) to leave some memory for other uses and avoid swapping.
|
||||
|
||||
```console
|
||||
$ node --max-old-space-size=1536 index.js
|
||||
```bash
|
||||
node --max-old-space-size=1536 index.js
|
||||
```
|
||||
|
||||
### `--max-semi-space-size=SIZE` (in megabytes)
|
||||
|
@ -711,7 +711,7 @@ all `import` calls. They won't apply to `require` calls; those still follow
|
||||
|
||||
Loaders follow the pattern of `--require`:
|
||||
|
||||
```console
|
||||
```bash
|
||||
node \
|
||||
--experimental-loader unpkg \
|
||||
--experimental-loader http-to-https \
|
||||
|
@ -1616,8 +1616,8 @@ server.listen(8124, () => {
|
||||
|
||||
Test this by using `telnet`:
|
||||
|
||||
```console
|
||||
$ telnet localhost 8124
|
||||
```bash
|
||||
telnet localhost 8124
|
||||
```
|
||||
|
||||
To listen on the socket `/tmp/echo.sock`:
|
||||
@ -1630,8 +1630,8 @@ server.listen('/tmp/echo.sock', () => {
|
||||
|
||||
Use `nc` to connect to a Unix domain socket server:
|
||||
|
||||
```console
|
||||
$ nc -U /tmp/echo.sock
|
||||
```bash
|
||||
nc -U /tmp/echo.sock
|
||||
```
|
||||
|
||||
## `net.getDefaultAutoSelectFamily()`
|
||||
|
@ -922,8 +922,8 @@ argv.forEach((val, index) => {
|
||||
|
||||
Launching the Node.js process as:
|
||||
|
||||
```console
|
||||
$ node process-args.js one two=three four
|
||||
```bash
|
||||
node process-args.js one two=three four
|
||||
```
|
||||
|
||||
Would generate the output:
|
||||
@ -1577,8 +1577,8 @@ reflected outside the Node.js process, or (unless explicitly requested)
|
||||
to other [`Worker`][] threads.
|
||||
In other words, the following example would not work:
|
||||
|
||||
```console
|
||||
$ node -e 'process.env.foo = "bar"' && echo $foo
|
||||
```bash
|
||||
node -e 'process.env.foo = "bar"' && echo $foo
|
||||
```
|
||||
|
||||
While the following will:
|
||||
@ -1683,8 +1683,8 @@ include the Node.js executable, the name of the script, or any options following
|
||||
the script name. These options are useful in order to spawn child processes with
|
||||
the same execution environment as the parent.
|
||||
|
||||
```console
|
||||
$ node --harmony script.js --version
|
||||
```bash
|
||||
node --harmony script.js --version
|
||||
```
|
||||
|
||||
Results in `process.execArgv`:
|
||||
|
@ -712,7 +712,7 @@ terminal settings, which will allow use with `rlwrap`.
|
||||
|
||||
For example, the following can be added to a `.bashrc` file:
|
||||
|
||||
```text
|
||||
```bash
|
||||
alias node="env NODE_NO_READLINE=1 rlwrap node"
|
||||
```
|
||||
|
||||
|
@ -26,42 +26,42 @@ Here are the steps for creating a single executable application using one such
|
||||
tool, [postject][]:
|
||||
|
||||
1. Create a JavaScript file:
|
||||
```console
|
||||
$ echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js
|
||||
```bash
|
||||
echo 'console.log(`Hello, ${process.argv[2]}!`);' > hello.js
|
||||
```
|
||||
|
||||
2. Create a configuration file building a blob that can be injected into the
|
||||
single executable application (see
|
||||
[Generating single executable preparation blobs][] for details):
|
||||
```console
|
||||
$ echo '{ "main": "hello.js", "output": "sea-prep.blob" }' > sea-config.json
|
||||
```bash
|
||||
echo '{ "main": "hello.js", "output": "sea-prep.blob" }' > sea-config.json
|
||||
```
|
||||
|
||||
3. Generate the blob to be injected:
|
||||
```console
|
||||
$ node --experimental-sea-config sea-config.json
|
||||
```bash
|
||||
node --experimental-sea-config sea-config.json
|
||||
```
|
||||
|
||||
4. Create a copy of the `node` executable and name it according to your needs:
|
||||
|
||||
* On systems other than Windows:
|
||||
|
||||
```console
|
||||
$ cp $(command -v node) hello
|
||||
```bash
|
||||
cp $(command -v node) hello
|
||||
```
|
||||
|
||||
* On Windows:
|
||||
|
||||
Using PowerShell:
|
||||
|
||||
```console
|
||||
$ cp (Get-Command node).Source hello.exe
|
||||
```bash
|
||||
cp (Get-Command node).Source hello.exe
|
||||
```
|
||||
|
||||
Using Command Prompt:
|
||||
|
||||
```console
|
||||
$ for /F "tokens=*" %n IN ('where.exe node') DO @(copy "%n" hello.exe)
|
||||
```bash
|
||||
for /F "tokens=*" %n IN ('where.exe node') DO @(copy "%n" hello.exe)
|
||||
```
|
||||
|
||||
The `.exe` extension is necessary.
|
||||
@ -70,8 +70,8 @@ tool, [postject][]:
|
||||
|
||||
* On macOS:
|
||||
|
||||
```console
|
||||
$ codesign --remove-signature hello
|
||||
```bash
|
||||
codesign --remove-signature hello
|
||||
```
|
||||
|
||||
* On Windows (optional):
|
||||
@ -79,8 +79,8 @@ tool, [postject][]:
|
||||
[signtool][] can be used from the installed [Windows SDK][]. If this step is
|
||||
skipped, ignore any signature-related warning from postject.
|
||||
|
||||
```console
|
||||
$ signtool remove /s hello.exe
|
||||
```bash
|
||||
signtool remove /s hello.exe
|
||||
```
|
||||
|
||||
6. Inject the blob into the copied binary by running `postject` with
|
||||
@ -100,20 +100,20 @@ tool, [postject][]:
|
||||
To summarize, here is the required command for each platform:
|
||||
|
||||
* On Linux:
|
||||
```console
|
||||
$ npx postject hello NODE_SEA_BLOB sea-prep.blob \
|
||||
```bash
|
||||
npx postject hello NODE_SEA_BLOB sea-prep.blob \
|
||||
--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
|
||||
```
|
||||
|
||||
* On Windows:
|
||||
```console
|
||||
$ npx postject hello.exe NODE_SEA_BLOB sea-prep.blob \
|
||||
```bash
|
||||
npx postject hello.exe NODE_SEA_BLOB sea-prep.blob \
|
||||
--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
|
||||
```
|
||||
|
||||
* On macOS:
|
||||
```console
|
||||
$ npx postject hello NODE_SEA_BLOB sea-prep.blob \
|
||||
```bash
|
||||
npx postject hello NODE_SEA_BLOB sea-prep.blob \
|
||||
--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 \
|
||||
--macho-segment-name NODE_SEA
|
||||
```
|
||||
@ -122,8 +122,8 @@ tool, [postject][]:
|
||||
|
||||
* On macOS:
|
||||
|
||||
```console
|
||||
$ codesign --sign - hello
|
||||
```bash
|
||||
codesign --sign - hello
|
||||
```
|
||||
|
||||
* On Windows (optional):
|
||||
@ -131,8 +131,8 @@ tool, [postject][]:
|
||||
A certificate needs to be present for this to work. However, the unsigned
|
||||
binary would still be runnable.
|
||||
|
||||
```console
|
||||
$ signtool sign /fd SHA256 hello.exe
|
||||
```bash
|
||||
signtool sign /fd SHA256 hello.exe
|
||||
```
|
||||
|
||||
8. Run the binary:
|
||||
|
@ -29,23 +29,23 @@ Now, create an empty project folder called `projects`, then navigate into it.
|
||||
|
||||
Linux and Mac:
|
||||
|
||||
```console
|
||||
$ mkdir ~/projects
|
||||
$ cd ~/projects
|
||||
```bash
|
||||
mkdir ~/projects
|
||||
cd ~/projects
|
||||
```
|
||||
|
||||
Windows CMD:
|
||||
|
||||
```console
|
||||
> mkdir %USERPROFILE%\projects
|
||||
> cd %USERPROFILE%\projects
|
||||
```powershell
|
||||
mkdir %USERPROFILE%\projects
|
||||
cd %USERPROFILE%\projects
|
||||
```
|
||||
|
||||
Windows PowerShell:
|
||||
|
||||
```console
|
||||
> mkdir $env:USERPROFILE\projects
|
||||
> cd $env:USERPROFILE\projects
|
||||
```powershell
|
||||
mkdir $env:USERPROFILE\projects
|
||||
cd $env:USERPROFILE\projects
|
||||
```
|
||||
|
||||
Next, create a new source file in the `projects`
|
||||
@ -73,8 +73,8 @@ server.listen(port, hostname, () => {
|
||||
|
||||
Save the file, go back to the terminal window, and enter the following command:
|
||||
|
||||
```console
|
||||
$ node hello-world.js
|
||||
```bash
|
||||
node hello-world.js
|
||||
```
|
||||
|
||||
Output like this should appear in the terminal:
|
||||
|
@ -285,8 +285,8 @@ failures, it is easy to not notice unnecessarily poor TLS performance. The
|
||||
OpenSSL CLI can be used to verify that servers are resuming sessions. Use the
|
||||
`-reconnect` option to `openssl s_client`, for example:
|
||||
|
||||
```console
|
||||
$ openssl s_client -connect localhost:443 -reconnect
|
||||
```bash
|
||||
openssl s_client -connect localhost:443 -reconnect
|
||||
```
|
||||
|
||||
Read through the debug output. The first connection should say "New", for
|
||||
|
@ -93,8 +93,8 @@ To run the above example, create a new WebAssembly text format file named
|
||||
|
||||
Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm`
|
||||
|
||||
```console
|
||||
$ wat2wasm demo.wat
|
||||
```bash
|
||||
wat2wasm demo.wat
|
||||
```
|
||||
|
||||
## Class: `WASI`
|
||||
|
@ -555,9 +555,9 @@ this tool, please file an issue [to the issue tracker][node-core-utils-issues].
|
||||
|
||||
Quick example:
|
||||
|
||||
```text
|
||||
$ npm install -g node-core-utils
|
||||
$ git node land $PRID
|
||||
```bash
|
||||
npm install -g node-core-utils
|
||||
git node land $PRID
|
||||
```
|
||||
|
||||
To use `node-core-utils`, you will need a GitHub access token. If you do not
|
||||
@ -576,37 +576,37 @@ pull request rather than rely on `git-node`.
|
||||
|
||||
Clear any `am`/`rebase` that might already be underway:
|
||||
|
||||
```text
|
||||
$ git am --abort
|
||||
$ git rebase --abort
|
||||
```bash
|
||||
git am --abort
|
||||
git rebase --abort
|
||||
```
|
||||
|
||||
Checkout proper target branch:
|
||||
|
||||
```text
|
||||
$ git checkout main
|
||||
```bash
|
||||
git checkout main
|
||||
```
|
||||
|
||||
Update the tree (assumes your repository is set up as detailed in
|
||||
[CONTRIBUTING.md](./pull-requests.md#step-1-fork)):
|
||||
|
||||
```text
|
||||
$ git fetch upstream
|
||||
$ git merge --ff-only upstream/main
|
||||
```bash
|
||||
git fetch upstream
|
||||
git merge --ff-only upstream/main
|
||||
```
|
||||
|
||||
Apply external patches:
|
||||
|
||||
```text
|
||||
$ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix
|
||||
```bash
|
||||
curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix
|
||||
```
|
||||
|
||||
If the merge fails even though recent CI runs were successful, try a 3-way
|
||||
merge:
|
||||
|
||||
```text
|
||||
$ git am --abort
|
||||
$ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix
|
||||
```bash
|
||||
git am --abort
|
||||
curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix
|
||||
```
|
||||
|
||||
If the 3-way merge succeeds, check the results against the original pull
|
||||
@ -617,20 +617,20 @@ has landed since the CI run. You will have to ask the author to rebase.
|
||||
|
||||
Check and re-review the changes:
|
||||
|
||||
```text
|
||||
$ git diff upstream/main
|
||||
```bash
|
||||
git diff upstream/main
|
||||
```
|
||||
|
||||
Check the number of commits and commit messages:
|
||||
|
||||
```text
|
||||
$ git log upstream/main...main
|
||||
```bash
|
||||
git log upstream/main...main
|
||||
```
|
||||
|
||||
Squash commits and add metadata:
|
||||
|
||||
```text
|
||||
$ git rebase -i upstream/main
|
||||
```bash
|
||||
git rebase -i upstream/main
|
||||
```
|
||||
|
||||
This will open a screen like this (in the default shell editor):
|
||||
@ -706,8 +706,8 @@ precaution, run tests (`make -j4 test` or `vcbuild test`).
|
||||
Confirm that the commit message format is correct using
|
||||
[core-validate-commit](https://github.com/nodejs/core-validate-commit).
|
||||
|
||||
```text
|
||||
$ git rev-list upstream/main...HEAD | xargs core-validate-commit
|
||||
```bash
|
||||
git rev-list upstream/main...HEAD | xargs core-validate-commit
|
||||
```
|
||||
|
||||
Optional: For your own commits, force push the amended commit to the pull
|
||||
@ -722,8 +722,8 @@ the issue with the red closed status.
|
||||
|
||||
Time to push it:
|
||||
|
||||
```text
|
||||
$ git push upstream main
|
||||
```bash
|
||||
git push upstream main
|
||||
```
|
||||
|
||||
Close the pull request with a "Landed in `<commit hash>`" comment. Even if
|
||||
|
@ -29,7 +29,7 @@ To use Valgrind:
|
||||
It is an optional package in most cases and must be installed explicitly.
|
||||
For example on Debian/Ubuntu:
|
||||
|
||||
```console
|
||||
```bash
|
||||
apt-get install valgrind
|
||||
```
|
||||
|
||||
@ -37,7 +37,7 @@ apt-get install valgrind
|
||||
|
||||
The simplest invocation of Valgrind is:
|
||||
|
||||
```console
|
||||
```bash
|
||||
valgrind node test.js
|
||||
```
|
||||
|
||||
@ -433,7 +433,7 @@ follow cover the steps needed to enable debug symbols to get more info.
|
||||
To enable debug symbols for all of your addons that are compiled on
|
||||
install use:
|
||||
|
||||
```console
|
||||
```bash
|
||||
npm install --debug
|
||||
```
|
||||
|
||||
@ -443,7 +443,7 @@ results in the addons being compiled with the debug option.
|
||||
If the native addon contains pre-built binaries you will need to force
|
||||
a rebuild.
|
||||
|
||||
```console
|
||||
```bash
|
||||
npm install --debug
|
||||
npm rebuild
|
||||
```
|
||||
@ -517,7 +517,7 @@ To get additional information with Valgrind:
|
||||
* Check out the Node.js source corresponding to the release that you
|
||||
want to debug. For example:
|
||||
|
||||
```console
|
||||
```bash
|
||||
git clone https://github.com/nodejs/node.git
|
||||
git checkout v12.14.1
|
||||
```
|
||||
@ -526,7 +526,7 @@ git checkout v12.14.1
|
||||
[building a debug build](https://github.com/nodejs/node/blob/v12.14.1/BUILDING.md#building-a-debug-build)).
|
||||
For example, on \*nix:
|
||||
|
||||
```console
|
||||
```bash
|
||||
./configure --debug
|
||||
make -j4
|
||||
```
|
||||
|
@ -187,7 +187,7 @@ Here are the steps for the bug mentioned above:
|
||||
|
||||
* Download and apply the commit linked-to in the issue (in this case a51f429):
|
||||
|
||||
```console
|
||||
```bash
|
||||
curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 --directory=deps/v8
|
||||
```
|
||||
|
||||
|
@ -61,15 +61,15 @@ release).
|
||||
|
||||
### OpenSSL 3.x.x
|
||||
|
||||
```console
|
||||
% git clone https://github.com/quictls/openssl
|
||||
% cd openssl
|
||||
% cd ../node/deps/openssl
|
||||
% rm -rf openssl
|
||||
% cp -R ../../../openssl openssl
|
||||
% rm -rf openssl/.git* openssl/.travis*
|
||||
% git add --all openssl
|
||||
% git commit openssl
|
||||
```bash
|
||||
git clone https://github.com/quictls/openssl
|
||||
cd openssl
|
||||
cd ../node/deps/openssl
|
||||
rm -rf openssl
|
||||
cp -R ../../../openssl openssl
|
||||
rm -rf openssl/.git* openssl/.travis*
|
||||
git add --all openssl
|
||||
git commit openssl
|
||||
```
|
||||
|
||||
```text
|
||||
@ -92,19 +92,19 @@ This updates all sources in deps/openssl/openssl by:
|
||||
Use `make` to regenerate all platform dependent files in
|
||||
`deps/openssl/config/archs/`:
|
||||
|
||||
```console
|
||||
```bash
|
||||
# On non-Linux machines
|
||||
% make gen-openssl
|
||||
make gen-openssl
|
||||
|
||||
# On Linux machines
|
||||
% make -C deps/openssl/config clean
|
||||
% make -C deps/openssl/config
|
||||
make -C deps/openssl/config clean
|
||||
make -C deps/openssl/config
|
||||
```
|
||||
|
||||
**Note**: If the 32-bit Windows is failing to compile run this workflow instead:
|
||||
|
||||
```console
|
||||
% make -C deps/openssl/config clean
|
||||
```bash
|
||||
make -C deps/openssl/config clean
|
||||
# Edit deps/openssl/openssl/crypto/perlasm/x86asm.pl changing
|
||||
# #ifdef to %ifdef to make it compatible to nasm on 32-bit Windows.
|
||||
# See: https://github.com/nodejs/node/pull/43603#issuecomment-1170670844
|
||||
@ -117,8 +117,8 @@ Check diffs to ensure updates are right. Even if there are no updates in openssl
|
||||
sources, `buildinf.h` files will be updated because they have timestamp
|
||||
data in them.
|
||||
|
||||
```console
|
||||
% git diff -- deps/openssl
|
||||
```bash
|
||||
git diff -- deps/openssl
|
||||
```
|
||||
|
||||
_Note_: On Windows, OpenSSL Configure generates a `makefile` that can be
|
||||
@ -133,10 +133,10 @@ please ask @shigeki for details.
|
||||
Update all architecture dependent files. Do not forget to git add or remove
|
||||
files if they are changed before committing:
|
||||
|
||||
```console
|
||||
% git add deps/openssl/config/archs
|
||||
% git add deps/openssl/openssl
|
||||
% git commit
|
||||
```bash
|
||||
git add deps/openssl/config/archs
|
||||
git add deps/openssl/openssl
|
||||
git commit
|
||||
```
|
||||
|
||||
The commit message can be written as (with the openssl version set
|
||||
|
@ -70,7 +70,7 @@ it's time to create a fork.
|
||||
Fork the project [on GitHub](https://github.com/nodejs/node) and clone your fork
|
||||
locally.
|
||||
|
||||
```text
|
||||
```bash
|
||||
git clone git@github.com:username/node.git
|
||||
cd node
|
||||
git remote add upstream https://github.com/nodejs/node.git
|
||||
@ -79,7 +79,7 @@ git fetch upstream
|
||||
|
||||
Configure `git` so that it knows who you are:
|
||||
|
||||
```text
|
||||
```bash
|
||||
git config user.name "J. Random User"
|
||||
git config user.email "j.random.user@example.com"
|
||||
```
|
||||
@ -99,7 +99,7 @@ As a best practice to keep your development environment as organized as
|
||||
possible, create local branches to work within. These should also be created
|
||||
directly off of the upstream default branch.
|
||||
|
||||
```text
|
||||
```bash
|
||||
git checkout -b my-branch -t upstream/HEAD
|
||||
```
|
||||
|
||||
@ -147,7 +147,7 @@ as possible within individual commits. There is no limit to the number of
|
||||
commits any single pull request may have, and many contributors find it easier
|
||||
to review changes that are split across multiple commits.
|
||||
|
||||
```text
|
||||
```bash
|
||||
git add my/changed/files
|
||||
git commit
|
||||
```
|
||||
@ -217,7 +217,7 @@ As a best practice, once you have committed your changes, it is a good idea
|
||||
to use `git rebase` (not `git merge`) to synchronize your work with the main
|
||||
repository.
|
||||
|
||||
```text
|
||||
```bash
|
||||
git fetch upstream HEAD
|
||||
git rebase FETCH_HEAD
|
||||
```
|
||||
@ -239,7 +239,7 @@ later.
|
||||
Before submitting your changes in a pull request, always run the full Node.js
|
||||
test suite. To run the tests (including code linting) on Unix / macOS:
|
||||
|
||||
```text
|
||||
```bash
|
||||
./configure && make -j4 test
|
||||
```
|
||||
|
||||
@ -249,8 +249,8 @@ information, see
|
||||
|
||||
And on Windows:
|
||||
|
||||
```text
|
||||
> vcbuild test
|
||||
```powershell
|
||||
vcbuild test
|
||||
```
|
||||
|
||||
For some configurations, running all tests might take a long time (an hour or
|
||||
@ -263,7 +263,7 @@ Once you are sure your commits are ready to go, with passing tests and linting,
|
||||
begin the process of opening a pull request by pushing your working branch to
|
||||
your fork on GitHub.
|
||||
|
||||
```text
|
||||
```bash
|
||||
git push origin my-branch
|
||||
```
|
||||
|
||||
@ -292,7 +292,7 @@ To make changes to an existing pull request, make the changes to your local
|
||||
branch, add a new commit with those changes, and push those to your fork.
|
||||
GitHub will automatically update the pull request.
|
||||
|
||||
```text
|
||||
```bash
|
||||
git add my/changed/files
|
||||
git commit
|
||||
git push origin my-branch
|
||||
@ -301,7 +301,7 @@ git push origin my-branch
|
||||
If a git conflict arises, it is necessary to synchronize your branch with other
|
||||
changes that have landed upstream by using `git rebase`:
|
||||
|
||||
```text
|
||||
```bash
|
||||
git fetch upstream HEAD
|
||||
git rebase FETCH_HEAD
|
||||
git push --force-with-lease origin my-branch
|
||||
|
@ -38,10 +38,10 @@ Node-API Working Group can be contacted best by opening up an issue on the
|
||||
|
||||
Checkout the staging branch locally.
|
||||
|
||||
```console
|
||||
$ git remote update
|
||||
$ git checkout main
|
||||
$ git reset --hard upstream/main
|
||||
```bash
|
||||
git remote update
|
||||
git checkout main
|
||||
git reset --hard upstream/main
|
||||
```
|
||||
|
||||
If the staging branch is not up to date relative to `main`, bring the
|
||||
@ -51,8 +51,8 @@ appropriate PRs and commits into it.
|
||||
|
||||
Create a new branch named `node-api-x-proposal`, off the main branch.
|
||||
|
||||
```console
|
||||
$ git checkout -b node-api-10-proposal upstream/main
|
||||
```bash
|
||||
git checkout -b node-api-10-proposal upstream/main
|
||||
```
|
||||
|
||||
### 3. Update `NAPI_VERSION`
|
||||
@ -83,7 +83,7 @@ version, the relevant commits should already include the `NAPI_EXPERIMENTAL`
|
||||
define guards on the declaration of the new Node-API. Check for these guards
|
||||
with:
|
||||
|
||||
```console
|
||||
```bash
|
||||
grep NAPI_EXPERIMENTAL src/js_native_api{_types,}.h src/node_api{_types,}.h
|
||||
```
|
||||
|
||||
@ -115,7 +115,7 @@ If this release includes runtime behavior version guards, the relevant commits
|
||||
should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check
|
||||
for these guards with:
|
||||
|
||||
```console
|
||||
```bash
|
||||
grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
|
||||
```
|
||||
|
||||
@ -127,7 +127,7 @@ If this release includes add-on tests for the new Node-APIs, the relevant
|
||||
commits should already include `NAPI_EXPERIMENTAL` definition for the tests.
|
||||
Check for these definitions with:
|
||||
|
||||
```console
|
||||
```bash
|
||||
grep NAPI_EXPERIMENTAL test/node-api/*/{*.{h,c},binding.gyp} test/js-native-api/*/{*.{h,c},binding.gyp}
|
||||
```
|
||||
|
||||
@ -170,7 +170,7 @@ should already have documented the new behavior in a "Change History" section.
|
||||
For all runtime version guards updated in Step 2, check for these definitions
|
||||
with:
|
||||
|
||||
```console
|
||||
```bash
|
||||
grep NAPI_EXPERIMENTAL doc/api/n-api.md
|
||||
```
|
||||
|
||||
|
@ -96,14 +96,14 @@ Keyservers at <https://sks-keyservers.net> are recommended. Use the
|
||||
[submission](https://pgp.mit.edu/) form to submit a new GPG key. You'll need to
|
||||
do an ASCII-armored export of your key first:
|
||||
|
||||
```console
|
||||
$ gpg --armor --export email@server.com > ~/nodekey.asc
|
||||
```bash
|
||||
gpg --armor --export email@server.com > ~/nodekey.asc
|
||||
```
|
||||
|
||||
Keys should be fetchable via:
|
||||
|
||||
```console
|
||||
$ gpg --keyserver pool.sks-keyservers.net --recv-keys <FINGERPRINT>
|
||||
```bash
|
||||
gpg --keyserver pool.sks-keyservers.net --recv-keys <FINGERPRINT>
|
||||
```
|
||||
|
||||
The key you use may be a child/subkey of an existing key.
|
||||
@ -144,10 +144,10 @@ access the private repository.
|
||||
|
||||
Checkout the staging branch locally.
|
||||
|
||||
```console
|
||||
$ git remote update
|
||||
$ git checkout v1.x-staging
|
||||
$ git reset --hard upstream/v1.x-staging
|
||||
```bash
|
||||
git remote update
|
||||
git checkout v1.x-staging
|
||||
git reset --hard upstream/v1.x-staging
|
||||
```
|
||||
|
||||
If the staging branch is not up to date relative to `main`, bring the
|
||||
@ -170,8 +170,8 @@ backport PR with `Landed in ...`. Update the label on the original PR from
|
||||
You can add the `Backport-PR-URL` metadata by using `--backport` with
|
||||
`git node land`
|
||||
|
||||
```console
|
||||
$ git node land --backport $PR-NUMBER
|
||||
```bash
|
||||
git node land --backport $PR-NUMBER
|
||||
```
|
||||
|
||||
To determine the relevant commits, use
|
||||
@ -184,8 +184,8 @@ duplicate or not.
|
||||
|
||||
For a list of commits that could be landed in a patch release on v1.x:
|
||||
|
||||
```console
|
||||
$ branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=simple
|
||||
```bash
|
||||
branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=simple
|
||||
```
|
||||
|
||||
Previously released commits and version bumps do not need to be
|
||||
@ -204,8 +204,8 @@ When you are ready to cherry-pick commits, you can automate with the following
|
||||
command. (For semver-minor releases, make sure to remove the `semver-minor` tag
|
||||
from `exclude-label`.)
|
||||
|
||||
```console
|
||||
$ branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=sha --reverse | xargs git cherry-pick
|
||||
```bash
|
||||
branch-diff v1.x-staging main --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-requested-v1.x,backport-blocked-v1.x,backport-open-v1.x,backported-to-v1.x --filter-release --format=sha --reverse | xargs git cherry-pick
|
||||
```
|
||||
|
||||
When cherry-picking commits, if there are simple conflicts you can resolve
|
||||
@ -216,14 +216,14 @@ Lines](https://github.com/nodejs/node/blob/HEAD/doc/contributing/backporting-to-
|
||||
|
||||
If commits were cherry-picked in this step, check that the test still pass.
|
||||
|
||||
```console
|
||||
$ make test
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
Then, push to the staging branch to keep it up-to-date.
|
||||
|
||||
```console
|
||||
$ git push upstream v1.x-staging
|
||||
```bash
|
||||
git push upstream v1.x-staging
|
||||
```
|
||||
|
||||
<details>
|
||||
@ -234,8 +234,8 @@ GitHub organization.
|
||||
|
||||
Add the `nodejs-private` remote:
|
||||
|
||||
```console
|
||||
$ git remote add private git@github.com:nodejs-private/node-private.git
|
||||
```bash
|
||||
git remote add private git@github.com:nodejs-private/node-private.git
|
||||
```
|
||||
|
||||
For security releases, we generally try to only include the security patches.
|
||||
@ -267,8 +267,8 @@ You can integrate the PRs into the proposal without running full CI.
|
||||
Create a new branch named `vx.y.z-proposal`, off the corresponding staging
|
||||
branch.
|
||||
|
||||
```console
|
||||
$ git checkout -b v1.2.3-proposal upstream/v1.x-staging
|
||||
```bash
|
||||
git checkout -b v1.2.3-proposal upstream/v1.x-staging
|
||||
```
|
||||
|
||||
<details>
|
||||
@ -309,16 +309,16 @@ be produced with a version string that does not have a trailing pre-release tag:
|
||||
Collect a formatted list of commits since the last release. Use
|
||||
[`changelog-maker`](https://github.com/nodejs/changelog-maker) to do this:
|
||||
|
||||
```console
|
||||
$ changelog-maker --group --markdown
|
||||
```bash
|
||||
changelog-maker --group --markdown
|
||||
```
|
||||
|
||||
`changelog-maker` counts commits since the last tag and if the last tag
|
||||
in the repository was not on the current branch you may have to supply a
|
||||
`--start-ref` argument:
|
||||
|
||||
```console
|
||||
$ changelog-maker --group --markdown --filter-release --start-ref v1.2.2
|
||||
```bash
|
||||
changelog-maker --group --markdown --filter-release --start-ref v1.2.2
|
||||
```
|
||||
|
||||
`--filter-release` will remove the release commit from the previous release.
|
||||
@ -361,8 +361,8 @@ notable. The ultimate decision rests with the releaser.
|
||||
You can use `branch-diff` to get a list of commits with the `notable-change`
|
||||
label:
|
||||
|
||||
```console
|
||||
$ branch-diff upstream/v1.x v1.2.3-proposal --require-label=notable-change --plaintext
|
||||
```bash
|
||||
branch-diff upstream/v1.x v1.2.3-proposal --require-label=notable-change --plaintext
|
||||
```
|
||||
|
||||
Be sure that the `<a>` tag, as well as the two headings, are not indented at
|
||||
@ -422,13 +422,13 @@ were first added in this version. The relevant commits should already include
|
||||
`REPLACEME` tags as per the example in the
|
||||
[docs README](../../tools/doc/README.md). Check for these tags with
|
||||
|
||||
```console
|
||||
```bash
|
||||
grep REPLACEME doc/api/*.md
|
||||
```
|
||||
|
||||
and substitute this node version with
|
||||
|
||||
```console
|
||||
```bash
|
||||
sed -i "s/REPLACEME/$VERSION/g" doc/api/*.md
|
||||
```
|
||||
|
||||
@ -440,7 +440,7 @@ sed -i "" "s/REPLACEME/$VERSION/g" doc/api/*.md
|
||||
|
||||
or
|
||||
|
||||
```console
|
||||
```bash
|
||||
perl -pi -e "s/REPLACEME/$VERSION/g" doc/api/*.md
|
||||
```
|
||||
|
||||
@ -549,9 +549,9 @@ ecosystem.
|
||||
|
||||
Use `ncu-ci` to compare `vx.x` run (10) and proposal branch (11)
|
||||
|
||||
```console
|
||||
$ npm i -g node-core-utils
|
||||
$ ncu-ci citgm 10 11
|
||||
```bash
|
||||
npm i -g node-core-utils
|
||||
ncu-ci citgm 10 11
|
||||
```
|
||||
|
||||
<details>
|
||||
@ -584,22 +584,22 @@ consider using the following approach:
|
||||
|
||||
1. Update staging
|
||||
|
||||
```console
|
||||
$ git checkout v1.x-staging
|
||||
$ git rebase -i $HASH_PREVIOUS_BAD_COMMIT
|
||||
... drop or edit the bad commit(s)
|
||||
$ git push -f upstream v1.x-staging
|
||||
```bash
|
||||
git checkout v1.x-staging
|
||||
git rebase -i $HASH_PREVIOUS_BAD_COMMIT
|
||||
# ... drop or edit the bad commit(s)
|
||||
git push -f upstream v1.x-staging
|
||||
```
|
||||
|
||||
2. Rebase the proposal against the updated staging branch
|
||||
|
||||
```console
|
||||
$ git checkout v1.2.3-proposal
|
||||
$ git checkout -b v1.2.3-proposal-tmp
|
||||
$ git checkout v1.2.3-proposal
|
||||
```bash
|
||||
git checkout v1.2.3-proposal
|
||||
git checkout -b v1.2.3-proposal-tmp
|
||||
git checkout v1.2.3-proposal
|
||||
|
||||
$ git reset --hard upstream/v1.x-staging
|
||||
$ git cherry-pick v1.2.3-proposal-tmp
|
||||
git reset --hard upstream/v1.x-staging
|
||||
git cherry-pick v1.2.3-proposal-tmp
|
||||
```
|
||||
|
||||
Note the `tmp` branch was created just to save the release commit.
|
||||
@ -669,7 +669,7 @@ the build before moving forward. Use the following list as a baseline:
|
||||
* Run `make build-addons` before running the tests
|
||||
* Remove `config.gypi` file
|
||||
|
||||
```console
|
||||
```bash
|
||||
./tools/test.py --shell ~/Downloads/node-v18.5.0-linux-x64/bin/node
|
||||
```
|
||||
|
||||
@ -684,7 +684,7 @@ count that tag/version as lost.
|
||||
|
||||
Tag summaries have a predictable format. Look at a recent tag to see:
|
||||
|
||||
```console
|
||||
```bash
|
||||
git tag -v v6.0.0
|
||||
```
|
||||
|
||||
@ -693,14 +693,14 @@ The message should look something like
|
||||
|
||||
Install `git-secure-tag` npm module:
|
||||
|
||||
```console
|
||||
$ npm install -g git-secure-tag
|
||||
```bash
|
||||
npm install -g git-secure-tag
|
||||
```
|
||||
|
||||
Create a tag using the following command:
|
||||
|
||||
```console
|
||||
$ git secure-tag <vx.y.z> <commit-sha> -sm "YYYY-MM-DD Node.js vx.y.z (<release-type>) Release"
|
||||
```bash
|
||||
git secure-tag <vx.y.z> <commit-sha> -sm "YYYY-MM-DD Node.js vx.y.z (<release-type>) Release"
|
||||
```
|
||||
|
||||
<sup>The commit-sha is the release commit. You can get it easily by running `git rev-parse HEAD`</sup>
|
||||
@ -738,13 +738,13 @@ version number _and_ a pre-release tag.
|
||||
Merge your release proposal branch into the stable branch that you are releasing
|
||||
from and rebase the corresponding staging branch on top of that.
|
||||
|
||||
```console
|
||||
$ git checkout v1.x
|
||||
$ git merge --ff-only v1.2.3-proposal
|
||||
$ git push upstream v1.x
|
||||
$ git checkout v1.x-staging
|
||||
$ git rebase v1.x
|
||||
$ git push upstream v1.x-staging
|
||||
```bash
|
||||
git checkout v1.x
|
||||
git merge --ff-only v1.2.3-proposal
|
||||
git push upstream v1.x
|
||||
git checkout v1.x-staging
|
||||
git rebase v1.x
|
||||
git push upstream v1.x-staging
|
||||
```
|
||||
|
||||
<details>
|
||||
@ -753,13 +753,13 @@ $ git push upstream v1.x-staging
|
||||
For security releases, you can start merging the release in the `nodejs-private`
|
||||
GitHub organization in advance by following the same steps:
|
||||
|
||||
```console
|
||||
$ git checkout v1.x
|
||||
$ git merge --ff-only v1.2.3-proposal
|
||||
$ git push private v1.x
|
||||
$ git checkout v1.x-staging
|
||||
$ git rebase v1.x
|
||||
$ git push private v1.x-staging
|
||||
```bash
|
||||
git checkout v1.x
|
||||
git merge --ff-only v1.2.3-proposal
|
||||
git push private v1.x
|
||||
git checkout v1.x-staging
|
||||
git rebase v1.x
|
||||
git push private v1.x-staging
|
||||
```
|
||||
|
||||
Once all releasers are ready, you can push each of the branches to the public
|
||||
@ -769,18 +769,18 @@ repository.
|
||||
|
||||
### 13. Cherry-pick the release commit to `main`
|
||||
|
||||
```console
|
||||
$ git checkout main
|
||||
$ git pull upstream main
|
||||
$ git cherry-pick --strategy-option=diff-algorithm=patience v1.x^
|
||||
```bash
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
git cherry-pick --strategy-option=diff-algorithm=patience v1.x^
|
||||
```
|
||||
|
||||
Git should stop to let you fix conflicts.
|
||||
|
||||
Revert all changes that were made to `src/node_version.h`:
|
||||
|
||||
```console
|
||||
$ git checkout --ours HEAD -- src/node_version.h
|
||||
```bash
|
||||
git checkout --ours HEAD -- src/node_version.h
|
||||
```
|
||||
|
||||
<details>
|
||||
@ -795,8 +795,8 @@ edit it instead and:
|
||||
|
||||
Amend the current commit to apply the changes:
|
||||
|
||||
```console
|
||||
$ git commit --amend
|
||||
```bash
|
||||
git commit --amend
|
||||
```
|
||||
|
||||
</details>
|
||||
@ -816,12 +816,12 @@ the cherry-pick step.
|
||||
|
||||
Then finish cherry-picking and push the commit upstream:
|
||||
|
||||
```console
|
||||
$ git add src/node_version.h doc
|
||||
$ git diff --staged src doc # read output to validate that changes shows up as expected
|
||||
$ git cherry-pick --continue
|
||||
$ make lint-md && make lint-cpp
|
||||
$ git push upstream main
|
||||
```bash
|
||||
git add src/node_version.h doc
|
||||
git diff --staged src doc # read output to validate that changes shows up as expected
|
||||
git cherry-pick --continue
|
||||
make lint-md && make lint-cpp
|
||||
git push upstream main
|
||||
```
|
||||
|
||||
**Do not** cherry-pick the "Working on vx.y.z" commit to `main`.
|
||||
@ -837,12 +837,12 @@ metadata.
|
||||
It is useful to first push the patches to `private/main` to check that the
|
||||
GitHub actions runs pass, before pushing to `upstream/main`:
|
||||
|
||||
```console
|
||||
$ git checkout main
|
||||
$ git reset --hard upstream/main
|
||||
$ git cherry-pick ... # apply the patches which apply to main
|
||||
$ git push private main # push to private main first run GitHub actions
|
||||
$ git push upstream main
|
||||
```bash
|
||||
git checkout main
|
||||
git reset --hard upstream/main
|
||||
git cherry-pick ... # apply the patches which apply to main
|
||||
git push private main # push to private main first run GitHub actions
|
||||
git push upstream main
|
||||
```
|
||||
|
||||
</details>
|
||||
@ -853,8 +853,8 @@ Push the tag to the repository before you promote the builds. If you
|
||||
haven't pushed your tag first, then build promotion won't work properly.
|
||||
Push the tag using the following command:
|
||||
|
||||
```console
|
||||
$ git push upstream v1.2.3
|
||||
```bash
|
||||
git push upstream v1.2.3
|
||||
```
|
||||
|
||||
_Note_: Please do not push the tag unless you are ready to complete the
|
||||
@ -877,24 +877,24 @@ dist@direct.nodejs.org's password:
|
||||
|
||||
The key can be loaded either with `ssh-add`:
|
||||
|
||||
```console
|
||||
```bash
|
||||
# Substitute node_id_rsa with whatever you've named the key
|
||||
$ ssh-add ~/.ssh/node_id_rsa
|
||||
ssh-add ~/.ssh/node_id_rsa
|
||||
```
|
||||
|
||||
or at runtime with:
|
||||
|
||||
```console
|
||||
```bash
|
||||
# Substitute node_id_rsa with whatever you've named the key
|
||||
$ ./tools/release.sh -i ~/.ssh/node_id_rsa
|
||||
./tools/release.sh -i ~/.ssh/node_id_rsa
|
||||
```
|
||||
|
||||
You can also specify a different ssh server address to connect to by defining
|
||||
a `NODEJS_RELEASE_HOST` environment variable:
|
||||
|
||||
```console
|
||||
```bash
|
||||
# Substitute proxy.xyz with whatever address you intend to use
|
||||
$ NODEJS_RELEASE_HOST=proxy.xyz ./tools/release.sh
|
||||
NODEJS_RELEASE_HOST=proxy.xyz ./tools/release.sh
|
||||
```
|
||||
|
||||
`tools/release.sh` will perform the following actions when run:
|
||||
@ -956,8 +956,8 @@ release. However, the blog post is not yet fully automatic.
|
||||
|
||||
Create a new blog post by running the [nodejs.org release-post.js script][]:
|
||||
|
||||
```console
|
||||
$ node ./scripts/release-post/index.mjs x.y.z
|
||||
```bash
|
||||
node ./scripts/release-post/index.mjs x.y.z
|
||||
```
|
||||
|
||||
This script will use the promoted builds and changelog to generate the post. Run
|
||||
@ -1038,20 +1038,20 @@ The process of marking a release line as LTS has been automated using
|
||||
Start by checking out the staging branch for the release line that is going to
|
||||
be marked as LTS, e.g:
|
||||
|
||||
```console
|
||||
$ git checkout v1.x-staging
|
||||
```bash
|
||||
git checkout v1.x-staging
|
||||
```
|
||||
|
||||
Next, make sure you have **node-core-utils** installed:
|
||||
|
||||
```console
|
||||
$ npm i -g node-core-utils
|
||||
```bash
|
||||
npm i -g node-core-utils
|
||||
```
|
||||
|
||||
Run the prepare LTS release command:
|
||||
|
||||
```console
|
||||
$ git node release --prepare --startLTS
|
||||
```bash
|
||||
git node release --prepare --startLTS
|
||||
```
|
||||
|
||||
<details>
|
||||
|
@ -159,8 +159,8 @@ assert/deepequal-object.js method="notDeepEqual" strict=0 size=100 n=5000: 9,734
|
||||
|
||||
It is possible to execute more groups by adding extra process arguments.
|
||||
|
||||
```console
|
||||
$ node benchmark/run.js assert async_hooks
|
||||
```bash
|
||||
node benchmark/run.js assert async_hooks
|
||||
```
|
||||
|
||||
#### Filtering benchmarks
|
||||
@ -263,20 +263,20 @@ First build two versions of Node.js, one from the `main` branch (here called
|
||||
To run multiple compiled versions in parallel you need to copy the output of the
|
||||
build: `cp ./out/Release/node ./node-main`. Check out the following example:
|
||||
|
||||
```console
|
||||
$ git checkout main
|
||||
$ ./configure && make -j4
|
||||
$ cp ./out/Release/node ./node-main
|
||||
```bash
|
||||
git checkout main
|
||||
./configure && make -j4
|
||||
cp ./out/Release/node ./node-main
|
||||
|
||||
$ git checkout pr-5134
|
||||
$ ./configure && make -j4
|
||||
$ cp ./out/Release/node ./node-pr-5134
|
||||
git checkout pr-5134
|
||||
./configure && make -j4
|
||||
cp ./out/Release/node ./node-pr-5134
|
||||
```
|
||||
|
||||
The `compare.js` tool will then produce a csv file with the benchmark results.
|
||||
|
||||
```console
|
||||
$ node benchmark/compare.js --old ./node-main --new ./node-pr-5134 string_decoder > compare-pr-5134.csv
|
||||
```bash
|
||||
node benchmark/compare.js --old ./node-main --new ./node-pr-5134 string_decoder > compare-pr-5134.csv
|
||||
```
|
||||
|
||||
_Tips: there are some useful options of `benchmark/compare.js`. For example,
|
||||
@ -358,8 +358,8 @@ To do this use the `scatter.js` tool, this will run a benchmark multiple times
|
||||
and generate a csv with the results. To see how to use this script,
|
||||
run `node benchmark/scatter.js`.
|
||||
|
||||
```console
|
||||
$ node benchmark/scatter.js benchmark/string_decoder/string-decoder.js > scatter.csv
|
||||
```bash
|
||||
node benchmark/scatter.js benchmark/string_decoder/string-decoder.js > scatter.csv
|
||||
```
|
||||
|
||||
After generating the csv, a comparison table can be created using the
|
||||
|
@ -287,7 +287,7 @@ const freelist = require('node:internal/freelist');
|
||||
In specific scenarios it may be useful to get a hold of `primordials` or
|
||||
`internalBinding()`. You can do so using
|
||||
|
||||
```console
|
||||
```bash
|
||||
node --expose-internals -r internal/test/binding lib/fs.js
|
||||
```
|
||||
|
||||
@ -439,20 +439,20 @@ adding them to the `libraries` section in the cctest target.
|
||||
|
||||
The test can be executed by running the `cctest` target:
|
||||
|
||||
```console
|
||||
$ make cctest
|
||||
```bash
|
||||
make cctest
|
||||
```
|
||||
|
||||
A filter can be applied to run single/multiple test cases:
|
||||
|
||||
```console
|
||||
$ make cctest GTEST_FILTER=EnvironmentTest.AtExitWithArgument
|
||||
```bash
|
||||
make cctest GTEST_FILTER=EnvironmentTest.AtExitWithArgument
|
||||
```
|
||||
|
||||
`cctest` can also be run directly which can be useful when debugging:
|
||||
|
||||
```console
|
||||
$ out/Release/cctest --gtest_filter=EnvironmentTest.AtExit\*
|
||||
```bash
|
||||
out/Release/cctest --gtest_filter=EnvironmentTest.AtExit\*
|
||||
```
|
||||
|
||||
### Node.js test fixture
|
||||
|
@ -4,6 +4,6 @@ Compile with clang and `wasm32-wasi` target. The clang version used must be
|
||||
built with wasi-libc. You can specify the location for clang and the sysroot
|
||||
if needed when running make:
|
||||
|
||||
```console
|
||||
$ make CC=/usr/local/opt/llvm/bin/clang SYSROOT=/path/to/wasi-libc/sysroot
|
||||
```bash
|
||||
make CC=/usr/local/opt/llvm/bin/clang SYSROOT=/path/to/wasi-libc/sysroot
|
||||
```
|
||||
|
@ -34,9 +34,9 @@ See [Format of a status JSON file](#status-format) for details.
|
||||
Use the [git node wpt][] command to download the WPT files into
|
||||
`test/fixtures/wpt`. For example, to add URL tests:
|
||||
|
||||
```text
|
||||
$ cd /path/to/node/project
|
||||
$ git node wpt url
|
||||
```bash
|
||||
cd /path/to/node/project
|
||||
git node wpt url
|
||||
```
|
||||
|
||||
### 3. Create the test driver
|
||||
@ -71,14 +71,14 @@ with the WPT harness while taking the status file into account.
|
||||
Run the test using `tools/test.py` and see if there are any failures.
|
||||
For example, to run all the URL tests under `test/fixtures/wpt/url`:
|
||||
|
||||
```text
|
||||
$ tools/test.py wpt/test-url
|
||||
```bash
|
||||
tools/test.py wpt/test-url
|
||||
```
|
||||
|
||||
To run a specific test in WPT, for example, `url/url-searchparams.any.js`,
|
||||
pass the file name as argument to the corresponding test driver:
|
||||
|
||||
```text
|
||||
```bash
|
||||
node test/wpt/test-url.js url-searchparams.any.js
|
||||
```
|
||||
|
||||
@ -149,7 +149,7 @@ expected failures.
|
||||
|
||||
## Format of a status JSON file
|
||||
|
||||
```text
|
||||
```json
|
||||
{
|
||||
"something.scope.js": { // the file name
|
||||
// Optional: If the requirement is not met, this test will be skipped
|
||||
|
Loading…
Reference in New Issue
Block a user