From 05b4919b336810fe1338c7efd8804ac05f9c09d5 Mon Sep 17 00:00:00 2001 From: Marco Ippolito Date: Mon, 17 Apr 2023 11:06:15 +0200 Subject: [PATCH] doc: create maintaining folder for deps --- .github/CODEOWNERS | 3 +- doc/contributing/maintaining-acorn.md | 47 --- doc/contributing/maintaining-brotli.md | 25 -- doc/contributing/maintaining-c-ares.md | 58 --- .../maintaining-cjs-module-lexer.md | 59 --- doc/contributing/maintaining-dependencies.md | 106 ------ doc/contributing/maintaining-nghttp2.md | 39 -- doc/contributing/maintaining-ngtpc2.md | 62 ---- doc/contributing/maintaining-npm.md | 51 --- doc/contributing/maintaining-postject.md | 26 -- doc/contributing/maintaining-undici.md | 25 -- doc/contributing/maintaining-zlib.md | 36 -- .../maintaining-V8.md | 0 doc/maintaining/maintaining-dependencies.md | 351 ++++++++++++++++++ .../maintaining-http.md | 45 +-- .../maintaining-icu.md | 0 .../maintaining-openssl.md | 5 +- .../maintaining-root-certs.md | 0 .../maintaining-shared-library-support.md | 0 ...g-single-executable-application-support.md | 0 .../maintaining-the-build-files.md | 0 .../maintaining-types-for-nodejs.md | 0 .../maintaining-web-assembly.md | 9 - 23 files changed, 363 insertions(+), 584 deletions(-) delete mode 100644 doc/contributing/maintaining-acorn.md delete mode 100644 doc/contributing/maintaining-brotli.md delete mode 100644 doc/contributing/maintaining-c-ares.md delete mode 100644 doc/contributing/maintaining-cjs-module-lexer.md delete mode 100644 doc/contributing/maintaining-dependencies.md delete mode 100644 doc/contributing/maintaining-nghttp2.md delete mode 100644 doc/contributing/maintaining-ngtpc2.md delete mode 100644 doc/contributing/maintaining-npm.md delete mode 100644 doc/contributing/maintaining-postject.md delete mode 100644 doc/contributing/maintaining-undici.md delete mode 100644 doc/contributing/maintaining-zlib.md rename doc/{contributing => maintaining}/maintaining-V8.md (100%) create mode 100644 doc/maintaining/maintaining-dependencies.md rename doc/{contributing => maintaining}/maintaining-http.md (79%) rename doc/{contributing => maintaining}/maintaining-icu.md (100%) rename doc/{contributing => maintaining}/maintaining-openssl.md (94%) rename doc/{contributing => maintaining}/maintaining-root-certs.md (100%) rename doc/{contributing => maintaining}/maintaining-shared-library-support.md (100%) rename doc/{contributing => maintaining}/maintaining-single-executable-application-support.md (100%) rename doc/{contributing => maintaining}/maintaining-the-build-files.md (100%) rename doc/{contributing => maintaining}/maintaining-types-for-nodejs.md (100%) rename doc/{contributing => maintaining}/maintaining-web-assembly.md (95%) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d26fb30e3cdc44..6e853e20fdacd5 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -144,8 +144,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/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 diff --git a/doc/contributing/maintaining-acorn.md b/doc/contributing/maintaining-acorn.md deleted file mode 100644 index ef73c07627a31b..00000000000000 --- a/doc/contributing/maintaining-acorn.md +++ /dev/null @@ -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 - - 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 - - Updated as described in doc/contributing/maintaining-acorn.md. - ``` diff --git a/doc/contributing/maintaining-brotli.md b/doc/contributing/maintaining-brotli.md deleted file mode 100644 index d2d725d161d041..00000000000000 --- a/doc/contributing/maintaining-brotli.md +++ /dev/null @@ -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 - - Updated as described in doc/contributing/maintaining-brotli.md. - ``` diff --git a/doc/contributing/maintaining-c-ares.md b/doc/contributing/maintaining-c-ares.md deleted file mode 100644 index d4b48dbfdb5bdb..00000000000000 --- a/doc/contributing/maintaining-c-ares.md +++ /dev/null @@ -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. -``` diff --git a/doc/contributing/maintaining-cjs-module-lexer.md b/doc/contributing/maintaining-cjs-module-lexer.md deleted file mode 100644 index 43dcfe0d2316d5..00000000000000 --- a/doc/contributing/maintaining-cjs-module-lexer.md +++ /dev/null @@ -1,59 +0,0 @@ -# Maintaining 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. - -It is used within -[`node:internal/modules/esm/translators`](https://github.com/nodejs/node/blob/HEAD/lib/internal/modules/esm/translators.js) -in which both `internal/deps/cjs-module-lexer/lexer` and -`internal/deps/cjs-module-lexer/dist/lexer` are required and used. - -`internal/deps/cjs-module-lexer/lexer` -is a regular JavaScript implementation that is -used when WebAssembly is not available on a platform. -`internal/deps/cjs-module-lexer/dist/lexer` is a faster -implementation using WebAssembly which is generated from a -C based implementation. These two paths -resolve to the files in `deps/cjs-module-lexer` due to their -inclusion in the `deps_files` entry in -[node.gyp](https://github.com/nodejs/node/blob/main/node.gyp). - -The two different versions of lexer.js are maintained in the -[nodejs/cjs-module-lexer][] project. - -In order to update the Node.js dependencies to use to a newer verion -of cjs-module-lexer, complete the following steps: - -* Clone [nodejs/cjs-module-lexer][] - and check out the version that you want Node.js to use. -* Follow the WASM build steps outlined in - [wasm-build-steps](https://github.com/nodejs/cjs-module-lexer#wasm-build-steps). - This will generate the WASM based dist/lexer.js file. -* Preserving the same directory structure, copy the following files over - to `deps/cjs-module-lexer` directory where you have checked out Node.js. - -```text -├── CHANGELOG.md -├── dist -│   ├── lexer.js -│   └── lexer.mjs -├── lexer.js -├── LICENSE -├── package.json -└── README.md -``` - -* Update the link to the cjs-module-lexer in the list at the end of - [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 - were modified. - -If updates are needed to cjs-module-lexer for Node.js, first PR -those updates into -[nodejs/cjs-module-lexer][], -request a release and then pull in the updated version once available. - -[nodejs/cjs-module-lexer]: https://github.com/nodejs/cjs-module-lexer diff --git a/doc/contributing/maintaining-dependencies.md b/doc/contributing/maintaining-dependencies.md deleted file mode 100644 index 52d7e364d5875c..00000000000000 --- a/doc/contributing/maintaining-dependencies.md +++ /dev/null @@ -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 BuildinLoader 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 - inport 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. diff --git a/doc/contributing/maintaining-nghttp2.md b/doc/contributing/maintaining-nghttp2.md deleted file mode 100644 index 41ba0b58508513..00000000000000 --- a/doc/contributing/maintaining-nghttp2.md +++ /dev/null @@ -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" -``` diff --git a/doc/contributing/maintaining-ngtpc2.md b/doc/contributing/maintaining-ngtpc2.md deleted file mode 100644 index 504e0dccc9bed4..00000000000000 --- a/doc/contributing/maintaining-ngtpc2.md +++ /dev/null @@ -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: -* 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 - - 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 - - Updated as described in doc/contributing/maintaining-ngtcp2.md. - ``` diff --git a/doc/contributing/maintaining-npm.md b/doc/contributing/maintaining-npm.md deleted file mode 100644 index a1b6e170dd1e97..00000000000000 --- a/doc/contributing/maintaining-npm.md +++ /dev/null @@ -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 -``` diff --git a/doc/contributing/maintaining-postject.md b/doc/contributing/maintaining-postject.md deleted file mode 100644 index 9f1bef0d776a4b..00000000000000 --- a/doc/contributing/maintaining-postject.md +++ /dev/null @@ -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 - - Updated as described in doc/contributing/maintaining-postject.md. - ``` diff --git a/doc/contributing/maintaining-undici.md b/doc/contributing/maintaining-undici.md deleted file mode 100644 index 0ebae05f4d03ae..00000000000000 --- a/doc/contributing/maintaining-undici.md +++ /dev/null @@ -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 - - Updated as described in doc/contributing/maintaining-undici.md. - ``` diff --git a/doc/contributing/maintaining-zlib.md b/doc/contributing/maintaining-zlib.md deleted file mode 100644 index 35a6d82299c005..00000000000000 --- a/doc/contributing/maintaining-zlib.md +++ /dev/null @@ -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. -``` diff --git a/doc/contributing/maintaining-V8.md b/doc/maintaining/maintaining-V8.md similarity index 100% rename from doc/contributing/maintaining-V8.md rename to doc/maintaining/maintaining-V8.md diff --git a/doc/maintaining/maintaining-dependencies.md b/doc/maintaining/maintaining-dependencies.md new file mode 100644 index 00000000000000..e1ec8ca22e56cb --- /dev/null +++ b/doc/maintaining/maintaining-dependencies.md @@ -0,0 +1,351 @@ +# 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][] +* [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 BuildinLoader 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 + inport 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][] + +## 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. + +It is used within +[`node:internal/modules/esm/translators`](https://github.com/nodejs/node/blob/HEAD/lib/internal/modules/esm/translators.js) +in which both `internal/deps/cjs-module-lexer/lexer` and +`internal/deps/cjs-module-lexer/dist/lexer` are required and used. + +`internal/deps/cjs-module-lexer/lexer` +is a regular JavaScript implementation that is +used when WebAssembly is not available on a platform. +`internal/deps/cjs-module-lexer/dist/lexer` is a faster +implementation using WebAssembly which is generated from a +C based implementation. These two paths +resolve to the files in `deps/cjs-module-lexer` due to their +inclusion in the `deps_files` entry in +[node.gyp](https://github.com/nodejs/node/blob/main/node.gyp). + +The two different versions of lexer.js are maintained in the +\[nodejs/cjs-module-lexer]\[] project. + +## 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. + +### 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: +* 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-http]: ./maintaining-http.md +[maintaining-icu]: ./maintaining-icu.md +[maintaining-openssl]: ./maintaining-openssl.md +[maintaining-web-assembly]: ./maintaining-web-assembly.md +[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 diff --git a/doc/contributing/maintaining-http.md b/doc/maintaining/maintaining-http.md similarity index 79% rename from doc/contributing/maintaining-http.md rename to doc/maintaining/maintaining-http.md index 3735c82e7b5393..a1ffdff5045e8a 100644 --- a/doc/contributing/maintaining-http.md +++ b/doc/maintaining/maintaining-http.md @@ -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 diff --git a/doc/contributing/maintaining-icu.md b/doc/maintaining/maintaining-icu.md similarity index 100% rename from doc/contributing/maintaining-icu.md rename to doc/maintaining/maintaining-icu.md diff --git a/doc/contributing/maintaining-openssl.md b/doc/maintaining/maintaining-openssl.md similarity index 94% rename from doc/contributing/maintaining-openssl.md rename to doc/maintaining/maintaining-openssl.md index 678b0df92c22f0..eed34f25c455b1 100644 --- a/doc/contributing/maintaining-openssl.md +++ b/doc/maintaining/maintaining-openssl.md @@ -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 diff --git a/doc/contributing/maintaining-root-certs.md b/doc/maintaining/maintaining-root-certs.md similarity index 100% rename from doc/contributing/maintaining-root-certs.md rename to doc/maintaining/maintaining-root-certs.md diff --git a/doc/contributing/maintaining-shared-library-support.md b/doc/maintaining/maintaining-shared-library-support.md similarity index 100% rename from doc/contributing/maintaining-shared-library-support.md rename to doc/maintaining/maintaining-shared-library-support.md diff --git a/doc/contributing/maintaining-single-executable-application-support.md b/doc/maintaining/maintaining-single-executable-application-support.md similarity index 100% rename from doc/contributing/maintaining-single-executable-application-support.md rename to doc/maintaining/maintaining-single-executable-application-support.md diff --git a/doc/contributing/maintaining-the-build-files.md b/doc/maintaining/maintaining-the-build-files.md similarity index 100% rename from doc/contributing/maintaining-the-build-files.md rename to doc/maintaining/maintaining-the-build-files.md diff --git a/doc/contributing/maintaining-types-for-nodejs.md b/doc/maintaining/maintaining-types-for-nodejs.md similarity index 100% rename from doc/contributing/maintaining-types-for-nodejs.md rename to doc/maintaining/maintaining-types-for-nodejs.md diff --git a/doc/contributing/maintaining-web-assembly.md b/doc/maintaining/maintaining-web-assembly.md similarity index 95% rename from doc/contributing/maintaining-web-assembly.md rename to doc/maintaining/maintaining-web-assembly.md index eb32d175d61da9..6eaa545186309b 100644 --- a/doc/contributing/maintaining-web-assembly.md +++ b/doc/maintaining/maintaining-web-assembly.md @@ -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 -```