Skip to content

doc: merge bootstrap/README.md into BUILDING.md #28465

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
rvagg wants to merge 3 commits into from
Closed

doc: merge bootstrap/README.md into BUILDING.md #28465

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1b7fe72
doc: merge bootstrap/README.md into BUILDING.md
rvagg Jun 28, 2019
b060a3b
fixup! doc: merge bootstrap/README.md into BUILDING.md
rvagg Jun 29, 2019
a6d131e
fixup! doc: merge bootstrap/README.md into BUILDING.md
rvagg Jun 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 125 additions & 55 deletions BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,30 +19,36 @@ file a new issue.
* [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)
* [Note about Python 2 and Python 3](#note-about-python-2-and-python-3)
* [Unix and macOS](#unix-and-macos)
* [Unix prerequisites](#unix-prerequisites)
* [macOS prerequisites](#macos-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-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)
* [`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](#eindows-2)
Comment thread
rvagg marked this conversation as resolved.
Outdated
* [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-4)
* [Unix/macOS](#unixmacos-3)
* [Windows](#windows-4)
* [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs)

Expand Down Expand Up @@ -215,34 +221,58 @@ 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.

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

#### Unix 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.
* Python 3.5, 3.6, and 3.7 are experimental.
* GNU Make 3.81 or newer
* Python (see note above)
* Python 2.7
* Python 3.5, 3.6, and 3.7 are experimental.

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`

On macOS, install the `Xcode Command Line Tools` by running
FreeBSD and OpenBSD users may also need to install `libexecinfo`.

#### macOS prerequisites

* Xcode Command Line Tools >= 8 for macOS
* Python (see note above)
* Python 2.7
* Python 3.5, 3.6, and 3.7 are experimental.

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
`make`.

If the path to your build directory contains a space, the build will likely
fail.

On FreeBSD and OpenBSD, you may also need:
* libexecinfo

#### Building Node.js

Note that if the path to your build directory contains a space, the build will
likely fail.

To build Node.js:

```console
Expand Down Expand Up @@ -461,7 +491,9 @@ $ backtrace

### Windows

Prerequisites:
#### Prerequisites

##### Option 1: Manual install

* [Python 2.7](https://www.python.org/downloads/)
* The "Desktop development with C++" workload from
Expand All @@ -476,17 +508,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:
Comment thread
rvagg marked this conversation as resolved.
Outdated

* 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.
Expand Down Expand Up @@ -523,55 +594,54 @@ $ ./android-configure /path/to/your/android-ndk
$ 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.

#### Default: `small-icu` (English only) support
### Default: `small-icu` (English only) support

By default, only English data is included, but
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
```

#### Building without Intl support
### Building without Intl support

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 @@ -580,7 +650,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 All @@ -591,7 +661,7 @@ 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.

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

From an already-unpacked ICU:
```console
Expand All @@ -608,7 +678,7 @@ From a tarball URL:
$ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
```

##### Windows
#### Windows

First unpack latest ICU to `deps/icu`
[icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`)
Expand Down
69 changes: 2 additions & 67 deletions tools/bootstrap/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,67 +1,2 @@
# Node.js Bootstrapping Guide

## Windows

A [Boxstarter][] 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] packages:
* [Git for Windows][] with the `git` and Unix tools added to the `PATH`
* [Python 3.x][] and [legacy Python][]
* [Visual Studio 2017 Build Tools][] with [Visual C++ workload][]
* [NetWide Assembler][]

To install Node.js prerequisites using [Boxstarter WebLauncher][], just open
[this link](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:
```console
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
```

Entire installation will take up about 10 GB of disk space.

### Why install two different versions of Python?
Python 2 will reach its _end-of-life_ at the end of 2019. Afterwards, the
interpreter will not get updates — no bugfixes, no security fixes, nothing. In
the interim, the Python ecosystem is abandoning 2.7 support.
https://python3statement.org/ In order to remain safe and current the Node.js
community is transitioning its Python code to Python 3. Having both versions of
Python in this bootstrap will allow developers and end users to test, benchmark,
and debug Node.js running on both versions to ensure a smooth and complete
transition before the yearend deadline.

## Linux

For building Node.js on Linux, following packages are required (note, that this
can vary from distribution to distribution):
* `git`
* `python`
* `gcc-c++` or `g++`
* `make`

To bootstrap Node.js on Linux, run in terminal:
* OpenSUSE: `sudo zypper install git python gcc-c++ make`
* Fedora: `sudo dnf install git python gcc-c++ make`
* Ubuntu, Debian: `sudo apt-get install git python g++ make`

## macOS

To install required tools on macOS, run in terminal:
```console
xcode-select --install
```

[Boxstarter]: http://boxstarter.org/
[Boxstarter WebLauncher]: http://boxstarter.org/WebLauncher
[Chocolatey]: https://chocolatey.org/
[Git for Windows]: https://chocolatey.org/packages/git
[Python 3.x]: https://chocolatey.org/packages/python
[legacy Python]: https://chocolatey.org/packages/python2
[Visual Studio 2017 Build Tools]: https://chocolatey.org/packages/visualstudio2017buildtools
[Visual C++ workload]: https://chocolatey.org/packages/visualstudio2017-workload-vctools
[NetWide Assembler]: https://chocolatey.org/packages/nasm
See the main project [README.md](../../README.md#boxstarter) for details on how
to use this script.
⚡