doc: merge bootstrap/README.md into BUILDING.mdrvagg/combine-bootstrap-and-building-docs

2 files changed, 122 insertions, 124 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.
diff --git a/tools/bootstrap/README.md b/tools/bootstrap/README.md
index df69a540c1..4098b5c3a2 100644
--- a/tools/bootstrap/README.md
+++ b/tools/bootstrap/README.md
@@ -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.