Skip to content

Commit ce2dc48

Browse files
Trottdanielleadams
Trott
authored and
danielleadams
committed
doc: use GFM footnotes in BUILDING.md
PR-URL: #40474 Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
1 parent 5e606b5 commit ce2dc48

File tree

1 file changed

+113
-72
lines changed

1 file changed

+113
-72
lines changed

‎BUILDING.md‎

Lines changed: 113 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -99,65 +99,61 @@ Node.js does not support a platform version if a vendor has expired support
9999
for it. In other words, Node.js does not support running on End-of-Life (EoL)
100100
platforms. This is true regardless of entries in the table below.
101101

102-
| Operating System | Architectures | Versions | Support Type | Notes |
103-
| ---------------- | ---------------- | ------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
104-
| 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> |
105-
| GNU/Linux | x64 | kernel >= 3.10, musl >= 1.1.19 | Experimental | e.g. Alpine 3.8 |
106-
| GNU/Linux | x86 | kernel >= 3.10, glibc >= 2.17 | Experimental | Downgraded as of Node.js 10 |
107-
| GNU/Linux | arm64 | kernel >= 4.5, glibc >= 2.17 | Tier 1 | e.g. Ubuntu 16.04, Debian 9, EL 7 <sup>[3](#fn3)</sup> |
108-
| GNU/Linux | armv7 | kernel >= 4.14, glibc >= 2.24 | Tier 1 | e.g. Ubuntu 18.04, Debian 9 |
109-
| GNU/Linux | armv6 | kernel >= 4.14, glibc >= 2.24 | Experimental | Downgraded as of Node.js 12 |
110-
| GNU/Linux | ppc64le >=power8 | kernel >= 3.10.0, glibc >= 2.17 | Tier 2 | e.g. Ubuntu 16.04 <sup>[1](#fn1)</sup>, EL 7 <sup>[2](#fn2)</sup> |
111-
| GNU/Linux | s390x | kernel >= 3.10.0, glibc >= 2.17 | Tier 2 | e.g. EL 7 <sup>[2](#fn2)</sup> |
112-
| Windows | x64, x86 (WoW64) | >= Windows 8.1/2012 R2 | Tier 1 | <sup>[4](#fn4),[5](#fn5)</sup> |
113-
| Windows | x86 (native) | >= Windows 8.1/2012 R2 | Tier 1 (running) / Experimental (compiling) <sup>[6](#fn6)</sup> | |
114-
| Windows | x64, x86 | Windows Server 2012 (not R2) | Experimental | |
115-
| Windows | arm64 | >= Windows 10 | Tier 2 (compiling) / Experimental (running) | |
116-
| macOS | x64 | >= 10.13 | Tier 1 | For notes about compilation see <sup>[7](#fn7)</sup> |
117-
| macOS | arm64 | >= 11 | Tier 1 | |
118-
| SmartOS | x64 | >= 18 | Tier 2 | |
119-
| AIX | ppc64be >=power7 | >= 7.2 TL04 | Tier 2 | |
120-
| FreeBSD | x64 | >= 12.2 | Experimental | |
121-
122-
<em id="fn1">1</em>: GCC 8 is not provided on the base platform. Users will
123-
need the
124-
[Toolchain test builds PPA](https://launchpad.net/\~ubuntu-toolchain-r/+archive/ubuntu/test?field.series\_filter=xenial)
125-
or similar to source a newer compiler.
126-
127-
<em id="fn2">2</em>: GCC 8 is not provided on the base platform. Users will
128-
need the
129-
[devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/)
130-
or later to source a newer compiler.
131-
132-
<em id="fn3">3</em>: Older kernel versions may work for ARM64. However the
133-
Node.js test infrastructure only tests >= 4.5.
134-
135-
<em id="fn4">4</em>: On Windows, running Node.js in Windows terminal emulators
136-
like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty)
137-
for the tty channels to work (e.g. `winpty node.exe script.js`).
138-
In "Git bash" if you call the node shell alias (`node` without the `.exe`
139-
extension), `winpty` is used automatically.
140-
141-
<em id="fn5">5</em>: The Windows Subsystem for Linux (WSL) is not
142-
supported, but the GNU/Linux build process and binaries should work. The
143-
community will only address issues that reproduce on native GNU/Linux
144-
systems. Issues that only reproduce on WSL should be reported in the
145-
[WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the
146-
Windows binary (`node.exe`) in WSL is not recommended. It will not work
147-
without workarounds such as stdio redirection.
148-
149-
<em id="fn6">6</em>: Running Node.js on x86 Windows should work and binaries
150-
are provided. However, tests in our infrastructure only run on WoW64.
151-
Furthermore, compiling on x86 Windows is Experimental and
152-
may not be possible.
153-
154-
<em id="fn7">7</em>: The default FreeBSD 12.0 compiler is Clang 6.0.1, but
155-
FreeBSD 12.1 upgrades to 8.0.1. Other Clang/LLVM versions are available
156-
via the system's package manager, including Clang 9.0.
157-
158-
<em id="fn8">8</em>: Our macOS x64 Binaries are compiled with 10.13 as a target.
159-
However there is no guarantee compiling on 10.13 will work as Xcode11 is
160-
required to compile.
102+
| Operating System | Architectures | Versions | Support Type | Notes |
103+
| ---------------- | ---------------- | ------------------------------- | ----------------------------------------------- | ----------------------------------------- |
104+
| GNU/Linux | x64 | kernel >= 3.10, glibc >= 2.17 | Tier 1 | e.g. Ubuntu 16.04[^1], Debian 9, EL 7[^2] |
105+
| GNU/Linux | x64 | kernel >= 3.10, musl >= 1.1.19 | Experimental | e.g. Alpine 3.8 |
106+
| GNU/Linux | x86 | kernel >= 3.10, glibc >= 2.17 | Experimental | Downgraded as of Node.js 10 |
107+
| GNU/Linux | arm64 | kernel >= 4.5, glibc >= 2.17 | Tier 1 | e.g. Ubuntu 16.04, Debian 9, EL 7[^3] |
108+
| GNU/Linux | armv7 | kernel >= 4.14, glibc >= 2.24 | Tier 1 | e.g. Ubuntu 18.04, Debian 9 |
109+
| GNU/Linux | armv6 | kernel >= 4.14, glibc >= 2.24 | Experimental | Downgraded as of Node.js 12 |
110+
| GNU/Linux | ppc64le >=power8 | kernel >= 3.10.0, glibc >= 2.17 | Tier 2 | e.g. Ubuntu 16.04[^1], EL 7[^2] |
111+
| GNU/Linux | s390x | kernel >= 3.10.0, glibc >= 2.17 | Tier 2 | e.g. EL 7[^2] |
112+
| Windows | x64, x86 (WoW64) | >= Windows 8.1/2012 R2 | Tier 1 | [^4],[^5] |
113+
| Windows | x86 (native) | >= Windows 8.1/2012 R2 | Tier 1 (running) / Experimental (compiling)[^6] | |
114+
| Windows | x64, x86 | Windows Server 2012 (not R2) | Experimental | |
115+
| Windows | arm64 | >= Windows 10 | Tier 2 (compiling) / Experimental (running) | |
116+
| macOS | x64 | >= 10.13 | Tier 1 | For notes about compilation see [^7] |
117+
| macOS | arm64 | >= 11 | Tier 1 | |
118+
| SmartOS | x64 | >= 18 | Tier 2 | |
119+
| AIX | ppc64be >=power7 | >= 7.2 TL04 | Tier 2 | |
120+
| FreeBSD | x64 | >= 12.2 | Experimental | |
121+
122+
[^1]: GCC 8 is not provided on the base platform. Users will
123+
need the
124+
[Toolchain test builds PPA](https://launchpad.net/\~ubuntu-toolchain-r/+archive/ubuntu/test?field.series\_filter=xenial)
125+
or similar to source a newer compiler.
126+
127+
[^2]: GCC 8 is not provided on the base platform. Users will
128+
need the
129+
[devtoolset-8](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-8/)
130+
or later to source a newer compiler.
131+
132+
[^3]: Older kernel versions may work for ARM64. However the
133+
Node.js test infrastructure only tests >= 4.5.
134+
135+
[^4]: On Windows, running Node.js in Windows terminal emulators
136+
like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty)
137+
for the tty channels to work (e.g. `winpty node.exe script.js`).
138+
In "Git bash" if you call the node shell alias (`node` without the `.exe`
139+
extension), `winpty` is used automatically.
140+
141+
[^5]: The Windows Subsystem for Linux (WSL) is not
142+
supported, but the GNU/Linux build process and binaries should work. The
143+
community will only address issues that reproduce on native GNU/Linux
144+
systems. Issues that only reproduce on WSL should be reported in the
145+
[WSL issue tracker](https://github.com/Microsoft/WSL/issues). Running the
146+
Windows binary (`node.exe`) in WSL is not recommended. It will not work
147+
without workarounds such as stdio redirection.
148+
149+
[^6]: Running Node.js on x86 Windows should work and binaries
150+
are provided. However, tests in our infrastructure only run on WoW64.
151+
Furthermore, compiling on x86 Windows is Experimental and
152+
may not be possible.
153+
154+
[^7]: Our macOS x64 Binaries are compiled with 10.13 as a target.
155+
However there is no guarantee compiling on 10.13 will work as Xcode11 is
156+
required to compile.
161157

162158
### Supported toolchains
163159

@@ -178,19 +174,19 @@ Binaries at <https://nodejs.org/download/release/> are produced on:
178174
| aix-ppc64 | AIX 7.2 TL04 on PPC64BE with GCC 8 |
179175
| darwin-x64 | macOS 10.15, Xcode Command Line Tools 11 with -mmacosx-version-min=10.13 |
180176
| darwin-arm64 (and .pkg) | macOS 11 (arm64), Xcode Command Line Tools 12 with -mmacosx-version-min=10.13 |
181-
| linux-arm64 | CentOS 7 with devtoolset-8 / GCC 8 <sup>[8](#fn8)</sup> |
177+
| linux-arm64 | CentOS 7 with devtoolset-8 / GCC 8[^8] |
182178
| linux-armv7l | Cross-compiled on Ubuntu 18.04 x64 with [custom GCC toolchain](https://github.com/rvagg/rpi-newer-crosstools) |
183-
| linux-ppc64le | CentOS 7 with devtoolset-8 / GCC 8 <sup>[8](#fn8)</sup> |
184-
| linux-s390x | RHEL 7 with devtoolset-8 / GCC 8 <sup>[8](#fn8)</sup> |
185-
| linux-x64 | CentOS 7 with devtoolset-8 / GCC 8 <sup>[8](#fn8)</sup> |
179+
| linux-ppc64le | CentOS 7 with devtoolset-8 / GCC 8[^8] |
180+
| linux-s390x | RHEL 7 with devtoolset-8 / GCC 8[^8] |
181+
| linux-x64 | CentOS 7 with devtoolset-8 / GCC 8[^8] |
186182
| win-x64 and win-x86 | Windows 2012 R2 (x64) with Visual Studio 2019 |
187183

188-
<em id="fn8">8</em>: The Enterprise Linux devtoolset-8 allows us to compile
189-
binaries with GCC 8 but linked to the glibc and libstdc++ versions of the host
190-
platforms (CentOS 7 / RHEL 7). Therefore, binaries produced on these systems
191-
are compatible with glibc >= 2.17 and libstdc++ >= 6.0.20 (`GLIBCXX_3.4.20`).
192-
These are available on distributions natively supporting GCC 4.9, such as
193-
Ubuntu 14.04 and Debian 8.
184+
[^8]: The Enterprise Linux devtoolset-8 allows us to compile binaries with GCC 8
185+
but linked to the glibc and libstdc++ versions of the host platforms
186+
(CentOS 7 / RHEL 7). Therefore, binaries produced on these systems are
187+
compatible with glibc >= 2.17 and libstdc++ >= 6.0.20 (`GLIBCXX_3.4.20`).
188+
These are available on distributions natively supporting GCC 4.9, such as
189+
Ubuntu 14.04 and Debian 8.
194190

195191
#### OpenSSL asm support
196192

@@ -776,9 +772,54 @@ as `deps/icu` (You'll have: `deps/icu/source/...`)
776772

777773
## Building Node.js with FIPS-compliant OpenSSL
778774

779-
The current version of Node.js does not support FIPS when statically linking
780-
(the default) with OpenSSL 1.1.1 but for dynamically linking it is possible
781-
to enable FIPS using the configuration flag `--openssl-is-fips`.
775+
The current version of Node.js supports FIPS when statically and
776+
dynamically linking with OpenSSL 3.0.0 by using the configuration flag
777+
`--openssl-is-fips`.
778+
779+
### FIPS support when statically linking OpenSSL
780+
781+
FIPS can be supported by specifying the configuration flag `--openssl-is-fips`:
782+
783+
```console
784+
$ ./configure --openssl-is-fips
785+
$ make -j8
786+
```
787+
788+
The above command will build and install the FIPS module into the out directory.
789+
This includes building fips.so, running the `installfips` command that generates
790+
the FIPS configuration file (fipsmodule.cnf), copying and updating openssl.cnf
791+
to include the correct path to fipsmodule.cnf and finally uncomment the fips
792+
section.
793+
794+
We can then run node specifying `--enable-fips`:
795+
796+
```console
797+
$ ./node --enable-fips -p 'crypto.getFips()'
798+
1
799+
```
800+
801+
The above will use the Node.js default locations for OpenSSL 3.0:
802+
803+
```console
804+
$ ./out/Release/openssl-cli version -m -d
805+
OPENSSLDIR: "/nodejs/openssl/out/Release/obj.target/deps/openssl"
806+
MODULESDIR: "/nodejs/openssl/out/Release/obj.target/deps/openssl/lib/openssl-modules"
807+
```
808+
809+
The OpenSSL configuration files will be found in `OPENSSLDIR` directory above:
810+
811+
```console
812+
$ ls -w 1 out/Release/obj.target/deps/openssl/*.cnf
813+
out/Release/obj.target/deps/openssl/fipsmodule.cnf
814+
out/Release/obj.target/deps/openssl/openssl.cnf
815+
```
816+
817+
And the FIPS module will be located in the `MODULESDIR` directory:
818+
819+
```console
820+
$ ls out/Release/obj.target/deps/openssl/lib/openssl-modules/
821+
fips.so
822+
```
782823

783824
### Configuring and building quictls/openssl for FIPS
784825

0 commit comments

Comments
 (0)