Skip to content

Commit

Permalink
doc: update supported platforms for Node.js 12
Browse files Browse the repository at this point in the history
  • Loading branch information
@rvagg
rvagg committed Apr 20, 2019
1 parent d4dae5e commit 6894480
Showing 1 changed file with 130 additions and 64 deletions.
194 changes: 130 additions & 64 deletions BUILDING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,38 +13,38 @@ file a new issue.
* [Supported platforms](#supported-platforms)
* [Input](#input)
* [Strategy](#strategy)
* [Supported platforms](#supported-platforms-1)
* [Platform list](#platform-list)
* [Supported toolchains](#supported-toolchains)
* [Unix](#unix)
* [AIX](#aix)
* [Windows](#windows)
* [Official binary platforms and toolchains](#official-binary-platforms-and-toolchains)
* [OpenSSL asm support](#openssl-asm-support)
* [Previous versions of this document](#previous-versions-of-this-document)
* [Building Node.js on supported platforms](#building-nodejs-on-supported-platforms)
* [Unix/macOS](#unixmacos)
* [Prerequisites](#prerequisites)
* [Building Node.js](#building-nodejs-1)
* [Building Node.js](#building-nodejs)
* [Running Tests](#running-tests)
* [Running Coverage](#running-coverage)
* [Building the documentation](#building-the-documentation)
* [Building a debug build](#building-a-debug-build)
* [Windows](#windows-1)
* [Windows](#windows)
* [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os)
* [`Intl` (ECMA-402) support](#intl-ecma-402-support)
* [Default: `small-icu` (English only) support](#default-small-icu-english-only-support)
* [Build with full ICU support (all locales supported by ICU)](#build-with-full-icu-support-all-locales-supported-by-icu)
* [Unix/macOS](#unixmacos-1)
* [Windows](#windows-2)
* [Windows](#windows-1)
* [Building without Intl support](#building-without-intl-support)
* [Unix/macOS](#unixmacos-2)
* [Windows](#windows-3)
* [Windows](#windows-2)
* [Use existing installed ICU (Unix/macOS only)](#use-existing-installed-icu-unixmacos-only)
* [Build with a specific ICU](#build-with-a-specific-icu)
* [Unix/macOS](#unixmacos-3)
* [Windows](#windows-4)
* [Windows](#windows-3)
* [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)
* [Unix/macOS](#unixmacos-4)
* [Windows](#windows-5)
* [Windows](#windows-4)
* [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs)

## Supported platforms

Expand All @@ -59,68 +59,124 @@ Node.js relies on V8 and libuv. We adopt a subset of their supported platforms.

There are three support tiers:

* **Tier 1**: Full test coverage and maintenance by the Node.js core team and
the broader community.
* **Tier 2**: Full test coverage. Limited maintenance, often provided by the
vendor of the platform.
* **Experimental**: May not compile or test suite may not pass.
These are often approaching Tier 2 support but are not quite ready.
There is at least one individual providing maintenance.

### Supported platforms

For production applications, run Node.js on supported platforms only.
* **Tier 1**: These platforms represent the majority of Node.js users. The
Node.js Build Working Group maintains infrastructure for full test coverage.
Maintenance is supported by the Node.js core team. All commits to the
Node.js repository are tested on multiple variants of these platforms. Test
failures on tier 1 platforms will block releases.
* **Tier 2**: These platforms represent smaller segments of the Node.js user
base. The Node.js Build Working Group maintains infrastructure for full test
coverage. Maintenance is supported by smaller groups or individuals within
the Node.js core team, or the vendor of the platform itself. All commits to
the Node.js repository are tested on multiple variants of these platforms
where practical. Test failures on tier 2 platforms will block releases.
Delays in release of binaries for these platforms are acceptable
where necessary due to infrastructure concerns.
* **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
will be updated to reflect those changes.

### Platform list

Compiling and running Node.js is supported for a limited set of operating
systems, architectures and libc versions. The table below lists the
combinations that the core team has committed to supporting and the nature of
that support as per the support tiers above. A list of
[supported compile toolchains](#supported-toolchains) is also supplied for
tier 1 platforms.

**For production applications, run Node.js on supported platforms only.**

Node.js does not support a platform version if a vendor has expired support
for it. In other words, Node.js does not support running on End-of-Life (EoL)
platforms. This is true regardless of entries in the table below.

| System | Support type | Version | Architectures | Notes |
| ------------ | ------------ | ------------------------------- | ---------------- | ----------------------------- |
| GNU/Linux | Tier 1 | kernel >= 2.6.32, glibc >= 2.12 | x64, arm | |
| GNU/Linux | Tier 1 | kernel >= 3.10, glibc >= 2.17 | arm64 | |
| macOS/OS X | Tier 1 | >= 10.11 | x64 | |
| Windows | Tier 1 | >= Windows 7/2008 R2/2012 R2 | x86, x64 | [1](#fn1),[2](#fn2),[3](#fn3) |
| SmartOS | Tier 2 | >= 16 | x64 | |
| FreeBSD | Tier 2 | >= 11 | x64 | |
| GNU/Linux | Tier 2 | kernel >= 3.13.0, glibc >= 2.19 | ppc64le >=power8 | |
| AIX | Tier 2 | >= 7.1 TL04 | ppc64be >=power7 | |
| GNU/Linux | Tier 2 | kernel >= 3.10, glibc >= 2.17 | s390x | |
| GNU/Linux | Experimental | kernel >= 2.6.32, glibc >= 2.12 | x86 | limited CI |
| Linux (musl) | Experimental | musl >= 1.0 | x64 | |

<em id="fn1">1</em>: Tier 1 support for building on Windows is only on 64-bit
hosts. Support is experimental for 32-bit hosts.

<em id="fn2">2</em>: On Windows, running Node.js in Windows terminal emulators
| Operating System | Architectures | Versions | Support Type | Notes |
| ---------------- | ---------------- | ------------------------------- | ------------ | --------------------------------- |
| GNU/Linux | x64 | kernel >= 3.10, glibc >= 2.17 | Tier 1 | e.g. Ubuntu 16.04 <sup>[1](#fn1)</sup>, Debian 9, EL 7 <sup>[2](#fn2)</sup> |
| 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.5, glibc >= 2.17 | Tier 1 | e.g. Ubuntu 16.04, Debian 9, EL 7 <sup>[3](#fn3)</sup> |
| GNU/Linux | armv7 | kernel >= 4.14, glibc >= 2.24 | Tier 1 | e.g. Ubuntu 18.04, Debian 9 |
| GNU/Linux | armv6 | kernel >= 4.14, glibc >= 2.24 | Experimental | Downgraded as of Node.js 12 |
| GNU/Linux | ppc64le >=power8 | kernel >= 3.13.0, glibc >= 2.19 | Tier 2 | e.g. Ubuntu 16.04, EL 7 |
| GNU/Linux | s390x | kernel >= 3.10.0, glibc >= 2.17 | Tier 2 | e.g. EL 7 |
| Windows | x64, x86 (WoW64) | >= Windows 7/2008 R2/2012 R2 | Tier 1 | <sup>[4](#fn4),[5](#fn5)</sup> |
| Windows | x86 (native) | >= Windows 7/2008 R2/2012 R2 | Tier 1 (running) / Experimental (compiling) <sup>[6](#fn6)</sup> | |
| Windows | arm64 | >= Windows 10 | Experimental | |
| macOS | x64 | >= 10.11 | Tier 1 | |
| SmartOS | x64 | >= 18 | Tier 2 | |
| AIX | ppc64be >=power7 | >= 7.1 TL05 | Tier 2 | |
| FreeBSD | x64 | >= 11 | Experimental | Downgraded as of Node.js 12 |

<em id="fn1">1</em>: GCC 6 is not provided on the base platform, users will
need the
[Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial)
or similar to source a newer compiler.

<em id="fn2">2</em>: GCC 6 is not provided on the base platform, users will
need the
[devtoolset-6](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-6/)
or later to source a newer compiler.

<em id="fn3">3</em>: Older kernel versions may work for ARM64, however the
Node.js test infrastructure only tests >= 4.5.

<em id="fn4">4</em>: On Windows, running Node.js in Windows terminal emulators
like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty)
for the tty channels to work correctly (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.

<em id="fn3">3</em>: The Windows Subsystem for Linux (WSL) is not directly
<em id="fn5">5</em>: The Windows Subsystem for Linux (WSL) is not directly
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
Windows binary (`node.exe`) in WSL is not recommended. It will not work
without workarounds such as stdio redirection.

<em id="fn6">6</em>: Running Node.js on x86 Windows should work and binaries
are provided. However, tests in our infrastructure only run on WoW64.
Furthermore, compiling on x86 Windows is currently considered Experimental and
may not be possible.

### Supported toolchains

Depending on the host platform, the selection of toolchains may vary.

#### Unix

* GCC 4.9.4 or newer
* Clang 3.4.2 or newer

#### AIX
* GCC 6.3 or newer

#### Windows

* Visual Studio 2017 with the Windows 10 SDK on a 64-bit host.
| Operating System | Compiler Versions |
| ---------------- | -------------------------------------------------------------- |
| Linux | GCC >= 6.3 |
| Windows | Visual Studio >= 2017 with the Windows 10 SDK on a 64-bit host |
| macOS | Xcode >= 8 (Apple LLVM >= 8) |

### Official binary platforms and toolchains

Binaries at <https://nodejs.org/download/release/> are produced on:

| Binary package | Platform and Toolchain |
| --------------------- | ------------------------------------------------------------------------ |
| aix-ppc64 | AIX 7.1 TL05 on PPC64BE with GCC 6 |
| darwin-x64 (and .pkg) | macOS 10.11, Xcode Command Line Tools 8 with -mmacosx-version-min=10.10 |
| linux-arm64 | CentOS 7 with devtoolset-6 / GCC 6 |
| linux-armv7l | Cross-compiled on Ubuntu 16.04 x64 with [custom GCC toolchain](https://github.com/rvagg/rpi-newer-crosstools) |
| linux-ppc64le | Ubuntu 14.04 with GCC 6 |
| linux-s390x | RHEL 7 with devtoolset-6 / GCC 6 <sup>[7](#fn7)</sup> |
| linux-x64 | CentOS 7 with devtoolset-6 / GCC 6 <sup>[7](#fn7)</sup> |
| sunos-x64 | SmartOS 18 with GCC 7 |
| win-x64 and win-x86 | Windows 2012 R2 (x64) with Visual Studio 2017 |

<em id="fn7">7</em>: The Enterprise Linux devtoolset-6 allows us to compile
binaries with GCC 6 but linked to the glibc and libstdc++ versions of the host
platforms (CentOS 7 / RHEL 7). Therefore, binaries produced on these systems
are compatible with glibc >= 2.17 and libstdc++ >= 6.0.20 (`GLIBCXX_3.4.20`).
These are available on distributions natively supporting GCC 4.9, such as
Ubuntu 14.04 and Debian 8.

#### OpenSSL asm support

Expand All @@ -147,6 +203,16 @@ Please refer to
If compiling without one of the above, use `configure` with the
`--openssl-no-asm` flag. Otherwise, `configure` will fail.

### 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:

* [Node.js 10](https://github.com/nodejs/node/blob/v10.x/BUILDING.md)
* [Node.js 8](https://github.com/nodejs/node/blob/v8.x/BUILDING.md)
* [Node.js 6](https://github.com/nodejs/node/blob/v6.x/BUILDING.md)

## Building Node.js on supported platforms

The [bootstrapping guide](https://github.com/nodejs/node/blob/master/tools/bootstrap/README.md)
Expand All @@ -156,8 +222,8 @@ explains how to install all prerequisites.

#### Prerequisites

* `gcc` and `g++` 4.9.4 or newer, or
* `clang` and `clang++` 3.4.2 or newer (macOS: latest Xcode Command Line Tools)
* `gcc` and `g++` >= 6.3 or newer, or
* macOS: Xcode Command Line Tools >= 8
* Python 2.7
* Python 2.7 end of life is in 2019 so a transition to Python 3 is underway.
* Python 3.5, 3.6, and 3.7 are experimental.
Expand Down Expand Up @@ -188,8 +254,8 @@ The `-j4` option will cause `make` to run 4 simultaneous compilation jobs which
may reduce build time. For more information, see the
[GNU Make Documentation](https://www.gnu.org/software/make/manual/html_node/Parallel.html).

Note that the above requires that `python` resolve to Python 2.7 and not a newer
version. See [Prerequisites](#prerequisites).
Note that the above requires that `python` resolves to a supported version of
Python. See [Prerequisites](#prerequisites).

After building, setting up [firewall rules](tools/macos-firewall.sh) can avoid
popups asking to accept incoming network connections when running tests.
Expand Down Expand Up @@ -457,7 +523,7 @@ $ make
```


### `Intl` (ECMA-402) support:
### `Intl` (ECMA-402) support

[Intl](https://github.com/nodejs/node/blob/master/doc/api/intl.md) support is
enabled by default, with English data only.
Expand All @@ -469,19 +535,19 @@ the full `Intl` (ECMA-402) APIs. It does not need to download
any dependencies to function. You can add full
data at runtime.

#### Build with full ICU support (all locales supported by ICU):
#### Build with full ICU support (all locales supported by ICU)

With the `--download=all`, this may download ICU if you don't have an
ICU in `deps/icu`. (The embedded `small-icu` included in the default
Node.js source does not include all locales.)

##### Unix/macOS:
##### Unix/macOS

```console
$ ./configure --with-intl=full-icu --download=all
```

##### Windows:
##### Windows

```console
> .\vcbuild full-icu download-all
Expand All @@ -492,19 +558,19 @@ $ ./configure --with-intl=full-icu --download=all
The `Intl` object will not be available, nor some other APIs such as
`String.normalize`.

##### Unix/macOS:
##### Unix/macOS

```console
$ ./configure --without-intl
```

##### Windows:
##### Windows

```console
> .\vcbuild without-intl
```

#### Use existing installed ICU (Unix/macOS only):
#### Use existing installed ICU (Unix/macOS only)

```console
$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
Expand All @@ -513,7 +579,7 @@ $ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
If you are cross-compiling, your `pkg-config` must be able to supply a path
that works for both your host and target environments.

#### Build with a specific ICU:
#### Build with a specific ICU

You can find other ICU releases at
[the ICU homepage](http://icu-project.org/download).
Expand Down Expand Up @@ -553,7 +619,7 @@ as `deps/icu` (You'll have: `deps/icu/source/...`)

## Building Node.js with FIPS-compliant OpenSSL

This version of Node.js does not support FIPS.
The current version of Node.js does not support FIPS.

## Building Node.js with external core modules

Expand Down

0 comments on commit 6894480

Please sign in to comment.