1# Building Node.js 2 3Depending on what platform or features you need, the build process may 4differ. After you've built a binary, running the 5test suite to confirm that the binary works as intended is a good next step. 6 7If you can reproduce a test failure, search for it in the 8[Node.js issue tracker](https://github.com/nodejs/node/issues) or 9file a new issue. 10 11## Table of Contents 12 13* [Supported platforms](#supported-platforms) 14 * [Input](#input) 15 * [Strategy](#strategy) 16 * [Supported platforms](#supported-platforms-1) 17 * [Supported toolchains](#supported-toolchains) 18 * [Unix](#unix) 19 * [AIX](#aix) 20 * [Windows](#windows) 21 * [OpenSSL asm support](#openssl-asm-support) 22* [Building Node.js on supported platforms](#building-nodejs-on-supported-platforms) 23 * [Unix/macOS](#unixmacos) 24 * [Prerequisites](#prerequisites) 25 * [Building Node.js](#building-nodejs-1) 26 * [Running Tests](#running-tests) 27 * [Building the documentation](#building-the-documentation) 28 * [Building a debug build](#building-a-debug-build) 29 * [Windows](#windows-1) 30 * [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os) 31 * [`Intl` (ECMA-402) support](#intl-ecma-402-support) 32 * [Default: `small-icu` (English only) support](#default-small-icu-english-only-support) 33 * [Build with full ICU support (all locales supported by ICU)](#build-with-full-icu-support-all-locales-supported-by-icu) 34 * [Unix/macOS](#unixmacos-1) 35 * [Windows](#windows-2) 36 * [Building without Intl support](#building-without-intl-support) 37 * [Unix/macOS](#unixmacos-2) 38 * [Windows](#windows-3) 39 * [Use existing installed ICU (Unix/macOS only)](#use-existing-installed-icu-unixmacos-only) 40 * [Build with a specific ICU](#build-with-a-specific-icu) 41 * [Unix/macOS](#unixmacos-3) 42 * [Windows](#windows-4) 43* [Building Node.js with FIPS-compliant OpenSSL](#building-nodejs-with-fips-compliant-openssl) 44* [Building Node.js with external core modules](#building-nodejs-with-external-core-modules) 45 * [Unix/macOS](#unixmacos-4) 46 * [Windows](#windows-5) 47 48## Supported platforms 49 50This list of supported platforms is current as of the branch/release to 51which it belongs. 52 53### Input 54 55Node.js relies on V8 and libuv. We adopt a subset of their supported platforms. 56 57### Strategy 58 59There are three support tiers: 60 61* **Tier 1**: Full test coverage and maintenance by the Node.js core team and 62 the broader community. 63* **Tier 2**: Full test coverage. Limited maintenance, often provided by the 64 vendor of the platform. 65* **Experimental**: May not compile or test suite may not pass. 66 These are often approaching Tier 2 support but are not quite ready. 67 There is at least one individual providing maintenance. 68 69### Supported platforms 70 71The community does not build or test against end-of-life distributions (EoL). 72For production applications, run Node.js on supported platforms only. 73 74| System | Support type | Version | Architectures | Notes | 75|--------------|--------------|----------------------------------|----------------------|------------------| 76| GNU/Linux | Tier 1 | kernel >= 2.6.32, glibc >= 2.12 | x64, arm | | 77| GNU/Linux | Tier 1 | kernel >= 3.10, glibc >= 2.17 | arm64 | | 78| macOS/OS X | Tier 1 | >= 10.11 | x64 | | 79| Windows | Tier 1 | >= Windows 7/2008 R2/2012 R2 | x86, x64 | [2](#fn2),[3](#fn3),[4](#fn4) | 80| SmartOS | Tier 2 | >= 15 < 16.4 | x86, x64 | [1](#fn1) | 81| FreeBSD | Tier 2 | >= 10 | x64 | | 82| GNU/Linux | Tier 2 | kernel >= 3.13.0, glibc >= 2.19 | ppc64le >=power8 | | 83| AIX | Tier 2 | >= 7.1 TL04 | ppc64be >=power7 | | 84| GNU/Linux | Tier 2 | kernel >= 3.10, glibc >= 2.17 | s390x | | 85| GNU/Linux | Experimental | kernel >= 2.6.32, glibc >= 2.12 | x86 | limited CI | 86| Linux (musl) | Experimental | musl >= 1.0 | x64 | | 87 88<em id="fn1">1</em>: The gcc4.8-libs package needs to be installed, because node 89 binaries have been built with GCC 4.8, for which runtime libraries are not 90 installed by default. For these node versions, the recommended binaries 91 are the ones available in pkgsrc, not the one available from nodejs.org. 92 Note that the binaries downloaded from the pkgsrc repositories are not 93 officially supported by the Node.js project, and instead are supported 94 by Joyent. SmartOS images >= 16.4 are not supported because 95 GCC 4.8 runtime libraries are not available in their pkgsrc repository 96 97<em id="fn2">2</em>: Tier 1 support for building on Windows is only on 64-bit 98 hosts. Support is experimental for 32-bit hosts. 99 100<em id="fn3">3</em>: On Windows, running Node.js in Windows terminal emulators 101 like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty) 102 for the tty channels to work correctly (e.g. `winpty node.exe script.js`). 103 In "Git bash" if you call the node shell alias (`node` without the `.exe` 104 extension), `winpty` is used automatically. 105 106<em id="fn4">4</em>: The Windows Subsystem for Linux (WSL) is not directly 107 supported, but the GNU/Linux build process and binaries should work. The 108 community will only address issues that reproduce on native GNU/Linux 109 systems. Issues that only reproduce on WSL should be reported in the 110 [WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the 111 Windows binary (`node.exe`) in WSL is not recommended. It will not work 112 without workarounds such as stdio redirection. 113 114### Supported toolchains 115 116Depending on the host platform, the selection of toolchains may vary. 117 118#### Unix 119 120* GCC 4.9.4 or newer 121* Clang 3.4.2 or newer 122 123#### AIX 124* GCC 6.3 or newer 125 126#### Windows 127 128* Visual Studio 2017 with the Windows 10 SDK on a 64-bit host. 129 130#### OpenSSL asm support 131 132OpenSSL-1.1.1 requires the following assembler version for use of asm 133support on x86_64 and ia32. 134 135For use of AVX-512, 136 137* gas (GNU assembler) version 2.26 or higher 138* nasm version 2.11.8 or higher in Windows 139 140Note that AVX-512 is disabled for Skylake-X by OpenSSL-1.1.1. 141 142For use of AVX2, 143 144* gas (GNU assembler) version 2.23 or higher 145* Xcode version 5.0 or higher 146* llvm version 3.3 or higher 147* nasm version 2.10 or higher in Windows 148 149Please refer to 150 https://www.openssl.org/docs/man1.1.1/man3/OPENSSL_ia32cap.html for details. 151 152 If compiling without one of the above, use `configure` with the 153`--openssl-no-asm` flag. Otherwise, `configure` will fail. 154 155## Building Node.js on supported platforms 156 157The [bootstrapping guide](https://github.com/nodejs/node/blob/master/tools/bootstrap/README.md) 158explains how to install all prerequisites. 159 160### Unix/macOS 161 162#### Prerequisites 163 164* `gcc` and `g++` 4.9.4 or newer, or 165* `clang` and `clang++` 3.4.2 or newer (macOS: latest Xcode Command Line Tools) 166* Python 2.6 or 2.7 167* GNU Make 3.81 or newer 168 169On macOS, install the `Xcode Command Line Tools` by running 170`xcode-select --install`. Alternatively, if you already have the full Xcode 171installed, you can find them under the menu `Xcode -> Open Developer Tool -> 172More Developer Tools...`. This step will install `clang`, `clang++`, and 173`make`. 174 175If the path to your build directory contains a space, the build will likely 176fail. 177 178On FreeBSD and OpenBSD, you may also need: 179* libexecinfo 180 181#### Building Node.js 182 183To build Node.js: 184 185```console 186$ ./configure 187$ make -j4 188``` 189 190The `-j4` option will cause `make` to run 4 simultaneous compilation jobs which 191may reduce build time. For more information, see the 192[GNU Make Documentation](https://www.gnu.org/software/make/manual/html_node/Parallel.html). 193 194Note that the above requires that `python` resolve to Python 2.6 or 2.7 195and not a newer version. 196 197After building, setting up [firewall rules](tools/macos-firewall.sh) can avoid 198popups asking to accept incoming network connections when running tests. 199 200Running the following script on macOS will add the firewall rules for the 201executable `node` in the `out` directory and the symbolic `node` link in the 202project's root directory. 203 204```console 205$ sudo ./tools/macos-firewall.sh 206``` 207 208#### Running Tests 209 210To verify the build: 211 212```console 213$ make test-only 214``` 215 216At this point, you are ready to make code changes and re-run the tests. 217 218If you are running tests before submitting a Pull Request, the recommended 219command is: 220 221```console 222$ make -j4 test 223``` 224 225`make -j4 test` does a full check on the codebase, including running linters and 226documentation tests. 227 228Optionally, continue below. 229 230To run the tests and generate code coverage reports: 231 232```console 233$ ./configure --coverage 234$ make coverage 235``` 236 237This will generate coverage reports for both JavaScript and C++ tests (if you 238only want to run the JavaScript tests then you do not need to run the first 239command `./configure --coverage`). 240 241The `make coverage` command downloads some tools to the project root directory 242and overwrites the `lib/` directory. To clean up after generating the coverage 243reports: 244 245```console 246$ make coverage-clean 247``` 248 249#### Building the documentation 250 251To build the documentation: 252 253This will build Node.js first (if necessary) and then use it to build the docs: 254 255```console 256$ make doc 257``` 258 259If you have an existing Node.js build, you can build just the docs with: 260 261```console 262$ NODE=/path/to/node make doc-only 263``` 264 265To read the documentation: 266 267```console 268$ man doc/node.1 269``` 270 271If you prefer to read the documentation in a browser, 272run the following after `make doc` is finished: 273 274```console 275$ make docopen 276``` 277 278This will open a browser with the documentation. 279 280To test if Node.js was built correctly: 281 282```console 283$ ./node -e "console.log('Hello from Node.js ' + process.version)" 284``` 285 286To install this version of Node.js into a system directory: 287 288```console 289$ [sudo] make install 290``` 291 292#### Building a debug build 293 294If you run into an issue where the information provided by the JS stack trace 295is not enough, or if you suspect the error happens outside of the JS VM, you 296can try to build a debug enabled binary: 297 298```console 299$ ./configure --debug 300$ make -j4 301``` 302 303`make` with `./configure --debug` generates two binaries, the regular release 304one in `out/Release/node` and a debug binary in `out/Debug/node`, only the 305release version is actually installed when you run `make install`. 306 307To use the debug build with all the normal dependencies overwrite the release 308version in the install directory: 309 310``` console 311$ make install --prefix=/opt/node-debug/ 312$ cp -a -f out/Debug/node /opt/node-debug/node 313``` 314 315When using the debug binary, core dumps will be generated in case of crashes. 316These core dumps are useful for debugging when provided with the 317corresponding original debug binary and system information. 318 319Reading the core dump requires `gdb` built on the same platform the core dump 320was captured on (i.e. 64-bit `gdb` for `node` built on a 64-bit system, Linux 321`gdb` for `node` built on Linux) otherwise you will get errors like 322`not in executable format: File format not recognized`. 323 324Example of generating a backtrace from the core dump: 325 326``` console 327$ gdb /opt/node-debug/node core.node.8.1535359906 328$ backtrace 329``` 330 331### Windows 332 333Prerequisites: 334 335* [Python 2.6 or 2.7](https://www.python.org/downloads/) 336* The "Desktop development with C++" workload from 337 [Visual Studio 2017](https://www.visualstudio.com/downloads/) or the 338 "Visual C++ build tools" workload from the 339 [Build Tools](https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2017), 340 with the default optional components. 341* Basic Unix tools required for some tests, 342 [Git for Windows](http://git-scm.com/download/win) includes Git Bash 343 and tools which can be included in the global `PATH`. 344* The [NetWide Assembler](http://www.nasm.us/), for OpenSSL assembler modules. 345 If not installed in the default location, it needs to be manually added 346 to `PATH`. A build with the `openssl-no-asm` option does not need this, nor 347 does a build targeting ARM64 Windows. 348* **Optional** (to build the MSI): the [WiX Toolset v3.11](http://wixtoolset.org/releases/) 349 and the [Wix Toolset Visual Studio 2017 Extension](https://marketplace.visualstudio.com/items?itemName=RobMensching.WixToolsetVisualStudio2017Extension). 350* **Optional** Requirements for compiling for Windows 10 on ARM (ARM64): 351 * ARM64 Windows build machine 352 * Due to a GYP limitation, this is required to run compiled code 353 generation tools (like V8's builtins and mksnapshot tools) 354 * Visual Studio 15.9.0 or newer 355 * Visual Studio optional components 356 * Visual C++ compilers and libraries for ARM64 357 * Visual C++ ATL for ARM64 358 * Windows 10 SDK 10.0.17763.0 or newer 359 360If the path to your build directory contains a space or a non-ASCII character, 361the build will likely fail. 362 363```console 364> .\vcbuild 365``` 366 367To run the tests: 368 369```console 370> .\vcbuild test 371``` 372 373To test if Node.js was built correctly: 374 375```console 376> Release\node -e "console.log('Hello from Node.js', process.version)" 377``` 378 379### Android/Android-based devices (e.g. Firefox OS) 380 381Android is not a supported platform. Patches to improve the Android build are 382welcome. There is no testing on Android in the current continuous integration 383environment. The participation of people dedicated and determined to improve 384Android building, testing, and support is encouraged. 385 386Be sure you have downloaded and extracted 387[Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) before in 388a folder. Then run: 389 390```console 391$ ./android-configure /path/to/your/android-ndk 392$ make 393``` 394 395 396### `Intl` (ECMA-402) support: 397 398[Intl](https://github.com/nodejs/node/blob/master/doc/api/intl.md) support is 399enabled by default, with English data only. 400 401#### Default: `small-icu` (English only) support 402 403By default, only English data is included, but 404the full `Intl` (ECMA-402) APIs. It does not need to download 405any dependencies to function. You can add full 406data at runtime. 407 408#### Build with full ICU support (all locales supported by ICU): 409 410With the `--download=all`, this may download ICU if you don't have an 411ICU in `deps/icu`. (The embedded `small-icu` included in the default 412Node.js source does not include all locales.) 413 414##### Unix/macOS: 415 416```console 417$ ./configure --with-intl=full-icu --download=all 418``` 419 420##### Windows: 421 422```console 423> .\vcbuild full-icu download-all 424``` 425 426#### Building without Intl support 427 428The `Intl` object will not be available, nor some other APIs such as 429`String.normalize`. 430 431##### Unix/macOS: 432 433```console 434$ ./configure --without-intl 435``` 436 437##### Windows: 438 439```console 440> .\vcbuild without-intl 441``` 442 443#### Use existing installed ICU (Unix/macOS only): 444 445```console 446$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu 447``` 448 449If you are cross-compiling, your `pkg-config` must be able to supply a path 450that works for both your host and target environments. 451 452#### Build with a specific ICU: 453 454You can find other ICU releases at 455[the ICU homepage](http://icu-project.org/download). 456Download the file named something like `icu4c-**##.#**-src.tgz` (or 457`.zip`). 458 459To check the minimum recommended ICU, run `./configure --help` and see 460the help for the `--with-icu-source` option. A warning will be printed 461during configuration if the ICU version is too old. 462 463##### Unix/macOS 464 465From an already-unpacked ICU: 466```console 467$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu 468``` 469 470From a local ICU tarball: 471```console 472$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz 473``` 474 475From a tarball URL: 476```console 477$ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz 478``` 479 480##### Windows 481 482First unpack latest ICU to `deps/icu` 483[icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`) 484as `deps/icu` (You'll have: `deps/icu/source/...`) 485 486```console 487> .\vcbuild full-icu 488``` 489 490## Building Node.js with FIPS-compliant OpenSSL 491 492This version of Node.js does not support FIPS. 493 494## Building Node.js with external core modules 495 496It is possible to specify one or more JavaScript text files to be bundled in 497the binary as built-in modules when building Node.js. 498 499### Unix/macOS 500 501This command will make `/root/myModule.js` available via 502`require('/root/myModule')` and `./myModule2.js` available via 503`require('myModule2')`. 504 505```console 506$ ./configure --link-module '/root/myModule.js' --link-module './myModule2.js' 507``` 508 509### Windows 510 511To make `./myModule.js` available via `require('myModule')` and 512`./myModule2.js` available via `require('myModule2')`: 513 514```console 515> .\vcbuild link-module './myModule.js' link-module './myModule2.js' 516``` 517 518## Note for downstream distributors of Node.js 519 520The Node.js ecosystem is reliant on ABI compatibility within a major 521release. To maintain ABI compatibility it is required that production 522builds of Node.js will be built against the same version of dependencies as the 523project vendors. If Node.js is to be built against a different version of a 524dependency please create a custom `NODE_MODULE_VERSION` to ensure ecosystem 525compatibility. Please consult with the TSC by opening an issue at 526https://github.com/nodejs/tsc/issues if you decide to create a custom 527`NODE_MODULE_VERSION` so we can avoid duplication in the ecosystem. 528