diff options
Diffstat (limited to 'BUILDING.md')
| -rw-r--r-- | BUILDING.md | 177 |
1 files changed, 120 insertions, 57 deletions
diff --git a/BUILDING.md b/BUILDING.md index 02a4deb0e5..3b459095df 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -10,41 +10,46 @@ file a new issue. ## Table of Contents -* [Supported platforms](#supported-platforms) - * [Input](#input) - * [Strategy](#strategy) - * [Platform list](#platform-list) - * [Supported toolchains](#supported-toolchains) - * [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) - * [Running Tests](#running-tests) - * [Running Coverage](#running-coverage) - * [Building the documentation](#building-the-documentation) - * [Building a debug build](#building-a-debug-build) - * [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-1) - * [Building without Intl support](#building-without-intl-support) - * [Unix/macOS](#unixmacos-2) - * [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-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-4) -* [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs) +* [Supported platforms](#Supported-platforms) + * [Input](#Input) + * [Strategy](#Strategy) + * [Platform list](#Platform-list) + * [Supported toolchains](#Supported-toolchains) + * [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) + * [Note about Python 2 and Python 3](#Note-about-Python-2-and-Python-3) + * [Unix and macOS](#Unix-and-macOS) + * [Prerequisites](#Prerequisites) + * [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) + * [Prerequisites](#Prerequisites-1) + * [Option 1: Manual install](#Option-1-Manual-install) + * [Option 1: Automated install with Boxstarter](#Option-1-Automated-install-with-Boxstarter) + * [Building Node.js](#Building-Nodejs-1) + * [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) + * [Windows](#Windows-1) + * [Building without Intl support](#Building-without-Intl-support) + * [Unix/macOS](#UnixmacOS-1) + * [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-2) + * [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-3) + * [Windows](#Windows-4) +* [Note for downstream distributors of Node.js](#Note-for-downstream-distributors-of-Nodejs) ## Supported platforms @@ -215,21 +220,32 @@ Consult previous versions of this document for older versions of Node.js: ## Building Node.js on supported platforms -The [bootstrapping guide](https://github.com/nodejs/node/blob/master/tools/bootstrap/README.md) -explains how to install all prerequisites. +### Note about Python 2 and Python 3 -### Unix/macOS +The Node.js project uses Python as part of its build process and has +historically only been Python 2 compatible. + +Python 2 will reach its _end-of-life_ at the end of 2019 at which point the +interpreter will cease receiving updates. See https://python3statement.org/ +for more information. + +The Node.js project is in the process of transitioning its Python code to +Python 3 compatibility. Installing both versions of Python while building +and testing Node.js allows developers and end users to test, benchmark, +and debug Node.js running on both versions to ensure a smooth and complete +transition before the year-end deadline. + +### Unix and macOS #### Prerequisites -* `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. +* `gcc` and `g++` >= 6.3 or newer, or Xcode Command Line Tools >= 8 for macOS +* Python (see note above) + * Python 2.7 * Python 3.5, 3.6, and 3.7 are experimental. * GNU Make 3.81 or newer -On macOS, install the `Xcode Command Line Tools` by running +macOS users can install the `Xcode Command Line Tools` by running `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 @@ -238,8 +254,14 @@ More Developer Tools...`. This step will install `clang`, `clang++`, and If the path to your build directory contains a space, the build will likely fail. -On FreeBSD and OpenBSD, you may also need: -* libexecinfo +Installation via Linux package manager can be achieved with: + +* Ubuntu, Debian: `sudo apt-get install python g++ make` +* Fedora: `sudo dnf install python gcc-c++ make` +* CentOS and RHEL: `sudo yum install python gcc-c++ make` +* OpenSUSE: `sudo zypper install python gcc-c++ make` + +FreeBSD and OpenBSD users may also need to install `libexecinfo`. #### Building Node.js @@ -461,7 +483,9 @@ $ backtrace ### Windows -Prerequisites: +#### Prerequisites + +##### Option 1: Manual install * [Python 2.7](https://www.python.org/downloads/) * The "Desktop development with C++" workload from @@ -476,17 +500,56 @@ Prerequisites: If not installed in the default location, it needs to be manually added to `PATH`. A build with the `openssl-no-asm` option does not need this, nor does a build targeting ARM64 Windows. -* **Optional** (to build the MSI): the [WiX Toolset v3.11](http://wixtoolset.org/releases/) - and the [Wix Toolset Visual Studio 2017 Extension](https://marketplace.visualstudio.com/items?itemName=RobMensching.WixToolsetVisualStudio2017Extension). -* **Optional** Requirements for compiling for Windows 10 on ARM (ARM64): - * ARM64 Windows build machine - * Due to a GYP limitation, this is required to run compiled code - generation tools (like V8's builtins and mksnapshot tools) - * Visual Studio 15.9.0 or newer - * 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 + +Optional requirements to build the MSI: + +* The [WiX Toolset v3.11](http://wixtoolset.org/releases/) and the + [Wix Toolset Visual Studio 2017 Extension](https://marketplace.visualstudio.com/items?itemName=RobMensching.WixToolsetVisualStudio2017Extension). + +Optional requirements for compiling for Windows 10 on ARM (ARM64): + +* ARM64 Windows build machine + * Due to a GYP limitation, this is required to run compiled code + generation tools (like V8's builtins and mksnapshot tools) +* Visual Studio 15.9.0 or newer +* 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 + +##### Option 2: Automated install with Boxstarter +<a name="boxstarter"></a> + +A [Boxstarter](http://boxstarter.org/) script can be used for easy setup of +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 + Unix tools added to the `PATH`. +* [Python 3.x](https://chocolatey.org/packages/python) and + [legacy Python](https://chocolatey.org/packages/python2) +* [Visual Studio 2017 Build Tools](https://chocolatey.org/packages/visualstudio2017buildtools) + with [Visual C++ workload](https://chocolatey.org/packages/visualstudio2017-workload-vctools) +* [NetWide Assembler](https://chocolatey.org/packages/nasm) + +To install Node.js prerequisites using +[Boxstarter WebLauncher](http://boxstarter.org/WebLauncher), open +<http://boxstarter.org/package/nr/url?https://raw.githubusercontent.com/nodejs/node/master/tools/bootstrap/windows_boxstarter> +with Internet Explorer or Edge browser on the target machine. + +Alternatively, you can use PowerShell. Run those commands from an elevated +PowerShell terminal: + +```powershell +Set-ExecutionPolicy Unrestricted -Force +iex ((New-Object System.Net.WebClient).DownloadString('http://boxstarter.org/bootstrapper.ps1')) +get-boxstarter -Force +Install-BoxstarterPackage https://raw.githubusercontent.com/nodejs/node/master/tools/bootstrap/windows_boxstarter -DisableReboots +``` + +The entire installation using Boxstarter will take up approximately 10 GB of disk space. + +#### Building Node.js If the path to your build directory contains a space or a non-ASCII character, the build will likely fail. |