2016-09-20 04:54:35 +00:00
|
|
|
# Building Node.js
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2018-10-08 16:24:37 +00:00
|
|
|
Depending on what platform or features you need, the build process may
|
|
|
|
|
differ. After you've built a binary, running the
|
|
|
|
|
test suite to confirm that the binary works as intended is a good next step.
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2018-10-08 16:24:37 +00:00
|
|
|
If you can reproduce a test failure, search for it in the
|
2016-03-09 23:41:52 +00:00
|
|
|
[Node.js issue tracker](https://github.com/nodejs/node/issues) or
|
|
|
|
|
file a new issue.
|
|
|
|
|
|
2021-02-06 16:14:25 +00:00
|
|
|
## Table of contents
|
2018-09-28 14:45:44 +00:00
|
|
|
|
2018-10-20 01:33:00 +00:00
|
|
|
* [Supported platforms](#supported-platforms)
|
|
|
|
|
* [Input](#input)
|
|
|
|
|
* [Strategy](#strategy)
|
2019-03-17 11:31:29 +00:00
|
|
|
* [Platform list](#platform-list)
|
2018-10-20 01:33:00 +00:00
|
|
|
* [Supported toolchains](#supported-toolchains)
|
2019-03-17 11:31:29 +00:00
|
|
|
* [Official binary platforms and toolchains](#official-binary-platforms-and-toolchains)
|
2018-10-20 01:33:00 +00:00
|
|
|
* [OpenSSL asm support](#openssl-asm-support)
|
2019-03-17 11:31:29 +00:00
|
|
|
* [Previous versions of this document](#previous-versions-of-this-document)
|
2018-10-20 01:33:00 +00:00
|
|
|
* [Building Node.js on supported platforms](#building-nodejs-on-supported-platforms)
|
2024-08-04 22:35:41 +00:00
|
|
|
* [Prerequisites](#prerequisites)
|
2019-06-28 08:01:02 +00:00
|
|
|
* [Unix and macOS](#unix-and-macos)
|
|
|
|
|
* [Unix prerequisites](#unix-prerequisites)
|
|
|
|
|
* [macOS prerequisites](#macos-prerequisites)
|
2019-11-06 11:49:27 +00:00
|
|
|
* [Building Node.js](#building-nodejs-1)
|
2020-10-19 18:27:32 +00:00
|
|
|
* [Installing Node.js](#installing-nodejs)
|
2018-10-20 01:33:00 +00:00
|
|
|
* [Running Tests](#running-tests)
|
2018-10-29 05:59:56 +00:00
|
|
|
* [Running Coverage](#running-coverage)
|
2018-10-20 01:33:00 +00:00
|
|
|
* [Building the documentation](#building-the-documentation)
|
|
|
|
|
* [Building a debug build](#building-a-debug-build)
|
2023-04-23 08:21:51 +00:00
|
|
|
* [Building an ASan build](#building-an-asan-build)
|
2020-12-09 12:29:15 +00:00
|
|
|
* [Speeding up frequent rebuilds when developing](#speeding-up-frequent-rebuilds-when-developing)
|
2020-01-28 00:58:07 +00:00
|
|
|
* [Troubleshooting Unix and macOS builds](#troubleshooting-unix-and-macos-builds)
|
2019-03-17 11:31:29 +00:00
|
|
|
* [Windows](#windows)
|
2024-08-04 22:35:41 +00:00
|
|
|
* [Windows Prerequisites](#windows-prerequisites)
|
2019-06-28 08:01:02 +00:00
|
|
|
* [Option 1: Manual install](#option-1-manual-install)
|
2019-11-06 11:49:27 +00:00
|
|
|
* [Option 2: Automated install with Boxstarter](#option-2-automated-install-with-boxstarter)
|
2020-01-28 00:58:07 +00:00
|
|
|
* [Building Node.js](#building-nodejs-2)
|
2022-08-12 10:29:23 +00:00
|
|
|
* [Android](#android)
|
2019-06-28 08:01:02 +00:00
|
|
|
* [`Intl` (ECMA-402) support](#intl-ecma-402-support)
|
|
|
|
|
* [Build with full ICU support (all locales supported by ICU)](#build-with-full-icu-support-all-locales-supported-by-icu)
|
|
|
|
|
* [Unix/macOS](#unixmacos)
|
|
|
|
|
* [Windows](#windows-1)
|
2019-09-30 18:17:49 +00:00
|
|
|
* [Trimmed: `small-icu` (English only) support](#trimmed-small-icu-english-only-support)
|
2019-06-28 08:01:02 +00:00
|
|
|
* [Unix/macOS](#unixmacos-1)
|
|
|
|
|
* [Windows](#windows-2)
|
2019-09-30 18:17:49 +00:00
|
|
|
* [Building without Intl support](#building-without-intl-support)
|
2019-06-28 08:01:02 +00:00
|
|
|
* [Unix/macOS](#unixmacos-2)
|
|
|
|
|
* [Windows](#windows-3)
|
2020-01-28 00:58:07 +00:00
|
|
|
* [Use existing installed ICU (Unix/macOS only)](#use-existing-installed-icu-unixmacos-only)
|
2019-09-30 18:17:49 +00:00
|
|
|
* [Build with a specific ICU](#build-with-a-specific-icu)
|
|
|
|
|
* [Unix/macOS](#unixmacos-3)
|
|
|
|
|
* [Windows](#windows-4)
|
2022-05-14 08:04:48 +00:00
|
|
|
* [Configuring OpenSSL config appname](#configure-openssl-appname)
|
2018-10-20 01:33:00 +00:00
|
|
|
* [Building Node.js with FIPS-compliant OpenSSL](#building-nodejs-with-fips-compliant-openssl)
|
|
|
|
|
* [Building Node.js with external core modules](#building-nodejs-with-external-core-modules)
|
2019-09-30 18:17:49 +00:00
|
|
|
* [Unix/macOS](#unixmacos-4)
|
|
|
|
|
* [Windows](#windows-5)
|
2019-03-17 11:31:29 +00:00
|
|
|
* [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs)
|
2018-09-28 14:45:44 +00:00
|
|
|
|
2017-03-17 21:34:54 +00:00
|
|
|
## Supported platforms
|
|
|
|
|
|
2018-01-04 23:37:53 +00:00
|
|
|
This list of supported platforms is current as of the branch/release to
|
2018-10-30 04:51:55 +00:00
|
|
|
which it belongs.
|
2017-03-17 21:34:54 +00:00
|
|
|
|
|
|
|
|
### Input
|
|
|
|
|
|
2018-10-12 00:15:15 +00:00
|
|
|
Node.js relies on V8 and libuv. We adopt a subset of their supported platforms.
|
2017-03-17 21:34:54 +00:00
|
|
|
|
|
|
|
|
### Strategy
|
|
|
|
|
|
2018-10-30 04:51:55 +00:00
|
|
|
There are three support tiers:
|
2017-03-17 21:34:54 +00:00
|
|
|
|
2019-03-17 11:31:29 +00:00
|
|
|
* **Tier 1**: These platforms represent the majority of Node.js users. The
|
|
|
|
|
Node.js Build Working Group maintains infrastructure for full test coverage.
|
2019-12-02 14:13:57 +00:00
|
|
|
Test failures on tier 1 platforms will block releases.
|
2019-03-17 11:31:29 +00:00
|
|
|
* **Tier 2**: These platforms represent smaller segments of the Node.js user
|
|
|
|
|
base. The Node.js Build Working Group maintains infrastructure for full test
|
2019-12-09 14:19:36 +00:00
|
|
|
coverage. Test failures on tier 2 platforms will block releases.
|
|
|
|
|
Infrastructure issues may delay the release of binaries for these platforms.
|
2019-03-17 11:31:29 +00:00
|
|
|
* **Experimental**: May not compile or test suite may not pass. The core team
|
|
|
|
|
does not create releases for these platforms. Test failures on experimental
|
|
|
|
|
platforms do not block releases. Contributions to improve support for these
|
|
|
|
|
platforms are welcome.
|
|
|
|
|
|
|
|
|
|
Platforms may move between tiers between major release lines. The table below
|
2019-12-23 15:17:40 +00:00
|
|
|
will reflect those changes.
|
2019-03-17 11:31:29 +00:00
|
|
|
|
|
|
|
|
### Platform list
|
|
|
|
|
|
2019-12-11 15:03:05 +00:00
|
|
|
Node.js compilation/execution support depends on operating system, architecture,
|
|
|
|
|
and libc version. The table below lists the support tier for each supported
|
|
|
|
|
combination. A list of [supported compile toolchains](#supported-toolchains) is
|
|
|
|
|
also supplied for tier 1 platforms.
|
2019-03-17 11:31:29 +00:00
|
|
|
|
|
|
|
|
**For production applications, run Node.js on supported platforms only.**
|
2017-04-26 16:59:53 +00:00
|
|
|
|
2019-01-30 22:53:21 +00:00
|
|
|
Node.js does not support a platform version if a vendor has expired support
|
2019-03-04 23:32:34 +00:00
|
|
|
for it. In other words, Node.js does not support running on End-of-Life (EoL)
|
2019-01-30 22:53:21 +00:00
|
|
|
platforms. This is true regardless of entries in the table below.
|
|
|
|
|
|
2024-05-30 14:28:47 +00:00
|
|
|
| Operating System | Architectures | Versions | Support Type | Notes |
|
|
|
|
|
| ---------------- | ---------------- | --------------------------------- | ------------ | ------------------------------------ |
|
|
|
|
|
| GNU/Linux | x64 | kernel >= 4.18[^1], glibc >= 2.28 | Tier 1 | e.g. Ubuntu 20.04, Debian 10, RHEL 8 |
|
|
|
|
|
| GNU/Linux | x64 | kernel >= 3.10, musl >= 1.1.19 | Experimental | e.g. Alpine 3.8 |
|
|
|
|
|
| GNU/Linux | x86 | kernel >= 3.10, glibc >= 2.17 | Experimental | Downgraded as of Node.js 10 |
|
|
|
|
|
| GNU/Linux | arm64 | kernel >= 4.18[^1], glibc >= 2.28 | Tier 1 | e.g. Ubuntu 20.04, Debian 10, RHEL 8 |
|
|
|
|
|
| GNU/Linux | armv7 | kernel >= 4.18[^1], glibc >= 2.28 | Tier 1 | e.g. Ubuntu 20.04, Debian 11 |
|
|
|
|
|
| GNU/Linux | armv6 | kernel >= 4.14, glibc >= 2.24 | Experimental | Downgraded as of Node.js 12 |
|
|
|
|
|
| GNU/Linux | ppc64le >=power8 | kernel >= 4.18[^1], glibc >= 2.28 | Tier 2 | e.g. Ubuntu 20.04, RHEL 8 |
|
|
|
|
|
| GNU/Linux | s390x | kernel >= 4.18[^1], glibc >= 2.28 | Tier 2 | e.g. RHEL 8 |
|
|
|
|
|
| GNU/Linux | loong64 | kernel >= 5.19, glibc >= 2.36 | Experimental | |
|
|
|
|
|
| Windows | x64 | >= Windows 10/Server 2016 | Tier 1 | [^2],[^3] |
|
|
|
|
|
| Windows | arm64 | >= Windows 10 | Tier 2 | |
|
|
|
|
|
| macOS | x64 | >= 11.0 | Tier 1 | For notes about compilation see [^4] |
|
|
|
|
|
| macOS | arm64 | >= 11.0 | Tier 1 | |
|
|
|
|
|
| SmartOS | x64 | >= 18 | Tier 2 | |
|
|
|
|
|
| AIX | ppc64be >=power8 | >= 7.2 TL04 | Tier 2 | |
|
|
|
|
|
| FreeBSD | x64 | >= 13.2 | Experimental | |
|
2022-04-13 06:36:08 +00:00
|
|
|
|
2024-04-10 23:08:39 +00:00
|
|
|
<!--lint disable final-definition-->
|
|
|
|
|
|
2022-04-13 06:36:08 +00:00
|
|
|
[^1]: Older kernel versions may work. However official Node.js release
|
|
|
|
|
binaries are [built on RHEL 8 systems](#official-binary-platforms-and-toolchains)
|
|
|
|
|
with kernel 4.18.
|
|
|
|
|
|
|
|
|
|
[^2]: On Windows, running Node.js in Windows terminal emulators
|
2021-10-16 02:52:13 +00:00
|
|
|
like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty)
|
|
|
|
|
for the tty channels to work (e.g. `winpty node.exe script.js`).
|
|
|
|
|
In "Git bash" if you call the node shell alias (`node` without the `.exe`
|
|
|
|
|
extension), `winpty` is used automatically.
|
|
|
|
|
|
2022-04-13 06:36:08 +00:00
|
|
|
[^3]: The Windows Subsystem for Linux (WSL) is not
|
2021-10-16 02:52:13 +00:00
|
|
|
supported, but the GNU/Linux build process and binaries should work. The
|
|
|
|
|
community will only address issues that reproduce on native GNU/Linux
|
|
|
|
|
systems. Issues that only reproduce on WSL should be reported in the
|
|
|
|
|
[WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the
|
2021-11-25 21:13:17 +00:00
|
|
|
Windows binary (`node.exe`) in WSL will not work without workarounds such as
|
|
|
|
|
stdio redirection.
|
2021-10-16 02:52:13 +00:00
|
|
|
|
2024-05-30 14:28:47 +00:00
|
|
|
[^4]: Our macOS x64 Binaries are compiled with 11.0 as a target. Xcode 13 is
|
2021-10-16 02:52:13 +00:00
|
|
|
required to compile.
|
2021-07-30 10:05:50 +00:00
|
|
|
|
2024-04-10 23:08:39 +00:00
|
|
|
<!--lint enable final-definition-->
|
|
|
|
|
|
2017-03-17 21:34:54 +00:00
|
|
|
### Supported toolchains
|
|
|
|
|
|
2018-10-30 17:31:18 +00:00
|
|
|
Depending on the host platform, the selection of toolchains may vary.
|
2017-03-17 21:34:54 +00:00
|
|
|
|
2019-03-17 11:31:29 +00:00
|
|
|
| Operating System | Compiler Versions |
|
|
|
|
|
| ---------------- | -------------------------------------------------------------- |
|
2024-08-05 13:25:44 +00:00
|
|
|
| Linux | GCC >= 12.2 |
|
2023-10-09 16:25:32 +00:00
|
|
|
| Windows | Visual Studio >= 2022 with the Windows 10 SDK on a 64-bit host |
|
2023-08-14 11:54:44 +00:00
|
|
|
| macOS | Xcode >= 13 (Apple LLVM >= 12) |
|
2019-03-17 11:31:29 +00:00
|
|
|
|
|
|
|
|
### Official binary platforms and toolchains
|
|
|
|
|
|
|
|
|
|
Binaries at <https://nodejs.org/download/release/> are produced on:
|
|
|
|
|
|
2023-04-03 14:48:11 +00:00
|
|
|
| Binary package | Platform and Toolchain |
|
|
|
|
|
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
|
|
|
| aix-ppc64 | AIX 7.2 TL04 on PPC64BE with GCC 10 |
|
2023-08-14 11:54:44 +00:00
|
|
|
| darwin-x64 | macOS 11, Xcode 13 with -mmacosx-version-min=11.0 |
|
|
|
|
|
| darwin-arm64 (and .pkg) | macOS 11 (arm64), Xcode 13 with -mmacosx-version-min=11.0 |
|
2023-04-03 14:48:11 +00:00
|
|
|
| linux-arm64 | RHEL 8 with GCC 10[^6] |
|
|
|
|
|
| linux-armv7l | Cross-compiled on RHEL 8 x64 with [custom GCC toolchain](https://github.com/rvagg/rpi-newer-crosstools)[^7] |
|
|
|
|
|
| linux-ppc64le | RHEL 8 with gcc-toolset-10[^6] |
|
|
|
|
|
| linux-s390x | RHEL 8 with gcc-toolset-10[^6] |
|
|
|
|
|
| linux-x64 | RHEL 8 with gcc-toolset-10[^6] |
|
2024-05-30 14:28:47 +00:00
|
|
|
| win-x64 | Windows Server 2022 (x64) with Visual Studio 2022 |
|
2019-03-17 11:31:29 +00:00
|
|
|
|
2024-04-10 23:08:39 +00:00
|
|
|
<!--lint disable final-definition-->
|
|
|
|
|
|
2022-04-13 06:36:08 +00:00
|
|
|
[^6]: Binaries produced on these systems are compatible with glibc >= 2.28
|
|
|
|
|
and libstdc++ >= 6.0.25 (`GLIBCXX_3.4.25`). These are available on
|
|
|
|
|
distributions natively supporting GCC 8.1 or higher, such as Debian 10,
|
|
|
|
|
RHEL 8 and Ubuntu 20.04.
|
2017-03-17 21:34:54 +00:00
|
|
|
|
2023-04-03 14:48:11 +00:00
|
|
|
[^7]: Binaries produced on these systems are compatible with glibc >= 2.28
|
|
|
|
|
and libstdc++ >= 6.0.28 (`GLIBCXX_3.4.28`). These are available on
|
|
|
|
|
distributions natively supporting GCC 9.3 or higher, such as Debian 11,
|
|
|
|
|
Ubuntu 20.04.
|
|
|
|
|
|
2024-04-10 23:08:39 +00:00
|
|
|
<!--lint enable final-definition-->
|
|
|
|
|
|
2018-03-07 13:31:05 +00:00
|
|
|
#### OpenSSL asm support
|
|
|
|
|
|
2018-11-10 01:54:00 +00:00
|
|
|
OpenSSL-1.1.1 requires the following assembler version for use of asm
|
2021-09-18 00:23:11 +00:00
|
|
|
support on x86\_64 and ia32.
|
2018-03-07 13:31:05 +00:00
|
|
|
|
2018-11-10 01:54:00 +00:00
|
|
|
For use of AVX-512,
|
|
|
|
|
|
|
|
|
|
* gas (GNU assembler) version 2.26 or higher
|
|
|
|
|
* nasm version 2.11.8 or higher in Windows
|
|
|
|
|
|
2019-06-20 19:19:27 +00:00
|
|
|
AVX-512 is disabled for Skylake-X by OpenSSL-1.1.1.
|
2018-11-10 01:54:00 +00:00
|
|
|
|
|
|
|
|
For use of AVX2,
|
|
|
|
|
|
2018-03-07 13:31:05 +00:00
|
|
|
* gas (GNU assembler) version 2.23 or higher
|
2018-11-08 06:43:45 +00:00
|
|
|
* Xcode version 5.0 or higher
|
2018-03-07 13:31:05 +00:00
|
|
|
* llvm version 3.3 or higher
|
|
|
|
|
* nasm version 2.10 or higher in Windows
|
|
|
|
|
|
2018-11-10 01:54:00 +00:00
|
|
|
Please refer to
|
2021-09-18 00:23:11 +00:00
|
|
|
<https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_ia32cap.html> for details.
|
2018-03-07 13:31:05 +00:00
|
|
|
|
2021-09-18 00:23:11 +00:00
|
|
|
If compiling without one of the above, use `configure` with the
|
2018-11-10 01:54:00 +00:00
|
|
|
`--openssl-no-asm` flag. Otherwise, `configure` will fail.
|
|
|
|
|
|
2019-03-17 11:31:29 +00:00
|
|
|
### Previous versions of this document
|
|
|
|
|
|
|
|
|
|
Supported platforms and toolchains change with each major version of Node.js.
|
|
|
|
|
This document is only valid for the current major version of Node.js.
|
|
|
|
|
Consult previous versions of this document for older versions of Node.js:
|
|
|
|
|
|
2024-05-06 12:30:21 +00:00
|
|
|
* [Node.js 21](https://github.com/nodejs/node/blob/v21.x/BUILDING.md)
|
|
|
|
|
* [Node.js 20](https://github.com/nodejs/node/blob/v20.x/BUILDING.md)
|
2023-05-03 11:33:23 +00:00
|
|
|
* [Node.js 18](https://github.com/nodejs/node/blob/v18.x/BUILDING.md)
|
2019-03-17 11:31:29 +00:00
|
|
|
|
2017-03-17 21:34:54 +00:00
|
|
|
## Building Node.js on supported platforms
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2024-08-04 22:35:41 +00:00
|
|
|
### Prerequisites
|
2019-06-28 08:01:02 +00:00
|
|
|
|
2024-08-04 22:35:41 +00:00
|
|
|
* Python support: the Node.js project supports Python >= 3.6 for building and testing.
|
|
|
|
|
* Memory: at least 8GB of RAM is typically required when compiling with 4 parallel jobs (e.g: `make -j4`)
|
2021-09-18 00:23:11 +00:00
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
### Unix and macOS
|
|
|
|
|
|
|
|
|
|
#### Unix prerequisites
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2024-08-05 13:25:44 +00:00
|
|
|
* `gcc` and `g++` >= 12.2 or newer
|
2016-03-09 23:41:52 +00:00
|
|
|
* GNU Make 3.81 or newer
|
2023-11-01 13:41:03 +00:00
|
|
|
* [A supported version of Python][Python versions]
|
2021-10-30 10:55:20 +00:00
|
|
|
* For test coverage, your Python installation must include pip.
|
2019-06-28 08:01:02 +00:00
|
|
|
|
|
|
|
|
Installation via Linux package manager can be achieved with:
|
|
|
|
|
|
2021-10-30 10:55:20 +00:00
|
|
|
* Ubuntu, Debian: `sudo apt-get install python3 g++ make python3-pip`
|
|
|
|
|
* Fedora: `sudo dnf install python3 gcc-c++ make python3-pip`
|
|
|
|
|
* CentOS and RHEL: `sudo yum install python3 gcc-c++ make python3-pip`
|
|
|
|
|
* OpenSUSE: `sudo zypper install python3 gcc-c++ make python3-pip`
|
|
|
|
|
* Arch Linux, Manjaro: `sudo pacman -S python gcc make python-pip`
|
2016-04-20 17:48:22 +00:00
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
FreeBSD and OpenBSD users may also need to install `libexecinfo`.
|
|
|
|
|
|
|
|
|
|
#### macOS prerequisites
|
|
|
|
|
|
2023-08-14 11:54:44 +00:00
|
|
|
* Xcode Command Line Tools >= 13 for macOS
|
2023-11-01 13:41:03 +00:00
|
|
|
* [A supported version of Python][Python versions]
|
2021-10-30 10:55:20 +00:00
|
|
|
* For test coverage, your Python installation must include pip.
|
2019-06-28 08:01:02 +00:00
|
|
|
|
|
|
|
|
macOS users can install the `Xcode Command Line Tools` by running
|
2017-05-28 10:57:35 +00:00
|
|
|
`xcode-select --install`. Alternatively, if you already have the full Xcode
|
|
|
|
|
installed, you can find them under the menu `Xcode -> Open Developer Tool ->
|
|
|
|
|
More Developer Tools...`. This step will install `clang`, `clang++`, and
|
|
|
|
|
`make`.
|
2016-12-03 06:56:01 +00:00
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
#### Building Node.js
|
|
|
|
|
|
2018-02-12 07:31:55 +00:00
|
|
|
If the path to your build directory contains a space, the build will likely
|
|
|
|
|
fail.
|
2017-07-18 19:03:43 +00:00
|
|
|
|
2016-09-03 03:23:21 +00:00
|
|
|
To build Node.js:
|
2016-04-20 17:48:22 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure
|
|
|
|
|
make -j4
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2022-02-25 03:20:41 +00:00
|
|
|
We can speed up the builds by using [Ninja](https://ninja-build.org/). For more
|
|
|
|
|
information, see
|
|
|
|
|
[Building Node.js with Ninja](doc/contributing/building-node-with-ninja.md).
|
|
|
|
|
|
2018-11-08 06:43:45 +00:00
|
|
|
The `-j4` option will cause `make` to run 4 simultaneous compilation jobs which
|
|
|
|
|
may reduce build time. For more information, see the
|
2021-10-30 22:40:34 +00:00
|
|
|
[GNU Make Documentation](https://www.gnu.org/software/make/manual/html_node/Parallel.html).
|
2016-12-01 16:47:46 +00:00
|
|
|
|
2019-06-20 19:19:27 +00:00
|
|
|
The above requires that `python` resolves to a supported version of
|
2019-03-17 11:31:29 +00:00
|
|
|
Python. See [Prerequisites](#prerequisites).
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2018-08-21 17:28:18 +00:00
|
|
|
After building, setting up [firewall rules](tools/macos-firewall.sh) can avoid
|
|
|
|
|
popups asking to accept incoming network connections when running tests.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
sudo ./tools/macos-firewall.sh
|
2018-08-21 17:28:18 +00:00
|
|
|
```
|
|
|
|
|
|
2020-10-19 18:27:32 +00:00
|
|
|
#### Installing Node.js
|
|
|
|
|
|
|
|
|
|
To install this version of Node.js into a system directory:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
[sudo] make install
|
|
|
|
|
```
|
|
|
|
|
|
2021-02-06 16:14:25 +00:00
|
|
|
#### Running tests
|
2018-01-09 11:34:11 +00:00
|
|
|
|
|
|
|
|
To verify the build:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
make test-only
|
2018-01-09 11:34:11 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
At this point, you are ready to make code changes and re-run the tests.
|
|
|
|
|
|
2021-11-25 21:13:17 +00:00
|
|
|
If you are running tests before submitting a pull request, use:
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
make -j4 test
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2018-04-17 00:46:25 +00:00
|
|
|
`make -j4 test` does a full check on the codebase, including running linters and
|
2018-01-09 11:34:11 +00:00
|
|
|
documentation tests.
|
|
|
|
|
|
2021-11-25 21:13:17 +00:00
|
|
|
To run the linter without running tests, use
|
2019-07-06 18:08:01 +00:00
|
|
|
`make lint`/`vcbuild lint`. It will lint JavaScript, C++, and Markdown files.
|
2018-10-29 05:59:56 +00:00
|
|
|
|
2024-04-10 23:45:36 +00:00
|
|
|
To fix auto fixable JavaScript linting errors, use `make lint-js-fix`.
|
|
|
|
|
|
2019-05-04 11:45:48 +00:00
|
|
|
If you are updating tests and want to run tests in a single test file
|
|
|
|
|
(e.g. `test/parallel/test-stream2-transform.js`):
|
2018-10-12 18:06:32 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
tools/test.py test/parallel/test-stream2-transform.js
|
2018-10-12 18:06:32 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You can execute the entire suite of tests for a given subsystem
|
|
|
|
|
by providing the name of a subsystem:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
tools/test.py child-process
|
2021-11-25 21:13:17 +00:00
|
|
|
```
|
|
|
|
|
|
2022-04-21 18:14:25 +00:00
|
|
|
You can also execute the tests in a test suite directory
|
|
|
|
|
(such as `test/message`):
|
2021-11-25 21:13:17 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
tools/test.py test/message
|
2018-10-12 18:06:32 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If you want to check the other options, please refer to the help by using
|
2018-10-20 01:33:00 +00:00
|
|
|
the `--help` option:
|
2018-10-12 18:06:32 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
tools/test.py --help
|
2018-10-12 18:06:32 +00:00
|
|
|
```
|
|
|
|
|
|
2023-02-06 07:50:07 +00:00
|
|
|
> Note: On Windows you should use `python3` executable.
|
|
|
|
|
> Example: `python3 tools/test.py test/message`
|
|
|
|
|
|
2018-10-12 18:06:32 +00:00
|
|
|
You can usually run tests directly with node:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./node test/parallel/test-stream2-transform.js
|
2018-10-12 18:06:32 +00:00
|
|
|
```
|
|
|
|
|
|
2023-02-06 07:50:07 +00:00
|
|
|
> Info: `./node` points to your local Node.js build.
|
|
|
|
|
|
2018-10-29 05:59:56 +00:00
|
|
|
Remember to recompile with `make -j4` in between test runs if you change code in
|
|
|
|
|
the `lib` or `src` directories.
|
|
|
|
|
|
2018-11-14 22:53:59 +00:00
|
|
|
The tests attempt to detect support for IPv6 and exclude IPv6 tests if
|
|
|
|
|
appropriate. If your main interface has IPv6 addresses, then your
|
|
|
|
|
loopback interface must also have '::1' enabled. For some default installations
|
2021-11-25 21:13:17 +00:00
|
|
|
on Ubuntu, that does not seem to be the case. To enable '::1' on the
|
2018-11-14 22:53:59 +00:00
|
|
|
loopback interface on Ubuntu:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
sudo sysctl -w net.ipv6.conf.lo.disable_ipv6=0
|
|
|
|
|
```
|
|
|
|
|
|
2018-11-01 05:46:29 +00:00
|
|
|
You can use
|
|
|
|
|
[node-code-ide-configs](https://github.com/nodejs/node-code-ide-configs)
|
2021-11-25 21:13:17 +00:00
|
|
|
to run/debug tests if your IDE configs are present.
|
2018-11-01 05:46:29 +00:00
|
|
|
|
2021-02-06 16:14:25 +00:00
|
|
|
#### Running coverage
|
2017-10-06 17:42:35 +00:00
|
|
|
|
2018-10-29 05:59:56 +00:00
|
|
|
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:
|
2017-09-04 22:10:05 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --coverage
|
|
|
|
|
make coverage
|
2017-09-04 22:10:05 +00:00
|
|
|
```
|
|
|
|
|
|
2018-10-29 05:59:56 +00:00
|
|
|
A detailed coverage report will be written to `coverage/index.html` for
|
2020-10-23 02:56:28 +00:00
|
|
|
JavaScript coverage and to `coverage/cxxcoverage.html` for C++ coverage.
|
2018-10-29 05:59:56 +00:00
|
|
|
|
2020-10-23 02:56:28 +00:00
|
|
|
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:
|
2018-10-29 05:59:56 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
make coverage-run-js
|
2018-10-29 05:59:56 +00:00
|
|
|
```
|
|
|
|
|
|
2020-10-26 10:35:56 +00:00
|
|
|
If you are updating tests and want to collect coverage for a single test file
|
2020-10-23 02:56:28 +00:00
|
|
|
(e.g. `test/parallel/test-stream2-transform.js`):
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
make coverage-clean
|
|
|
|
|
NODE_V8_COVERAGE=coverage/tmp tools/test.py test/parallel/test-stream2-transform.js
|
|
|
|
|
make coverage-report-js
|
2020-10-23 02:56:28 +00:00
|
|
|
```
|
2017-09-04 22:10:05 +00:00
|
|
|
|
2020-10-23 02:56:28 +00:00
|
|
|
You can collect coverage for the entire suite of tests for a given subsystem
|
|
|
|
|
by providing the name of a subsystem:
|
2019-01-18 21:46:49 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
make coverage-clean
|
|
|
|
|
NODE_V8_COVERAGE=coverage/tmp tools/test.py --mode=release child-process
|
|
|
|
|
make coverage-report-js
|
2019-01-18 21:46:49 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The `make coverage` command downloads some tools to the project root directory.
|
|
|
|
|
To clean up after generating the coverage reports:
|
2017-09-04 22:10:05 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
make coverage-clean
|
2017-09-04 22:10:05 +00:00
|
|
|
```
|
|
|
|
|
|
2018-01-09 11:34:11 +00:00
|
|
|
#### Building the documentation
|
|
|
|
|
|
2016-03-09 23:41:52 +00:00
|
|
|
To build the documentation:
|
|
|
|
|
|
2015-11-18 22:40:03 +00:00
|
|
|
This will build Node.js first (if necessary) and then use it to build the docs:
|
|
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
```bash
|
|
|
|
|
make doc
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2017-08-18 18:36:33 +00:00
|
|
|
If you have an existing Node.js build, you can build just the docs with:
|
2015-11-18 22:40:03 +00:00
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
```bash
|
|
|
|
|
NODE=/path/to/node make doc-only
|
2015-11-18 22:40:03 +00:00
|
|
|
```
|
|
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
To read the man page:
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
```bash
|
|
|
|
|
man doc/node.1
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
If you prefer to read the full documentation in a browser, run the following.
|
2018-03-13 15:12:40 +00:00
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
```bash
|
|
|
|
|
make docserve
|
2018-03-13 15:12:40 +00:00
|
|
|
```
|
|
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
This will spin up a static file server and provide a URL to where you may browse
|
|
|
|
|
the documentation locally.
|
|
|
|
|
|
|
|
|
|
If you're comfortable viewing the documentation using the program your operating
|
|
|
|
|
system has associated with the default web browser, run the following.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
make docopen
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This will open a file URL to a one-page version of all the browsable HTML
|
|
|
|
|
documents using the default browser.
|
2018-03-13 15:12:40 +00:00
|
|
|
|
2023-11-27 09:03:27 +00:00
|
|
|
```bash
|
|
|
|
|
make docclean
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This will clean previously built doc.
|
|
|
|
|
|
2016-03-09 23:41:52 +00:00
|
|
|
To test if Node.js was built correctly:
|
|
|
|
|
|
2020-08-30 12:52:17 +00:00
|
|
|
```bash
|
|
|
|
|
./node -e "console.log('Hello from Node.js ' + process.version)"
|
2016-09-03 03:23:21 +00:00
|
|
|
```
|
|
|
|
|
|
2018-08-24 18:52:18 +00:00
|
|
|
#### Building a debug build
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --debug
|
|
|
|
|
make -j4
|
2018-08-24 18:52:18 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`make` with `./configure --debug` generates two binaries, the regular release
|
|
|
|
|
one in `out/Release/node` and a debug binary in `out/Debug/node`, only the
|
|
|
|
|
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:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
make install PREFIX=/opt/node-debug/
|
|
|
|
|
cp -a -f out/Debug/node /opt/node-debug/node
|
2018-08-24 18:52:18 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
When using the debug binary, core dumps will be generated in case of crashes.
|
|
|
|
|
These core dumps are useful for debugging when provided with the
|
|
|
|
|
corresponding original debug binary and system information.
|
|
|
|
|
|
|
|
|
|
Reading the core dump requires `gdb` built on the same platform the core dump
|
2018-10-30 17:31:18 +00:00
|
|
|
was captured on (i.e. 64-bit `gdb` for `node` built on a 64-bit system, Linux
|
2018-08-24 18:52:18 +00:00
|
|
|
`gdb` for `node` built on Linux) otherwise you will get errors like
|
|
|
|
|
`not in executable format: File format not recognized`.
|
|
|
|
|
|
|
|
|
|
Example of generating a backtrace from the core dump:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
2018-08-24 18:52:18 +00:00
|
|
|
$ gdb /opt/node-debug/node core.node.8.1535359906
|
2023-05-19 22:14:03 +00:00
|
|
|
(gdb) backtrace
|
2018-08-24 18:52:18 +00:00
|
|
|
```
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-04-23 08:21:51 +00:00
|
|
|
#### Building an ASan build
|
2020-03-23 12:07:29 +00:00
|
|
|
|
2023-04-23 08:21:51 +00:00
|
|
|
[ASan](https://github.com/google/sanitizers) can help detect various memory
|
|
|
|
|
related bugs. ASan builds are currently only supported on linux.
|
2020-03-23 12:07:29 +00:00
|
|
|
If you want to check it on Windows or macOS or you want a consistent toolchain
|
|
|
|
|
on Linux, you can try [Docker](https://www.docker.com/products/docker-desktop)
|
2021-09-18 00:23:11 +00:00
|
|
|
(using an image like `gengjiawen/node-build:2020-02-14`).
|
2020-03-23 12:07:29 +00:00
|
|
|
|
|
|
|
|
The `--debug` is not necessary and will slow down build and testing, but it can
|
2023-04-23 08:21:51 +00:00
|
|
|
show clear stacktrace if ASan hits an issue.
|
2020-03-23 12:07:29 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --debug --enable-asan && make -j4
|
|
|
|
|
make test-only
|
2020-03-23 12:07:29 +00:00
|
|
|
```
|
|
|
|
|
|
2020-12-09 12:29:15 +00:00
|
|
|
#### Speeding up frequent rebuilds when developing
|
|
|
|
|
|
2024-03-25 15:40:09 +00:00
|
|
|
Tips: The `ccache` utility is widely used and should generally work fine.
|
|
|
|
|
If you encounter any difficulties, consider disabling `mold` as a
|
|
|
|
|
troubleshooting step.
|
|
|
|
|
|
|
|
|
|
If you plan to frequently rebuild Node.js, especially if using several
|
2024-03-28 14:10:49 +00:00
|
|
|
branches, installing `ccache` can help to greatly reduce build
|
2024-03-25 15:40:09 +00:00
|
|
|
times. Set up with:
|
2021-09-18 00:23:11 +00:00
|
|
|
|
2021-10-21 17:06:49 +00:00
|
|
|
On GNU/Linux:
|
|
|
|
|
|
2024-03-28 14:10:49 +00:00
|
|
|
Tips: `mold` can speed up the link process, which can't be cached, you may
|
|
|
|
|
need to install the latest version but not the apt version.
|
|
|
|
|
|
2021-10-21 18:06:05 +00:00
|
|
|
```bash
|
2024-03-25 15:40:09 +00:00
|
|
|
sudo apt install ccache mold # for Debian/Ubuntu, included in most Linux distros
|
|
|
|
|
export CC="ccache gcc" # add to your .profile
|
|
|
|
|
export CXX="ccache g++" # add to your .profile
|
|
|
|
|
export LDFLAGS="-fuse-ld=mold" # add to your .profile
|
2020-12-09 12:29:15 +00:00
|
|
|
```
|
2021-09-18 00:23:11 +00:00
|
|
|
|
2024-03-28 14:10:49 +00:00
|
|
|
Refs:
|
|
|
|
|
|
|
|
|
|
1. <https://ccache.dev/performance.html>
|
|
|
|
|
2. <https://github.com/rui314/mold>
|
|
|
|
|
|
2021-10-21 17:06:49 +00:00
|
|
|
On macOS:
|
|
|
|
|
|
2021-10-21 18:06:05 +00:00
|
|
|
```bash
|
2024-03-28 14:10:49 +00:00
|
|
|
brew install ccache # see https://brew.sh
|
2024-03-25 15:40:09 +00:00
|
|
|
export CC="ccache cc" # add to ~/.zshrc or other shell config file
|
|
|
|
|
export CXX="ccache c++" # add to ~/.zshrc or other shell config file
|
2021-10-21 17:06:49 +00:00
|
|
|
```
|
|
|
|
|
|
2023-10-15 10:55:36 +00:00
|
|
|
This will allow for near-instantaneous rebuilds when switching branches back
|
|
|
|
|
and forth that were built with cache.
|
2020-12-09 12:29:15 +00:00
|
|
|
|
|
|
|
|
When modifying only the JS layer in `lib`, it is possible to externally load it
|
|
|
|
|
without modifying the executable:
|
2021-09-18 00:23:11 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --node-builtin-modules-path "$(pwd)"
|
2020-12-09 12:29:15 +00:00
|
|
|
```
|
2021-09-18 00:23:11 +00:00
|
|
|
|
2020-12-09 12:29:15 +00:00
|
|
|
The resulting binary won't include any JS files and will try to load them from
|
|
|
|
|
the specified directory. The JS debugger of Visual Studio Code supports this
|
|
|
|
|
configuration since the November 2020 version and allows for setting
|
|
|
|
|
breakpoints.
|
|
|
|
|
|
2020-01-28 00:58:07 +00:00
|
|
|
#### Troubleshooting Unix and macOS builds
|
|
|
|
|
|
|
|
|
|
Stale builds can sometimes result in `file not found` errors while building.
|
|
|
|
|
This and some other problems can be resolved with `make distclean`. The
|
|
|
|
|
`distclean` recipe aggressively removes build artifacts. You will need to
|
|
|
|
|
build again (`make -j4`). Since all build artifacts have been removed, this
|
|
|
|
|
rebuild may take a lot more time than previous builds. Additionally,
|
|
|
|
|
`distclean` removes the file that stores the results of `./configure`. If you
|
|
|
|
|
ran `./configure` with non-default options (such as `--debug`), you will need
|
|
|
|
|
to run it again before invoking `make -j4`.
|
|
|
|
|
|
2024-07-31 09:42:02 +00:00
|
|
|
If you received the error `nodejs g++ fatal error compilation terminated cc1plus`
|
|
|
|
|
during compilation, this is likely a memory issue and you should either provide
|
|
|
|
|
more RAM or create swap space to accommodate toolchain requirements or reduce
|
|
|
|
|
the number of parallel build tasks (`-j<n>`).
|
|
|
|
|
|
2016-03-09 23:41:52 +00:00
|
|
|
### Windows
|
|
|
|
|
|
2024-04-03 23:48:55 +00:00
|
|
|
#### Tips
|
|
|
|
|
|
|
|
|
|
You may need disable vcpkg integration if you got link error about symbol
|
|
|
|
|
redefine related to zlib.lib(zlib1.dll), even you never install it by hand,
|
|
|
|
|
as vcpkg is part of CLion and Visual Studio now.
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
# find your vcpkg
|
|
|
|
|
# double check vcpkg install the related file
|
|
|
|
|
vcpkg owns zlib.lib
|
|
|
|
|
vcpkg owns zlib1.dll
|
|
|
|
|
vcpkg integrate remove
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Refs: #24448, <https://github.com/microsoft/vcpkg/issues/37518>, [vcpkg](https://github.com/microsoft/vcpkg/)
|
|
|
|
|
|
2024-08-04 22:35:41 +00:00
|
|
|
#### Windows Prerequisites
|
2019-06-28 08:01:02 +00:00
|
|
|
|
|
|
|
|
##### Option 1: Manual install
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-11-01 13:41:03 +00:00
|
|
|
* The current [version of Python][Python versions] from the
|
|
|
|
|
[Microsoft Store](https://apps.microsoft.com/store/search?publisher=Python+Software+Foundation)
|
2017-11-07 17:36:09 +00:00
|
|
|
* The "Desktop development with C++" workload from
|
2024-06-06 09:05:29 +00:00
|
|
|
[Visual Studio 2022 (17.6 or newer)](https://visualstudio.microsoft.com/downloads/)
|
|
|
|
|
or the "C++ build tools" workload from the
|
2023-10-01 14:22:58 +00:00
|
|
|
[Build Tools](https://aka.ms/vs/17/release/vs_buildtools.exe),
|
2020-08-20 02:16:44 +00:00
|
|
|
with the default optional components
|
2016-03-09 23:41:52 +00:00
|
|
|
* Basic Unix tools required for some tests,
|
2019-09-04 06:39:05 +00:00
|
|
|
[Git for Windows](https://git-scm.com/download/win) includes Git Bash
|
2016-03-09 23:41:52 +00:00
|
|
|
and tools which can be included in the global `PATH`.
|
2019-09-04 06:39:05 +00:00
|
|
|
* The [NetWide Assembler](https://www.nasm.us/), for OpenSSL assembler modules.
|
2018-04-11 12:11:36 +00:00
|
|
|
If not installed in the default location, it needs to be manually added
|
2019-01-03 00:44:23 +00:00
|
|
|
to `PATH`. A build with the `openssl-no-asm` option does not need this, nor
|
|
|
|
|
does a build targeting ARM64 Windows.
|
2019-06-28 08:01:02 +00:00
|
|
|
|
|
|
|
|
Optional requirements to build the MSI installer package:
|
|
|
|
|
|
2023-10-01 14:22:58 +00:00
|
|
|
* The .NET SDK component from [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)
|
|
|
|
|
* This component can be installed via the Visual Studio Installer Application
|
2019-06-28 08:01:02 +00:00
|
|
|
|
2024-06-11 17:37:26 +00:00
|
|
|
Optional requirements for compiling for Windows on ARM (ARM64):
|
2019-06-28 08:01:02 +00:00
|
|
|
|
2023-10-01 14:22:58 +00:00
|
|
|
* Visual Studio 17.6.0 or newer
|
2019-06-28 08:01:02 +00:00
|
|
|
* Visual Studio optional components
|
|
|
|
|
* Visual C++ compilers and libraries for ARM64
|
|
|
|
|
* Visual C++ ATL for ARM64
|
|
|
|
|
* Windows 10 SDK 10.0.17763.0 or newer
|
|
|
|
|
|
2024-06-11 17:37:26 +00:00
|
|
|
Optional requirements for compiling with ClangCL:
|
|
|
|
|
|
|
|
|
|
* Visual Studio optional components
|
|
|
|
|
* C++ Clang Compiler for Windows
|
|
|
|
|
* MSBuild support for LLVM toolset
|
|
|
|
|
|
|
|
|
|
NOTE: Currently we only support compiling with Clang that comes from Visual Studio.
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
##### Option 2: Automated install with Boxstarter
|
|
|
|
|
|
2019-09-04 06:39:05 +00:00
|
|
|
A [Boxstarter](https://boxstarter.org/) script can be used for easy setup of
|
2019-06-28 08:01:02 +00:00
|
|
|
Windows systems with all the required prerequisites for Node.js development.
|
|
|
|
|
This script will install the following [Chocolatey](https://chocolatey.org/)
|
|
|
|
|
packages:
|
|
|
|
|
|
|
|
|
|
* [Git for Windows](https://chocolatey.org/packages/git) with the `git` and
|
2020-08-20 02:16:44 +00:00
|
|
|
Unix tools added to the `PATH`
|
2020-12-30 14:09:52 +00:00
|
|
|
* [Python 3.x](https://chocolatey.org/packages/python)
|
2023-10-01 14:22:58 +00:00
|
|
|
* [Visual Studio 2022 Build Tools](https://chocolatey.org/packages/visualstudio2022buildtools)
|
|
|
|
|
with [Visual C++ workload](https://chocolatey.org/packages/visualstudio2022-workload-vctools)
|
2019-06-28 08:01:02 +00:00
|
|
|
* [NetWide Assembler](https://chocolatey.org/packages/nasm)
|
|
|
|
|
|
|
|
|
|
To install Node.js prerequisites using
|
2022-06-02 16:34:01 +00:00
|
|
|
[Boxstarter WebLauncher](https://boxstarter.org/weblauncher), open
|
2021-02-23 19:59:24 +00:00
|
|
|
<https://boxstarter.org/package/nr/url?https://raw.githubusercontent.com/nodejs/node/HEAD/tools/bootstrap/windows_boxstarter>
|
2024-04-10 23:37:19 +00:00
|
|
|
with Edge browser on the target machine.
|
2019-06-28 08:01:02 +00:00
|
|
|
|
2023-10-01 14:22:58 +00:00
|
|
|
Alternatively, you can use PowerShell. Run those commands from
|
|
|
|
|
an elevated (Administrator) PowerShell terminal:
|
2019-06-28 08:01:02 +00:00
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
Set-ExecutionPolicy Unrestricted -Force
|
2019-09-04 06:39:05 +00:00
|
|
|
iex ((New-Object System.Net.WebClient).DownloadString('https://boxstarter.org/bootstrapper.ps1'))
|
2019-06-28 08:01:02 +00:00
|
|
|
get-boxstarter -Force
|
2021-02-23 19:59:24 +00:00
|
|
|
Install-BoxstarterPackage https://raw.githubusercontent.com/nodejs/node/HEAD/tools/bootstrap/windows_boxstarter -DisableReboots
|
2022-09-13 15:38:06 +00:00
|
|
|
refreshenv
|
2019-06-28 08:01:02 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The entire installation using Boxstarter will take up approximately 10 GB of
|
|
|
|
|
disk space.
|
|
|
|
|
|
|
|
|
|
#### Building Node.js
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-10-01 14:22:58 +00:00
|
|
|
* Remember to first clone the Node.js repository with the Git command
|
|
|
|
|
and head to the directory that Git created; If you haven't already
|
|
|
|
|
```powershell
|
|
|
|
|
git clone https://github.com/nodejs/node.git
|
|
|
|
|
cd node
|
|
|
|
|
```
|
2024-05-25 19:00:10 +00:00
|
|
|
|
|
|
|
|
> \[!TIP]
|
|
|
|
|
> If you are building from a Windows machine, symlinks are disabled by default, and can be enabled by cloning
|
|
|
|
|
> with the `-c core.symlinks=true` flag.
|
|
|
|
|
>
|
|
|
|
|
> ```powershell
|
|
|
|
|
> git clone -c core.symlinks=true <repository_url>
|
|
|
|
|
> ```
|
|
|
|
|
|
2023-10-01 14:22:58 +00:00
|
|
|
* If the path to your build directory contains a space or a non-ASCII character,
|
|
|
|
|
the build will likely fail
|
|
|
|
|
|
|
|
|
|
To start the build process:
|
2017-07-18 19:03:43 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
.\vcbuild
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
To run the tests:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
.\vcbuild test
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
To test if Node.js was built correctly:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
Release\node -e "console.log('Hello from Node.js', process.version)"
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2022-08-12 10:29:23 +00:00
|
|
|
### Android
|
2016-04-04 17:48:34 +00:00
|
|
|
|
2018-10-12 00:15:15 +00:00
|
|
|
Android is not a supported platform. Patches to improve the Android build are
|
|
|
|
|
welcome. There is no testing on Android in the current continuous integration
|
|
|
|
|
environment. The participation of people dedicated and determined to improve
|
|
|
|
|
Android building, testing, and support is encouraged.
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2017-04-01 08:07:31 +00:00
|
|
|
Be sure you have downloaded and extracted
|
2022-08-12 10:29:23 +00:00
|
|
|
[Android NDK](https://developer.android.com/ndk) before in
|
2017-04-01 08:07:31 +00:00
|
|
|
a folder. Then run:
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./android-configure <path to the Android NDK> <Android SDK version> <target architecture>
|
|
|
|
|
make -j4
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2022-08-12 10:29:23 +00:00
|
|
|
The Android SDK version should be at least 24 (Android 7.0) and the target
|
|
|
|
|
architecture supports \[arm, arm64/aarch64, x86, x86\_64].
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
## `Intl` (ECMA-402) support
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2021-05-03 09:15:35 +00:00
|
|
|
[Intl](https://github.com/nodejs/node/blob/HEAD/doc/api/intl.md) support is
|
2019-09-30 18:17:49 +00:00
|
|
|
enabled by default.
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2019-09-30 18:17:49 +00:00
|
|
|
### Build with full ICU support (all locales supported by ICU)
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2019-09-30 18:17:49 +00:00
|
|
|
This is the default option.
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2019-09-30 18:17:49 +00:00
|
|
|
#### Unix/macOS
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --with-intl=full-icu
|
2019-09-30 18:17:49 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### Windows
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
.\vcbuild full-icu
|
2019-09-30 18:17:49 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Trimmed: `small-icu` (English only) support
|
|
|
|
|
|
2021-09-18 00:23:11 +00:00
|
|
|
In this configuration, only English data is included, but
|
2023-10-01 14:22:58 +00:00
|
|
|
the full `Intl` (ECMA-402) APIs. It does not need to download
|
2019-09-30 18:17:49 +00:00
|
|
|
any dependencies to function. You can add full data at runtime.
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
#### Unix/macOS
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --with-intl=small-icu
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
#### Windows
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
.\vcbuild small-icu
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
### Building without Intl support
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2016-04-09 02:03:24 +00:00
|
|
|
The `Intl` object will not be available, nor some other APIs such as
|
|
|
|
|
`String.normalize`.
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
#### Unix/macOS
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --without-intl
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
#### Windows
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
.\vcbuild without-intl
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
### Use existing installed ICU (Unix/macOS only)
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2018-10-30 17:31:18 +00:00
|
|
|
If you are cross-compiling, your `pkg-config` must be able to supply a path
|
2016-03-09 23:41:52 +00:00
|
|
|
that works for both your host and target environments.
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
### Build with a specific ICU
|
2016-03-09 23:41:52 +00:00
|
|
|
|
|
|
|
|
You can find other ICU releases at
|
2020-05-28 14:03:53 +00:00
|
|
|
[the ICU homepage](http://site.icu-project.org/download).
|
2016-03-09 23:41:52 +00:00
|
|
|
Download the file named something like `icu4c-**##.#**-src.tgz` (or
|
|
|
|
|
`.zip`).
|
|
|
|
|
|
2018-06-08 20:57:32 +00:00
|
|
|
To check the minimum recommended ICU, run `./configure --help` and see
|
|
|
|
|
the help for the `--with-icu-source` option. A warning will be printed
|
|
|
|
|
during configuration if the ICU version is too old.
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
#### Unix/macOS
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2016-07-14 09:55:30 +00:00
|
|
|
From an already-unpacked ICU:
|
2019-08-29 13:28:03 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu
|
2016-07-14 09:55:30 +00:00
|
|
|
```
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2016-07-14 09:55:30 +00:00
|
|
|
From a local ICU tarball:
|
2019-08-29 13:28:03 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
|
2016-07-14 09:55:30 +00:00
|
|
|
```
|
2016-03-09 23:41:52 +00:00
|
|
|
|
2016-07-14 09:55:30 +00:00
|
|
|
From a tarball URL:
|
2019-08-29 13:28:03 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2019-06-28 08:01:02 +00:00
|
|
|
#### Windows
|
2016-03-09 23:41:52 +00:00
|
|
|
|
|
|
|
|
First unpack latest ICU to `deps/icu`
|
2020-05-28 14:03:53 +00:00
|
|
|
[icu4c-**##.#**-src.tgz](http://site.icu-project.org/download) (or `.zip`)
|
2016-03-09 23:41:52 +00:00
|
|
|
as `deps/icu` (You'll have: `deps/icu/source/...`)
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
.\vcbuild full-icu
|
2016-03-09 23:41:52 +00:00
|
|
|
```
|
|
|
|
|
|
2022-05-14 08:04:48 +00:00
|
|
|
### Configure OpenSSL appname
|
|
|
|
|
|
|
|
|
|
Node.js can use an OpenSSL configuration file by specifying the environment
|
|
|
|
|
variable `OPENSSL_CONF`, or using the command line option `--openssl-conf`, and
|
|
|
|
|
if none of those are specified will default to reading the default OpenSSL
|
|
|
|
|
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:
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --openssl-conf-name=<some_conf_name>
|
2022-05-14 08:04:48 +00:00
|
|
|
```
|
|
|
|
|
|
2016-03-09 23:41:52 +00:00
|
|
|
## Building Node.js with FIPS-compliant OpenSSL
|
|
|
|
|
|
2023-05-30 11:40:25 +00:00
|
|
|
Node.js supports FIPS when statically or dynamically linked with OpenSSL 3 via
|
|
|
|
|
[OpenSSL's provider model](https://www.openssl.org/docs/man3.0/man7/crypto.html#OPENSSL-PROVIDERS).
|
|
|
|
|
It is not necessary to rebuild Node.js to enable support for FIPS.
|
2021-04-26 03:52:16 +00:00
|
|
|
|
2023-05-30 11:40:25 +00:00
|
|
|
See [FIPS mode](./doc/api/crypto.md#fips-mode) for more information on how to
|
|
|
|
|
enable FIPS support in Node.js.
|
2017-12-16 05:19:16 +00:00
|
|
|
|
|
|
|
|
## Building Node.js with external core modules
|
|
|
|
|
|
|
|
|
|
It is possible to specify one or more JavaScript text files to be bundled in
|
2018-10-30 17:31:18 +00:00
|
|
|
the binary as built-in modules when building Node.js.
|
2017-12-16 05:19:16 +00:00
|
|
|
|
2018-05-30 10:21:20 +00:00
|
|
|
### Unix/macOS
|
2017-12-16 05:19:16 +00:00
|
|
|
|
|
|
|
|
This command will make `/root/myModule.js` available via
|
|
|
|
|
`require('/root/myModule')` and `./myModule2.js` available via
|
|
|
|
|
`require('myModule2')`.
|
|
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```bash
|
|
|
|
|
./configure --link-module '/root/myModule.js' --link-module './myModule2.js'
|
2017-12-16 05:19:16 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Windows
|
|
|
|
|
|
2018-05-16 11:59:48 +00:00
|
|
|
To make `./myModule.js` available via `require('myModule')` and
|
|
|
|
|
`./myModule2.js` available via `require('myModule2')`:
|
2017-12-16 05:19:16 +00:00
|
|
|
|
2023-05-19 22:14:03 +00:00
|
|
|
```powershell
|
|
|
|
|
.\vcbuild link-module './myModule.js' link-module './myModule2.js'
|
2017-12-16 05:19:16 +00:00
|
|
|
```
|
2018-08-10 16:10:24 +00:00
|
|
|
|
2022-08-24 02:41:29 +00:00
|
|
|
## Building to use shared dependencies at runtime
|
|
|
|
|
|
|
|
|
|
By default Node.js is built so that all dependencies are bundled into
|
|
|
|
|
the Node.js binary itself. This provides a single binary that includes
|
|
|
|
|
the correct versions of all dependencies on which it depends.
|
|
|
|
|
|
|
|
|
|
Some Node.js distributions, however, prefer to manage dependencies.
|
|
|
|
|
A number of `configure` options are provided to support this use case.
|
|
|
|
|
|
|
|
|
|
* For dependencies with native code, the first set of options allow
|
|
|
|
|
Node.js to be built so that it uses a shared library
|
|
|
|
|
at runtime instead of building and including the dependency
|
|
|
|
|
in the Node.js binary itself. These options are in the
|
|
|
|
|
`Shared libraries` section of the `configure` help
|
|
|
|
|
(run `./configure --help` to get the complete list).
|
|
|
|
|
They provide the ability to enable the use of a shared library,
|
|
|
|
|
to set the name of the shared library, and to set the paths that
|
|
|
|
|
contain the include and shared library files.
|
|
|
|
|
|
|
|
|
|
* For dependencies with JavaScript code (including WASM), the second
|
|
|
|
|
set of options allow the Node.js binary to be built so that it loads
|
|
|
|
|
the JavaScript for dependencies at runtime instead of being built into
|
|
|
|
|
the Node.js binary itself. These options are in the `Shared builtins`
|
|
|
|
|
section of the `configure` help
|
|
|
|
|
(run `./configure --help` to get the complete list). They
|
|
|
|
|
provide the ability to set the path to an external JavaScript file
|
|
|
|
|
for the dependency to be used at runtime.
|
|
|
|
|
|
|
|
|
|
It is the responsibility of any distribution
|
|
|
|
|
shipping with these options to:
|
|
|
|
|
|
|
|
|
|
* ensure that the shared dependencies available at runtime
|
|
|
|
|
match what is expected by the Node.js binary. A
|
|
|
|
|
mismatch may result in crashes or unexpected behavior.
|
|
|
|
|
* fully test that Node.js operates as expected with the
|
|
|
|
|
external dependencies. There may be little or no test coverage
|
|
|
|
|
within the Node.js project CI for these non-default options.
|
|
|
|
|
|
2018-08-10 16:10:24 +00:00
|
|
|
## Note for downstream distributors of Node.js
|
|
|
|
|
|
2018-11-06 02:40:03 +00:00
|
|
|
The Node.js ecosystem is reliant on ABI compatibility within a major release.
|
|
|
|
|
To maintain ABI compatibility it is required that distributed builds of Node.js
|
|
|
|
|
be built against the same version of dependencies, or similar versions that do
|
|
|
|
|
not break their ABI compatibility, as those released by Node.js for any given
|
|
|
|
|
`NODE_MODULE_VERSION` (located in `src/node_version.h`).
|
|
|
|
|
|
|
|
|
|
When Node.js is built (with an intention to distribute) with an ABI
|
|
|
|
|
incompatible with the official Node.js builds (e.g. using a ABI incompatible
|
|
|
|
|
version of a dependency), please reserve and use a custom `NODE_MODULE_VERSION`
|
|
|
|
|
by opening a pull request against the registry available at
|
2021-05-03 09:15:35 +00:00
|
|
|
<https://github.com/nodejs/node/blob/HEAD/doc/abi_version_registry.json>.
|
2023-11-01 13:41:03 +00:00
|
|
|
|
|
|
|
|
[Python versions]: https://devguide.python.org/versions/
|
