1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
plus some minor tweaks

PR-URL: https://github.com/nodejs/node/pull/28465
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Bartosz Sosnowski <bartosz@janeasystems.com>
This commit is contained in:
Rod Vagg 2019-06-28 18:01:02 +10:00
parent 1095635a8a
commit b12528f349
No known key found for this signature in database
GPG Key ID: C273792F7D83545D
2 changed files with 128 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
BUILDING.md
View File

@ -19,30 +19,36 @@ file a new issue.
* [OpenSSL asm support](#openssl-asm-support) * [OpenSSL asm support](#openssl-asm-support)
* [Previous versions of this document](#previous-versions-of-this-document) * [Previous versions of this document](#previous-versions-of-this-document)
* [Building Node.js on supported platforms](#building-nodejs-on-supported-platforms) * [Building Node.js on supported platforms](#building-nodejs-on-supported-platforms)
* [Unix/macOS](#unixmacos) * [Note about Python 2 and Python 3](#note-about-python-2-and-python-3)
* [Prerequisites](#prerequisites) * [Unix and macOS](#unix-and-macos)
* [Unix prerequisites](#unix-prerequisites)
* [macOS prerequisites](#macos-prerequisites)
* [Building Node.js](#building-nodejs) * [Building Node.js](#building-nodejs)
* [Running Tests](#running-tests) * [Running Tests](#running-tests)
* [Running Coverage](#running-coverage) * [Running Coverage](#running-coverage)
* [Building the documentation](#building-the-documentation) * [Building the documentation](#building-the-documentation)
* [Building a debug build](#building-a-debug-build) * [Building a debug build](#building-a-debug-build)
* [Windows](#windows) * [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) * [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os)
* [`Intl` (ECMA-402) support](#intl-ecma-402-support) * [`Intl` (ECMA-402) support](#intl-ecma-402-support)
* [Default: `small-icu` (English only) support](#default-small-icu-english-only-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) * [Build with full ICU support (all locales supported by ICU)](#build-with-full-icu-support-all-locales-supported-by-icu)
* [Unix/macOS](#unixmacos-1) * [Unix/macOS](#unixmacos)
* [Windows](#windows-1) * [Windows](#windows-1)
* [Building without Intl support](#building-without-intl-support) * [Building without Intl support](#building-without-intl-support)
* [Unix/macOS](#unixmacos-2) * [Unix/macOS](#unixmacos-1)
* [Windows](#windows-2) * [Windows](#windows-2)
* [Use existing installed ICU (Unix/macOS only)](#use-existing-installed-icu-unixmacos-only) * [Use existing installed ICU (Unix/macOS only)](#use-existing-installed-icu-unixmacOS-only)
* [Build with a specific ICU](#build-with-a-specific-icu) * [Build with a specific ICU](#build-with-a-specific-icu)
* [Unix/macOS](#unixmacos-3) * [Unix/macOS](#unixmacos-2)
* [Windows](#windows-3) * [Windows](#windows-3)
* [Building Node.js with FIPS-compliant OpenSSL](#building-nodejs-with-fips-compliant-openssl) * [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) * [Building Node.js with external core modules](#building-nodejs-with-external-core-modules)
* [Unix/macOS](#unixmacos-4) * [Unix/macOS](#unixmacos-3)
* [Windows](#windows-4) * [Windows](#windows-4)
* [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs) * [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs)
@ -215,34 +221,58 @@ Consult previous versions of this document for older versions of Node.js:
## Building Node.js on supported platforms ## Building Node.js on supported platforms
The [bootstrapping guide](https://github.com/nodejs/node/blob/master/tools/bootstrap/README.md) ### Note about Python 2 and Python 3
explains how to install all prerequisites.
### 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 * `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 * GNU Make 3.81 or newer
* Python (see note above)
* Python 2.7
* Python 3.5, 3.6, and 3.7 are experimental.
On macOS, install the `Xcode Command Line Tools` by running 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`.
#### 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 `xcode-select --install`. Alternatively, if you already have the full Xcode
installed, you can find them under the menu `Xcode -> Open Developer Tool -> installed, you can find them under the menu `Xcode -> Open Developer Tool ->
More Developer Tools...`. This step will install `clang`, `clang++`, and More Developer Tools...`. This step will install `clang`, `clang++`, and
`make`. `make`.
#### Building Node.js
If the path to your build directory contains a space, the build will likely If the path to your build directory contains a space, the build will likely
fail. fail.
On FreeBSD and OpenBSD, you may also need:
* libexecinfo
#### Building Node.js
To build Node.js: To build Node.js:
```console ```console
@ -461,7 +491,9 @@ $ backtrace
### Windows ### Windows
Prerequisites: #### Prerequisites
##### Option 1: Manual install
* [Python 2.7](https://www.python.org/downloads/) * [Python 2.7](https://www.python.org/downloads/)
* The "Desktop development with C++" workload from * The "Desktop development with C++" workload from
@ -476,9 +508,14 @@ Prerequisites:
If not installed in the default location, it needs to be manually added 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 to `PATH`. A build with the `openssl-no-asm` option does not need this, nor
does a build targeting ARM64 Windows. 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 to build the MSI installer package:
* **Optional** Requirements for compiling for Windows 10 on ARM (ARM64):
* 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 * ARM64 Windows build machine
* Due to a GYP limitation, this is required to run compiled code * Due to a GYP limitation, this is required to run compiled code
generation tools (like V8's builtins and mksnapshot tools) generation tools (like V8's builtins and mksnapshot tools)
@ -488,6 +525,42 @@ Prerequisites:
* Visual C++ ATL for ARM64 * Visual C++ ATL for ARM64
* Windows 10 SDK 10.0.17763.0 or newer * 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, If the path to your build directory contains a space or a non-ASCII character,
the build will likely fail. the build will likely fail.
@ -523,55 +596,54 @@ $ ./android-configure /path/to/your/android-ndk
$ make $ make
``` ```
## `Intl` (ECMA-402) support
### `Intl` (ECMA-402) support
[Intl](https://github.com/nodejs/node/blob/master/doc/api/intl.md) support is [Intl](https://github.com/nodejs/node/blob/master/doc/api/intl.md) support is
enabled by default, with English data only. 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 By default, only English data is included, but
the full `Intl` (ECMA-402) APIs. It does not need to download the full `Intl` (ECMA-402) APIs. It does not need to download
any dependencies to function. You can add full any dependencies to function. You can add full
data at runtime. 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 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 ICU in `deps/icu`. (The embedded `small-icu` included in the default
Node.js source does not include all locales.) Node.js source does not include all locales.)
##### Unix/macOS #### Unix/macOS
```console ```console
$ ./configure --with-intl=full-icu --download=all $ ./configure --with-intl=full-icu --download=all
``` ```
##### Windows #### Windows
```console ```console
> .\vcbuild full-icu download-all > .\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 The `Intl` object will not be available, nor some other APIs such as
`String.normalize`. `String.normalize`.
##### Unix/macOS #### Unix/macOS
```console ```console
$ ./configure --without-intl $ ./configure --without-intl
``` ```
##### Windows #### Windows
```console ```console
> .\vcbuild without-intl > .\vcbuild without-intl
``` ```
#### Use existing installed ICU (Unix/macOS only) ### Use existing installed ICU (Unix/macOS only)
```console ```console
$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu $ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
@ -580,7 +652,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 If you are cross-compiling, your `pkg-config` must be able to supply a path
that works for both your host and target environments. 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 You can find other ICU releases at
[the ICU homepage](http://icu-project.org/download). [the ICU homepage](http://icu-project.org/download).
@ -591,7 +663,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 the help for the `--with-icu-source` option. A warning will be printed
during configuration if the ICU version is too old. during configuration if the ICU version is too old.
##### Unix/macOS #### Unix/macOS
From an already-unpacked ICU: From an already-unpacked ICU:
```console ```console
@ -608,7 +680,7 @@ From a tarball URL:
$ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz $ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
``` ```
##### Windows #### Windows
First unpack latest ICU to `deps/icu` First unpack latest ICU to `deps/icu`
[icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`) [icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`)

69
tools/bootstrap/README.md
View File

@ -1,67 +1,2 @@
# Node.js Bootstrapping Guide See the main project [README.md](../../README.md#boxstarter) for details on how
to use this script.
## 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