mirror of
https://github.com/nodejs/node.git
synced 2024-11-21 10:59:27 +00:00
doc: create maintaining folder for deps
PR-URL: https://github.com/nodejs/node/pull/47589 Refs: https://github.com/nodejs/security-wg/issues/828 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com>
This commit is contained in:
Marco Ippolito
GitHub
parent
ab434d2327
commit
109ab0a89c
3
.github/CODEOWNERS
vendored
3
.github/CODEOWNERS
vendored
@ -146,8 +146,7 @@
|
||||
# Single Executable Applications
|
||||
/deps/postject @nodejs/single-executable
|
||||
/doc/api/single-executable-applications.md @nodejs/single-executable
|
||||
/doc/contributing/maintaining-postject.md @nodejs/single-executable
|
||||
/doc/contributing/maintaining-single-executable-application-support.md @nodejs/single-executable
|
||||
/doc/contributing/maintaining/maintaining-single-executable-application-support.md @nodejs/single-executable
|
||||
/src/node_sea* @nodejs/single-executable
|
||||
/test/fixtures/postject-copy @nodejs/single-executable
|
||||
/test/parallel/test-single-executable-* @nodejs/single-executable
|
||||
|
||||
@ -1,47 +0,0 @@
|
||||
# Maintaining acorn
|
||||
|
||||
The [acorn](https://github.com/acornjs/acorn) dependency is a JavaScript parser.
|
||||
[acorn-walk](https://github.com/acornjs/acorn/tree/master/acorn-walk) is
|
||||
an abstract syntax tree walker for the ESTree format.
|
||||
|
||||
## Updating acorn
|
||||
|
||||
The `tools/dep_updaters/update-acorn.sh` script automates the update of the
|
||||
acorn source files.
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
## Committing acorn
|
||||
|
||||
1. Add acorn:
|
||||
```console
|
||||
$ git add deps/acorn
|
||||
```
|
||||
2. Commit the changes: `git commit`.
|
||||
3. Add a message like:
|
||||
```text
|
||||
deps: update acorn to <version>
|
||||
|
||||
Updated as described in doc/contributing/maintaining-acorn.md.
|
||||
```
|
||||
|
||||
## Updating acorn-walk
|
||||
|
||||
The `tools/dep_updaters/update-acorn-walk.sh` script automates the update of the
|
||||
acorn-walk source files.
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
## Committing acorn-walk
|
||||
|
||||
1. Add acorn-walk:
|
||||
```console
|
||||
$ git add deps/acorn-walk
|
||||
```
|
||||
2. Commit the changes: `git commit`.
|
||||
3. Add a message like:
|
||||
```text
|
||||
deps: update acorn-walk to <version>
|
||||
|
||||
Updated as described in doc/contributing/maintaining-acorn.md.
|
||||
```
|
||||
@ -1,25 +0,0 @@
|
||||
# Maintaining brotli
|
||||
|
||||
The [brotli](https://github.com/google/brotli) dependency is used for
|
||||
the homonym generic-purpose lossless compression algorithm.
|
||||
|
||||
## Updating brotli
|
||||
|
||||
The `tools/dep_updaters/update-brotli.sh` script automates the update of the
|
||||
brotli source files.
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
## Committing brotli
|
||||
|
||||
1. Add brotli:
|
||||
```console
|
||||
$ git add deps/brotli
|
||||
```
|
||||
2. Commit the changes: `git commit`.
|
||||
3. Add a message like:
|
||||
```text
|
||||
deps: update brotli to <version>
|
||||
|
||||
Updated as described in doc/contributing/maintaining-brotli.md.
|
||||
```
|
||||
@ -1,58 +0,0 @@
|
||||
# Maintaining c-ares
|
||||
|
||||
Updates to the c-ares dependency involve the following steps:
|
||||
|
||||
1. Downloading the source archive for the new version.
|
||||
2. Unpacking the source in a temporary workspace directory.
|
||||
3. Removing the `test` directory (to save disk space).
|
||||
4. Copying over the existing `.gitignore`, pre-generated `config` directory and
|
||||
`cares.gyp` files.
|
||||
5. Replacing the existing `deps/cares` with the workspace directory.
|
||||
6. Modifying the `cares.gyp` file for file additions/deletions.
|
||||
7. Rebuilding the main Node.js `LICENSE`.
|
||||
|
||||
## Running the update script
|
||||
|
||||
The `tools/dep_updaters/update-c-ares.sh` script automates the update of
|
||||
the c-ares source files, preserving the existing files added by Node.js.
|
||||
|
||||
```bash
|
||||
./tools/dep_updaters/update-c-ares.sh
|
||||
```
|
||||
|
||||
## Check that Node.js still builds and tests
|
||||
|
||||
It may be necessary to update `deps/cares/cares.gyp` if any significant changes
|
||||
have occurred upstream.
|
||||
|
||||
## Rebuild the main Node.js license
|
||||
|
||||
Run the `tools/license-builder.sh` script to rebuild the main Node.js `LICENSE`
|
||||
file. This may result in no changes if c-ares' license has not changed.
|
||||
|
||||
```console
|
||||
./tools/license-builder.sh
|
||||
```
|
||||
|
||||
If the updated `LICENSE` contains changes for other dependencies, those should
|
||||
be done in a separate pull request first.
|
||||
|
||||
## Commit the changes
|
||||
|
||||
```console
|
||||
git add -A deps/cares
|
||||
```
|
||||
|
||||
Add the rebuilt `LICENSE` if it has been updated.
|
||||
|
||||
```console
|
||||
git add LICENSE
|
||||
```
|
||||
|
||||
Commit the changes with a message like
|
||||
|
||||
```text
|
||||
deps: update c-ares to x.y.z
|
||||
|
||||
Updated as described in doc/contributing/maintaining-c-ares.md.
|
||||
```
|
||||
@ -1,106 +0,0 @@
|
||||
# Maintaining Dependencies
|
||||
|
||||
Node.js depends on additional components beyond the Node.js code
|
||||
itself. These dependencies provide both native and JavaScript code
|
||||
and are built together with the code under the `src` and `lib`
|
||||
directories to create the Node.js binaries.
|
||||
|
||||
All dependencies are located within the `deps` directory.
|
||||
|
||||
Any code which meets one or more of these conditions should
|
||||
be managed as a dependency:
|
||||
|
||||
* originates in an upstream project and is maintained
|
||||
in that upstream project.
|
||||
* is not built from the `preferred form of the work for
|
||||
making modifications to it` (see
|
||||
[GNU GPL v2, section 3.](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
|
||||
when `make node` is run. A good example is
|
||||
WASM code generated from C (the preferred form).
|
||||
Typically generation is only supported on a subset of platforms, needs
|
||||
additional tools, and is pre-built outside of the `make node`
|
||||
step and then committed as a WASM binary in the directory
|
||||
for the dependency under the `deps` directory.
|
||||
|
||||
By default all dependencies are bundled into the Node.js
|
||||
binary, however, `configure` options should be available to
|
||||
use an externalized version at runtime when:
|
||||
|
||||
* the dependency provides native code and is available as
|
||||
a shared library in one or more of the common Node.js
|
||||
distributions.
|
||||
* the dependency provides JavaScript and is not built
|
||||
from the `preferred form of the work for making modifications
|
||||
to it` when `make node` is run.
|
||||
|
||||
Many distributions use externalized dependencies for one or
|
||||
more of these reasons:
|
||||
|
||||
1. They have a requirement to build everything that they ship
|
||||
from the `preferred form of the work for making
|
||||
modifications to it`. This means that they need to
|
||||
replace any pre-built components (for example WASM
|
||||
binaries) with an equivalent that they have built.
|
||||
2. They manage the dependency separately as it is used by
|
||||
more applications than just Node.js. Linking against
|
||||
a shared library allows them to manage updates and
|
||||
CVE fixes against the library instead of having to
|
||||
patch all of the individual applications.
|
||||
3. They have a system wide configuration for the
|
||||
dependency that all applications should respect.
|
||||
|
||||
## Supporting externalized dependencies with native code
|
||||
|
||||
Support for externalized dependencies with native code for which a
|
||||
shared library is available can added by:
|
||||
|
||||
* adding options to `configure.py`. These are added to the
|
||||
shared\_optgroup and include an options to:
|
||||
* enable use of a shared library
|
||||
* set the name of the shared library
|
||||
* set the path to the directory with the includes for the
|
||||
shared library
|
||||
* set the path to where to find the shared library at
|
||||
runtime
|
||||
* add a call to configure\_library() to `configure.py` for the
|
||||
library at the end of list of existing configure\_library() calls.
|
||||
If there are additional libraries that are required it is
|
||||
possible to list more than one with the `pkgname` option.
|
||||
* in `node.gypi` guard the build for the dependency
|
||||
with `node_shared_depname` so that it is only built if
|
||||
the dependency is being bundled into Node.js itself. For example:
|
||||
|
||||
```text
|
||||
[ 'node_shared_brotli=="false"', {
|
||||
'dependencies': [ 'deps/brotli/brotli.gyp:brotli' ],
|
||||
}],
|
||||
```
|
||||
|
||||
## Supporting externalizable dependencies with JavaScript code
|
||||
|
||||
Support for an externalizable dependency with JavaScript code
|
||||
can be added by:
|
||||
|
||||
* adding an entry to the `sharable_builtins` map in
|
||||
`configure.py`. The path should correspond to the file
|
||||
within the deps directory that is normally bundled into
|
||||
Node.js. For example `deps/cjs-module-lexer/lexer.js`.
|
||||
This will add a new option for building with that dependency
|
||||
externalized. After adding the entry you can see
|
||||
the new option by running `./configure --help`.
|
||||
|
||||
* adding a call to `AddExternalizedBuiltin` to the constructor
|
||||
for BuiltinLoader in `src/node_builtins.cc` for the
|
||||
dependency using the `NODE_SHARED_BUILTLIN` #define generated for
|
||||
the dependency. After running `./configure` with the new
|
||||
option you can find the #define in `config.gypi`. You can cut and
|
||||
paste one of the existing entries and then update to match the
|
||||
import name for the dependency and the #define generated.
|
||||
|
||||
## Supporting non-externalized dependencies with JavaScript code
|
||||
|
||||
If the dependency consists of JavaScript in the
|
||||
`preferred form of the work for making modifications to it`, it
|
||||
can be added as a non-externalizable dependency. In this case
|
||||
simply add the path to the JavaScript file in the `deps_files`
|
||||
list in the `node.gyp` file.
|
||||
@ -1,39 +0,0 @@
|
||||
# Maintaining nghttp2 in Node.js
|
||||
|
||||
The low-level implementation of
|
||||
[HTTP2](https://nodejs.org/docs/latest/api/http2.html)
|
||||
is based on [nghttp2](https://nghttp2.org/). Updates are pulled into Node.js
|
||||
under [deps/nghttp2](https://github.com/nodejs/node/tree/HEAD/deps/nghttp2)
|
||||
as needed.
|
||||
|
||||
The low-level implementation is made available in the Node.js API through
|
||||
JavaScript code in the [lib](https://github.com/nodejs/node/tree/HEAD/lib)
|
||||
directory and C++ code in the
|
||||
[src](https://github.com/nodejs/node/tree/HEAD/src) directory.
|
||||
|
||||
## Step 1: Updating nghttp2
|
||||
|
||||
The `tools/dep_updaters/update-nghttp2.sh` script automates the update of the
|
||||
postject source files.
|
||||
|
||||
## Step 2: Test the build
|
||||
|
||||
```console
|
||||
$ make test-http2
|
||||
```
|
||||
|
||||
## Step 3: Commit new nghttp2
|
||||
|
||||
```console
|
||||
$ git add -A deps/nghttp2
|
||||
$ git commit -m "deps: upgrade nghttp2 to x.y.z"
|
||||
```
|
||||
|
||||
## Step 4: Update licenses
|
||||
|
||||
```console
|
||||
$ ./tools/license-builder.sh
|
||||
# The following commands are only necessary if there are changes
|
||||
$ git add .
|
||||
$ git commit -m "doc: update nghttp2 LICENSE using license-builder.sh"
|
||||
```
|
||||
@ -1,62 +0,0 @@
|
||||
# ngtcp2 and nghttp3
|
||||
|
||||
The ngtcp2 and nghttp3 dependencies provide the core functionality for
|
||||
QUIC and HTTP/3.
|
||||
|
||||
The sources are pulled from:
|
||||
|
||||
* ngtcp2: <https://github.com/ngtcp2/ngtcp2>
|
||||
* nghttp3: <https://github.com/ngtcp2/nghttp3>
|
||||
|
||||
In both the `ngtcp2` and `nghttp3` git repos, the active development occurs
|
||||
in the default branch (currently named `main` in each). Tagged versions do not
|
||||
always point to the default branch.
|
||||
|
||||
We only use a subset of the sources for each.
|
||||
|
||||
## Updating
|
||||
|
||||
The `nghttp3` library depends on `ngtcp2`. Both should always be updated
|
||||
together. From `ngtcp2` we only want the contents of the `lib` and `crypto`
|
||||
directories; from `nghttp3` we only want the contents of the `lib` directory.
|
||||
|
||||
After updating either dependency, check if any source files or include
|
||||
directories have been added or removed and update `ngtcp2.gyp` accordingly.
|
||||
|
||||
### Updating ngtcp2
|
||||
|
||||
The `tools/dep_updaters/update-ngtcp2.sh` script automates the update of the
|
||||
ngtcp2 source files.
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
1. Add ngtcp2:
|
||||
```console
|
||||
$ git add deps/ngtcp2
|
||||
```
|
||||
2. Commit the changes: `git commit`.
|
||||
3. Add a message like:
|
||||
```text
|
||||
deps: update ngtcp2 to <version>
|
||||
|
||||
Updated as described in doc/contributing/maintaining-ngtcp2.md.
|
||||
```
|
||||
|
||||
### Updating nghttp3
|
||||
|
||||
The `tools/dep_updaters/update-nghttp3.sh` script automates the update of the
|
||||
nghttp3 source files.
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
1. Add nghttp3:
|
||||
```console
|
||||
$ git add deps/ngtcp2
|
||||
```
|
||||
2. Commit the changes: `git commit`.
|
||||
3. Add a message like:
|
||||
```text
|
||||
deps: update nghttp3 to <version>
|
||||
|
||||
Updated as described in doc/contributing/maintaining-ngtcp2.md.
|
||||
```
|
||||
@ -1,51 +0,0 @@
|
||||
# Maintaining npm in Node.js
|
||||
|
||||
New pull requests should be opened when a "next" version of npm has
|
||||
been released. Once the "next" version has been promoted to "latest"
|
||||
the PR should be updated as necessary.
|
||||
|
||||
The specific Node.js release streams the new version will be able to land into
|
||||
are at the discretion of the release and LTS teams.
|
||||
|
||||
This process only covers full updates to new versions of npm. Cherry-picked
|
||||
changes can be reviewed and landed via the normal consensus seeking process.
|
||||
|
||||
## Step 1: Run the update script
|
||||
|
||||
In the following examples, `x.y.z` should match the npm version to update to.
|
||||
|
||||
```console
|
||||
$ ./tools/update-npm.sh x.y.z
|
||||
```
|
||||
|
||||
## Step 2: Commit new npm
|
||||
|
||||
```console
|
||||
$ git add -A deps/npm
|
||||
$ git commit -m "deps: upgrade npm to x.y.z"
|
||||
```
|
||||
|
||||
## Step 3: Update licenses
|
||||
|
||||
```console
|
||||
$ ./configure
|
||||
$ make -j4
|
||||
$ ./tools/license-builder.sh
|
||||
# The following commands are only necessary if there are changes
|
||||
$ git add .
|
||||
$ git commit -m "doc: update npm LICENSE using license-builder.sh"
|
||||
```
|
||||
|
||||
Note: please ensure you are only making the updates that are changed by npm.
|
||||
|
||||
## Step 4: Apply whitespace fix
|
||||
|
||||
```console
|
||||
$ git rebase --whitespace=fix main
|
||||
```
|
||||
|
||||
## Step 5: Test the build
|
||||
|
||||
```console
|
||||
$ make test-npm
|
||||
```
|
||||
@ -1,26 +0,0 @@
|
||||
# Maintaining postject
|
||||
|
||||
The [postject](https://github.com/nodejs/postject) dependency is used for the
|
||||
[Single Executable strategic initiative](https://github.com/nodejs/single-executable).
|
||||
|
||||
## Updating postject
|
||||
|
||||
The `tools/dep_updaters/update-postject.sh` script automates the update of the
|
||||
postject source files.
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
## Committing postject
|
||||
|
||||
1. Add postject:
|
||||
```console
|
||||
$ git add test/fixtures/postject-copy
|
||||
$ git add deps/postject
|
||||
```
|
||||
2. Commit the changes: `git commit`.
|
||||
3. Add a message like:
|
||||
```text
|
||||
deps,test: update postject to <version>
|
||||
|
||||
Updated as described in doc/contributing/maintaining-postject.md.
|
||||
```
|
||||
@ -1,25 +0,0 @@
|
||||
# Maintaining undici
|
||||
|
||||
The [undici](https://github.com/nodejs/undici) dependency is
|
||||
an HTTP/1.1 client, written from scratch for Node.js.
|
||||
|
||||
## Updating undici
|
||||
|
||||
The `tools/dep_updaters/update-undici.sh` script automates the update of the
|
||||
undici source files.
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
## Committing undici
|
||||
|
||||
1. Add undici:
|
||||
```console
|
||||
$ git add deps/undici
|
||||
```
|
||||
2. Commit the changes: `git commit`.
|
||||
3. Add a message like:
|
||||
```text
|
||||
deps: update undici to <version>
|
||||
|
||||
Updated as described in doc/contributing/maintaining-undici.md.
|
||||
```
|
||||
@ -1,36 +0,0 @@
|
||||
# Maintaining zlib
|
||||
|
||||
This copy of zlib comes from the Chromium team's zlib fork which incorporated
|
||||
performance improvements not currently available in standard zlib.
|
||||
|
||||
## Updating zlib
|
||||
|
||||
Update zlib:
|
||||
|
||||
```bash
|
||||
git clone https://chromium.googlesource.com/chromium/src/third_party/zlib
|
||||
cp deps/zlib/zlib.gyp deps/zlib/GN-scraper.py deps/zlib/win32/zlib.def deps
|
||||
rm -rf deps/zlib zlib/.git
|
||||
mv zlib deps/
|
||||
mv deps/zlib.gyp deps/GN-scraper.py deps/zlib/
|
||||
mkdir deps/zlib/win32
|
||||
mv deps/zlib.def deps/zlib/win32
|
||||
perl -i -pe 's|^#include "chromeconf.h"|//#include "chromeconf.h"|' deps/zlib/zconf.h
|
||||
```
|
||||
|
||||
Check that Node.js still builds and tests.
|
||||
|
||||
It may be necessary to update deps/zlib/zlib.gyp if any significant changes have
|
||||
occurred upstream.
|
||||
|
||||
## Committing zlib
|
||||
|
||||
Add zlib: `git add --all deps/zlib`
|
||||
|
||||
Commit the changes with a message like
|
||||
|
||||
```text
|
||||
deps: update zlib to upstream d7f3ca9
|
||||
|
||||
Updated as described in doc/contributing/maintaining-zlib.md.
|
||||
```
|
||||
@ -36,8 +36,8 @@ of cjs-module-lexer, complete the following steps:
|
||||
```text
|
||||
├── CHANGELOG.md
|
||||
├── dist
|
||||
│ ├── lexer.js
|
||||
│ └── lexer.mjs
|
||||
│ ├── lexer.js
|
||||
│ └── lexer.mjs
|
||||
├── lexer.js
|
||||
├── LICENSE
|
||||
├── package.json
|
||||
@ -45,7 +45,7 @@ of cjs-module-lexer, complete the following steps:
|
||||
```
|
||||
|
||||
* Update the link to the cjs-module-lexer in the list at the end of
|
||||
[doc/api/esm.md](../api/esm.md)
|
||||
[doc/api/esm.md](../../api/esm.md)
|
||||
to point to the updated version.
|
||||
|
||||
* Create a PR, adding the files in the deps/cjs-module-lexer that
|
||||
344
doc/contributing/maintaining/maintaining-dependencies.md
Normal file
344
doc/contributing/maintaining/maintaining-dependencies.md
Normal file
@ -0,0 +1,344 @@
|
||||
# Maintaining Dependencies
|
||||
|
||||
Node.js depends on additional components beyond the Node.js code
|
||||
itself. These dependencies provide both native and JavaScript code
|
||||
and are built together with the code under the `src` and `lib`
|
||||
directories to create the Node.js binaries.
|
||||
|
||||
All dependencies are located within the `deps` directory.
|
||||
This a list of all the dependencies:
|
||||
|
||||
* [acorn][]
|
||||
* [ada][]
|
||||
* [base64][]
|
||||
* [brotli][]
|
||||
* [c-ares][]
|
||||
* [cjs-module-lexer][]
|
||||
* [corepack][]
|
||||
* [googletest][]
|
||||
* [histogram][]
|
||||
* [icu-small][]
|
||||
* [llhttp][]
|
||||
* [minimatch][]
|
||||
* [nghttp2][]
|
||||
* [ngtcp2][]
|
||||
* [npm][]
|
||||
* [openssl][]
|
||||
* [postject][]
|
||||
* [simdutf][]
|
||||
* [undici][]
|
||||
* [uv][]
|
||||
* [uvwasi][]
|
||||
* [V8][]
|
||||
* [zlib][]
|
||||
|
||||
Any code which meets one or more of these conditions should
|
||||
be managed as a dependency:
|
||||
|
||||
* originates in an upstream project and is maintained
|
||||
in that upstream project.
|
||||
* is not built from the `preferred form of the work for
|
||||
making modifications to it` (see
|
||||
[GNU GPL v2, section 3.](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
|
||||
when `make node` is run. A good example is
|
||||
WASM code generated from C (the preferred form).
|
||||
Typically generation is only supported on a subset of platforms, needs
|
||||
additional tools, and is pre-built outside of the `make node`
|
||||
step and then committed as a WASM binary in the directory
|
||||
for the dependency under the `deps` directory.
|
||||
|
||||
By default all dependencies are bundled into the Node.js
|
||||
binary, however, `configure` options should be available to
|
||||
use an externalized version at runtime when:
|
||||
|
||||
* the dependency provides native code and is available as
|
||||
a shared library in one or more of the common Node.js
|
||||
distributions.
|
||||
* the dependency provides JavaScript and is not built
|
||||
from the `preferred form of the work for making modifications
|
||||
to it` when `make node` is run.
|
||||
|
||||
Many distributions use externalized dependencies for one or
|
||||
more of these reasons:
|
||||
|
||||
1. They have a requirement to build everything that they ship
|
||||
from the `preferred form of the work for making
|
||||
modifications to it`. This means that they need to
|
||||
replace any pre-built components (for example WASM
|
||||
binaries) with an equivalent that they have built.
|
||||
2. They manage the dependency separately as it is used by
|
||||
more applications than just Node.js. Linking against
|
||||
a shared library allows them to manage updates and
|
||||
CVE fixes against the library instead of having to
|
||||
patch all of the individual applications.
|
||||
3. They have a system wide configuration for the
|
||||
dependency that all applications should respect.
|
||||
|
||||
## Supporting externalized dependencies with native code
|
||||
|
||||
Support for externalized dependencies with native code for which a
|
||||
shared library is available can added by:
|
||||
|
||||
* adding options to `configure.py`. These are added to the
|
||||
shared\_optgroup and include an options to:
|
||||
* enable use of a shared library
|
||||
* set the name of the shared library
|
||||
* set the path to the directory with the includes for the
|
||||
shared library
|
||||
* set the path to where to find the shared library at
|
||||
runtime
|
||||
* add a call to configure\_library() to `configure.py` for the
|
||||
library at the end of list of existing configure\_library() calls.
|
||||
If there are additional libraries that are required it is
|
||||
possible to list more than one with the `pkgname` option.
|
||||
* in `node.gypi` guard the build for the dependency
|
||||
with `node_shared_depname` so that it is only built if
|
||||
the dependency is being bundled into Node.js itself. For example:
|
||||
|
||||
```text
|
||||
[ 'node_shared_brotli=="false"', {
|
||||
'dependencies': [ 'deps/brotli/brotli.gyp:brotli' ],
|
||||
}],
|
||||
```
|
||||
|
||||
## Supporting externalizable dependencies with JavaScript code
|
||||
|
||||
Support for an externalizable dependency with JavaScript code
|
||||
can be added by:
|
||||
|
||||
* adding an entry to the `sharable_builtins` map in
|
||||
`configure.py`. The path should correspond to the file
|
||||
within the deps directory that is normally bundled into
|
||||
Node.js. For example `deps/cjs-module-lexer/lexer.js`.
|
||||
This will add a new option for building with that dependency
|
||||
externalized. After adding the entry you can see
|
||||
the new option by running `./configure --help`.
|
||||
|
||||
* adding a call to `AddExternalizedBuiltin` to the constructor
|
||||
for BuiltinLoader in `src/node_builtins.cc` for the
|
||||
dependency using the `NODE_SHARED_BUILTLIN` #define generated for
|
||||
the dependency. After running `./configure` with the new
|
||||
option you can find the #define in `config.gypi`. You can cut and
|
||||
paste one of the existing entries and then update to match the
|
||||
import name for the dependency and the #define generated.
|
||||
|
||||
## Supporting non-externalized dependencies with JavaScript code
|
||||
|
||||
If the dependency consists of JavaScript in the
|
||||
`preferred form of the work for making modifications to it`, it
|
||||
can be added as a non-externalizable dependency. In this case
|
||||
simply add the path to the JavaScript file in the `deps_files`
|
||||
list in the `node.gyp` file.
|
||||
|
||||
## Updating dependencies
|
||||
|
||||
Most dependencies are automatically updated by
|
||||
[dependency-update-action][] that runs weekly.
|
||||
However, it is possible to manually update a dependency by running
|
||||
the corresponding script in `tools/update-deps`.
|
||||
[OpenSSL][] has its own update action: [update-openssl-action][].
|
||||
[npm-cli-bot](https://github.com/npm/cli/blob/latest/.github/workflows/create-node-pr.yml)
|
||||
takes care of [npm][] update, it is maintained by the npm team.
|
||||
|
||||
## Dependency list
|
||||
|
||||
### acorn
|
||||
|
||||
The [acorn](https://github.com/acornjs/acorn) dependency is a JavaScript parser.
|
||||
[acorn-walk](https://github.com/acornjs/acorn/tree/master/acorn-walk) is
|
||||
an abstract syntax tree walker for the ESTree format.
|
||||
|
||||
### ada
|
||||
|
||||
The [ada](https://github.com/ada-url/ada) dependency is a
|
||||
fast and spec-compliant URL parser written in C++.
|
||||
|
||||
### base64
|
||||
|
||||
The [base64](https://github.com/aklomp/base64) dependency is a base64
|
||||
stream encoding/decoding library in C99 with SIMD and OpenMP acceleration.
|
||||
It also contains wrapper functions to encode/decode simple
|
||||
length-delimited strings.
|
||||
|
||||
### brotli
|
||||
|
||||
The [brotli](https://github.com/google/brotli) dependency is
|
||||
used for the homonym generic-purpose lossless compression algorithm.
|
||||
|
||||
### c-ares
|
||||
|
||||
The [c-ares](https://github.com/c-ares/c-ares) is a C library
|
||||
for asynchronous DNS requests.
|
||||
|
||||
### cjs-module-lexer
|
||||
|
||||
The [cjs-module-lexer](https://github.com/nodejs/node/tree/HEAD/deps/cjs-module-lexer)
|
||||
dependency is used within the Node.js ESM implementation to detect the
|
||||
named exports of a CommonJS module.
|
||||
See [maintaining-cjs-module-lexer][] for more information.
|
||||
|
||||
## corepack
|
||||
|
||||
The [corepack](https://github.com/nodejs/corepack) dependency is a
|
||||
zero-runtime-dependency Node.js script that acts as a bridge between
|
||||
Node.js projects and the package managers they are intended to
|
||||
be used with during development.
|
||||
In practical terms, Corepack will let you use Yarn and pnpm without having to
|
||||
install them - just like what currently happens with npm, which is shipped
|
||||
by Node.js by default.
|
||||
|
||||
### googletest
|
||||
|
||||
The [googletest](https://github.com/google/googletest) dependency is Google’s
|
||||
C++ testing and mocking framework.
|
||||
|
||||
### histogram
|
||||
|
||||
The [histogram](https://github.com/HdrHistogram/HdrHistogram_c) dependency is
|
||||
a C port of High Dynamic Range (HDR) Histogram.
|
||||
|
||||
### icu-small
|
||||
|
||||
The [icu](http://site.icu-project.org) is widely used set of C/C++
|
||||
and Java libraries providing Unicode and Globalization
|
||||
support for software applications.
|
||||
See [maintaining-icu][] for more informations.
|
||||
|
||||
### llhttp
|
||||
|
||||
The [llhttp](https://github.com/nodejs/llhttp) dependency is
|
||||
the http parser used by Node.js.
|
||||
See [maintaining-http][] for more informations.
|
||||
|
||||
### minimatch
|
||||
|
||||
The [minimatch](https://github.com/isaacs/minimatch) dependency is a
|
||||
minimal matching utility.
|
||||
|
||||
### nghttp2
|
||||
|
||||
The [nghttp2](https://github.com/nghttp2/nghttp2) dependency is a C library
|
||||
implementing HTTP/2 protocol.
|
||||
See [maintaining-http][] for more informations.
|
||||
|
||||
### ngtcp2
|
||||
|
||||
The ngtcp2 and nghttp3 dependencies provide the core functionality for
|
||||
QUIC and HTTP/3.
|
||||
|
||||
The sources are pulled from:
|
||||
|
||||
* ngtcp2: <https://github.com/ngtcp2/ngtcp2>
|
||||
* nghttp3: <https://github.com/ngtcp2/nghttp3>
|
||||
|
||||
In both the `ngtcp2` and `nghttp3` git repos, the active development occurs
|
||||
in the default branch (currently named `main` in each). Tagged versions do not
|
||||
always point to the default branch.
|
||||
|
||||
We only use a subset of the sources for each.
|
||||
|
||||
The `nghttp3` library depends on `ngtcp2`. Both should always be updated
|
||||
together. From `ngtcp2` we only want the contents of the `lib` and `crypto`
|
||||
directories; from `nghttp3` we only want the contents of the `lib` directory.
|
||||
|
||||
### npm
|
||||
|
||||
The [npm](https://github.com/npm/cli) dependency is
|
||||
the package manager for JavaScript.
|
||||
|
||||
New pull requests should be opened when a "next" version of npm has
|
||||
been released. Once the "next" version has been promoted to "latest"
|
||||
the PR should be updated as necessary.
|
||||
|
||||
The specific Node.js release streams the new version will be able to land into
|
||||
are at the discretion of the release and LTS teams.
|
||||
|
||||
This process only covers full updates to new versions of npm. Cherry-picked
|
||||
changes can be reviewed and landed via the normal consensus seeking process.
|
||||
|
||||
### openssl
|
||||
|
||||
The [openssl](https://github.com/quictls/openssl) dependency is a
|
||||
fork of OpenSSL to enable QUIC.
|
||||
[OpenSSL](https://www.openssl.org/) is toolkit for general-purpose
|
||||
cryptography and secure communication.
|
||||
|
||||
Node.js currently uses the quictls/openssl fork, which closely tracks
|
||||
the main openssl/openssl releases with the addition of APIs to support
|
||||
the QUIC protocol.
|
||||
See [maintaining-openssl][] for more informations.
|
||||
|
||||
### postject
|
||||
|
||||
The [postject](https://github.com/nodejs/postject) dependency is used for the
|
||||
[Single Executable strategic initiative](https://github.com/nodejs/single-executable).
|
||||
|
||||
### simdutf
|
||||
|
||||
The [simdutf](https://github.com/simdutf/simdutf) dependency is
|
||||
a C++ library for fast UTF-8 decoding and encoding.
|
||||
|
||||
### undici
|
||||
|
||||
The [undici](https://github.com/nodejs/undici) dependency is an HTTP/1.1 client,
|
||||
written from scratch for Node.js..
|
||||
See [maintaining-http][] for more informations.
|
||||
|
||||
### uv
|
||||
|
||||
The [libuv](https://github.com/libuv/libuv) dependency is a
|
||||
multi-platform support library with a focus on asynchronous I/O.
|
||||
It was primarily developed for use by Node.js.
|
||||
|
||||
### uvwasi
|
||||
|
||||
The [uvwasi](https://github.com/nodejs/uvwasi) dependency implements
|
||||
the WASI system call API, so that WebAssembly runtimes can easily
|
||||
implement WASI calls.
|
||||
Under the hood, uvwasi leverages libuv where possible for maximum portability.
|
||||
See [maintaining-web-assembly][] for more informations.
|
||||
|
||||
### V8
|
||||
|
||||
[V8](https://chromium.googlesource.com/v8/v8.git/) is Google's open source
|
||||
high-performance JavaScript and WebAssembly engine, written in C++.
|
||||
See [maintaining-V8][] for more informations.
|
||||
|
||||
### zlib
|
||||
|
||||
The [zlib](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/zlib)
|
||||
dependency lossless data-compression library,
|
||||
it comes from the Chromium team's zlib fork which incorporated
|
||||
performance improvements not currently available in standard zlib.
|
||||
|
||||
[acorn]: #acorn
|
||||
[ada]: #ada
|
||||
[base64]: #base64
|
||||
[brotli]: #brotli
|
||||
[c-ares]: #c-ares
|
||||
[cjs-module-lexer]: #cjs-module-lexer
|
||||
[corepack]: #corepack
|
||||
[dependency-update-action]: ../../../.github/workflows/tools.yml
|
||||
[googletest]: #googletest
|
||||
[histogram]: #histogram
|
||||
[icu-small]: #icu-small
|
||||
[llhttp]: #llhttp
|
||||
[maintaining-V8]: ./maintaining-V8.md
|
||||
[maintaining-cjs-module-lexer]: ./maintaining-cjs-module-lexer.md
|
||||
[maintaining-http]: ./maintaining-http.md
|
||||
[maintaining-icu]: ./maintaining-icu.md
|
||||
[maintaining-openssl]: ./maintaining-openssl.md
|
||||
[maintaining-web-assembly]: ./maintaining-web-assembly.md
|
||||
[minimatch]: #minimatch
|
||||
[nghttp2]: #nghttp2
|
||||
[ngtcp2]: #ngtcp2
|
||||
[npm]: #npm
|
||||
[openssl]: #openssl
|
||||
[postject]: #postject
|
||||
[simdutf]: #simdutf
|
||||
[undici]: #undici
|
||||
[update-openssl-action]: ../../../.github/workflows/update-openssl.yml
|
||||
[uv]: #uv
|
||||
[uvwasi]: #uvwasi
|
||||
[v8]: #v8
|
||||
[zlib]: #zlib
|
||||
@ -62,15 +62,11 @@ more control is required. The current plan is for the following APIs:
|
||||
Fetch-based API. As this gets worked out we will discuss which
|
||||
APIs to expose in the Node.js API surface.
|
||||
|
||||
For info see [maintaining undici][].
|
||||
|
||||
### Server APIs
|
||||
|
||||
For the server APIs we do not yet have a clear path, other than wanting
|
||||
to align them with the APIs built for the client.
|
||||
|
||||
## Maintaining the HTTP APIs
|
||||
|
||||
### HTTP, HTTPS
|
||||
|
||||
The low-level implementation of the
|
||||
@ -80,42 +76,15 @@ are maintained in the [llhttp](https://github.com/nodejs/llhttp)
|
||||
repository. Updates are pulled into Node.js under
|
||||
[deps/llhttp](https://github.com/nodejs/node/tree/HEAD/deps/llhttp).
|
||||
|
||||
In order to update Node.js with a new version of llhttp you can use the
|
||||
`tools/dep_updaters/update-llhttp.sh` script.
|
||||
|
||||
The contents of the `deps/llhttp` folder should look like the following:
|
||||
|
||||
```bash
|
||||
$ find deps/llhttp
|
||||
|
||||
deps/llhttp/
|
||||
deps/llhttp/CMakeLists.txt
|
||||
deps/llhttp/include
|
||||
deps/llhttp/include/llhttp.h
|
||||
deps/llhttp/llhttp.gyp
|
||||
deps/llhttp/README.md
|
||||
deps/llhttp/common.gypi
|
||||
deps/llhttp/libllhttp.pc.in
|
||||
deps/llhttp/LICENSE-MIT
|
||||
deps/llhttp/src
|
||||
deps/llhttp/src/api.c
|
||||
deps/llhttp/src/http.c
|
||||
deps/llhttp/src/llhttp.c
|
||||
```
|
||||
|
||||
After updating, make sure the version in `CMakeLists.txt` and `include/llhttp.h`
|
||||
are the same and that they match the one you are expecting.
|
||||
|
||||
The low-level implementation is made available in the Node.js API through
|
||||
JavaScript code in the [lib](https://github.com/nodejs/node/tree/HEAD/lib)
|
||||
directory and C++ code in the
|
||||
[src](https://github.com/nodejs/node/tree/HEAD/src) directory.
|
||||
|
||||
### HTTP2
|
||||
|
||||
The low-level implementation of
|
||||
[HTTP2](https://nodejs.org/docs/latest/api/http2.html)
|
||||
is based on [nghttp2](https://nghttp2.org/). See [maintaining nghttp2][].
|
||||
is based on [nghttp2](https://nghttp2.org/). Updates are pulled into Node.js
|
||||
under [deps/nghttp2](https://github.com/nodejs/node/tree/HEAD/deps/nghttp2)
|
||||
as needed.
|
||||
|
||||
[maintaining nghttp2]: ./maintaining-nghttp2.md
|
||||
[maintaining undici]: ./maintaining-undici.md
|
||||
The low-level implementation is made available in the Node.js API through
|
||||
JavaScript code in the [lib](https://github.com/nodejs/node/tree/HEAD/lib)
|
||||
directory and C++ code in the
|
||||
[src](https://github.com/nodejs/node/tree/HEAD/src) directory
|
||||
@ -1,6 +1,8 @@
|
||||
# Maintaining OpenSSL
|
||||
|
||||
This document describes how to update `deps/openssl/`.
|
||||
OpenSSL is automatically updated by the [update-openssl-action][].
|
||||
There is also a script in `tools/dep_updaters` that can be used to update it.
|
||||
This document describes how to manually update `deps/openssl/`.
|
||||
|
||||
If you need to provide updates across all active release lines you will
|
||||
currently need to generate four PRs as follows:
|
||||
@ -155,4 +157,5 @@ regenerated and committed by:
|
||||
|
||||
Finally, build Node.js and run the tests.
|
||||
|
||||
[update-openssl-action]: ../../../.github/workflows/update-openssl.yml
|
||||
[v14.x-staging version]: https://github.com/nodejs/node/blob/v14.x-staging/doc/guides/maintaining-openssl.md
|
||||
@ -4,7 +4,7 @@ This document explains how to maintain the build files in the codebase.
|
||||
|
||||
## Overview
|
||||
|
||||
On how to build the Node.js core, see [Building Node.js](../../BUILDING.md).
|
||||
On how to build the Node.js core, see [Building Node.js](../../../BUILDING.md).
|
||||
|
||||
There are three main build files that may be directly run when building Node.js:
|
||||
|
||||
@ -88,12 +88,3 @@ The implementation of the bindings and the public API is in:
|
||||
* [src/node\_wasi.h](https://github.com/nodejs/node/blob/main/src/node_wasi.h)
|
||||
* [src/node\_wasi.cc](https://github.com/nodejs/node/blob/main/src/node_wasi.cc)
|
||||
* [lib/wasi.js](https://github.com/nodejs/node/blob/main/lib/wasi.js)
|
||||
|
||||
### Running the update script
|
||||
|
||||
The `tools/dep_updaters/update-uvwasi.sh` script automates the update of
|
||||
the uvwasi source files.
|
||||
|
||||
```bash
|
||||
./tools/dep_updaters/update-uvwasi.sh
|
||||
```
|
||||
@ -27,7 +27,7 @@ Note:
|
||||
|
||||
## See Also
|
||||
|
||||
* [docs/guides/maintaining-icu.md](../../doc/contributing/maintaining-icu.md)
|
||||
* [docs/guides/maintaining-icu.md](../../doc/contributing/maintaining/maintaining-icu.md)
|
||||
for information on maintaining ICU in Node.js
|
||||
|
||||
* [docs/api/intl.md](../../doc/api/intl.md) for information on the
|
||||
|
||||
Loading…
Reference in New Issue
Block a user