From 870fb584cd03e54a07c9e32a31e8120ffa4ed909 Mon Sep 17 00:00:00 2001 From: Swagat Konchada Date: Tue, 28 Jan 2020 00:58:07 +0000 Subject: [PATCH 1/3] doc: add note in BUILDING.md about running `make distclean` Fixes: https://github.com/nodejs/node/issues/28675 --- BUILDING.md | 117 +++++++++++++++++++++++++++++++++------------------- 1 file changed, 74 insertions(+), 43 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 448b7711b4d4cc..6432ba598fc978 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -10,49 +10,53 @@ 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) - * [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-1) - * [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) - * [Option 1: Manual install](#option-1-manual-install) - * [Option 2: Automated install with Boxstarter](#option-2-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) - * [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) - * [Trimmed: `small-icu` (English only) support](#trimmed-small-icu-english-only-support) - * [Unix/macOS](#unixmacos-1) - * [Windows](#windows-2) - * [Building without Intl support](#building-without-intl-support) - * [Unix/macOS](#unixmacos-2) - * [Windows](#windows-3) - * [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-4) -* [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-5) -* [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs) +* [Building Node.js](#building-nodejs) + * [Table of Contents](#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) + * [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-1) + * [Running Tests](#running-tests) + * [Running Coverage](#running-coverage) + * [Building the documentation](#building-the-documentation) + * [Building a debug build](#building-a-debug-build) + * [Cleaning up the build](#cleaning-up-the-build) + * [Windows](#windows) + * [Prerequisites](#prerequisites) + * [Option 1: Manual install](#option-1-manual-install) + * [Option 2: Automated install with Boxstarter](#option-2-automated-install-with-boxstarter) + * [Building Node.js](#building-nodejs-2) + * [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os) + * [Troubleshooting Build failures](#troubleshooting-build-failures) + * [`Intl` (ECMA-402) support](#intl-ecma-402-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) + * [Trimmed: `small-icu` (English only) support](#trimmed-small-icu-english-only-support) + * [Unix/macOS](#unixmacos-1) + * [Windows](#windows-2) + * [Building without Intl support](#building-without-intl-support) + * [Unix/macOS](#unixmacos-2) + * [Windows](#windows-3) + * [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-4) + * [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-5) + * [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs) ## Supported platforms @@ -488,6 +492,27 @@ $ gdb /opt/node-debug/node core.node.8.1535359906 $ backtrace ``` +#### Cleaning up the build + +Always try + +``` console +$ make clean +$ make -j4 +``` + +first, to clean the current build and build again. + +For a more thorough clean up, try + +``` console +$ make distclean +$ ./configure +$ make -j4 +``` +```distclean``` should be followed by ```./configure```, and therefore takes +significantly longer to rebuild than using ```make clean```. + ### Windows #### Prerequisites @@ -596,6 +621,12 @@ $ ./android-configure /path/to/your/android-ndk $ make ``` +### Troubleshooting Build failures +Error: ``` fatal error: 'src/snapshot/macros.h' file not found``` + +This is probably due to a stale build, and should be fixed with a full clean. +Refer to [Cleaning up the build](#cleaning-up-the-build) + ## `Intl` (ECMA-402) support [Intl](https://github.com/nodejs/node/blob/master/doc/api/intl.md) support is From 55ff98ffce6160012d2c617507d537cd58e2cfba Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 1 Feb 2020 18:40:40 -0800 Subject: [PATCH 2/3] fixup! doc: add note in BUILDING.md about running `make distclean` --- BUILDING.md | 92 ++++++++++++++++++++++++++--------------------------- 1 file changed, 45 insertions(+), 47 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 6432ba598fc978..c054335f962b9b 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -10,53 +10,51 @@ file a new issue. ## Table of Contents -* [Building Node.js](#building-nodejs) - * [Table of Contents](#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) - * [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-1) - * [Running Tests](#running-tests) - * [Running Coverage](#running-coverage) - * [Building the documentation](#building-the-documentation) - * [Building a debug build](#building-a-debug-build) - * [Cleaning up the build](#cleaning-up-the-build) - * [Windows](#windows) - * [Prerequisites](#prerequisites) - * [Option 1: Manual install](#option-1-manual-install) - * [Option 2: Automated install with Boxstarter](#option-2-automated-install-with-boxstarter) - * [Building Node.js](#building-nodejs-2) - * [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os) - * [Troubleshooting Build failures](#troubleshooting-build-failures) - * [`Intl` (ECMA-402) support](#intl-ecma-402-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) - * [Trimmed: `small-icu` (English only) support](#trimmed-small-icu-english-only-support) - * [Unix/macOS](#unixmacos-1) - * [Windows](#windows-2) - * [Building without Intl support](#building-without-intl-support) - * [Unix/macOS](#unixmacos-2) - * [Windows](#windows-3) - * [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-4) - * [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-5) - * [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) + * [Unix prerequisites](#unix-prerequisites) + * [macOS prerequisites](#macos-prerequisites) + * [Building Node.js](#building-nodejs-1) + * [Running Tests](#running-tests) + * [Running Coverage](#running-coverage) + * [Building the documentation](#building-the-documentation) + * [Building a debug build](#building-a-debug-build) + * [Cleaning up the build](#cleaning-up-the-build) + * [Windows](#windows) + * [Prerequisites](#prerequisites) + * [Option 1: Manual install](#option-1-manual-install) + * [Option 2: Automated install with Boxstarter](#option-2-automated-install-with-boxstarter) + * [Building Node.js](#building-nodejs-2) + * [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os) + * [Troubleshooting Build failures](#troubleshooting-build-failures) +* [`Intl` (ECMA-402) support](#intl-ecma-402-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) + * [Trimmed: `small-icu` (English only) support](#trimmed-small-icu-english-only-support) + * [Unix/macOS](#unixmacos-1) + * [Windows](#windows-2) + * [Building without Intl support](#building-without-intl-support) + * [Unix/macOS](#unixmacos-2) + * [Windows](#windows-3) + * [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-4) +* [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-5) +* [Note for downstream distributors of Node.js](#note-for-downstream-distributors-of-nodejs) ## Supported platforms From bb335c732ef9779fa5747eb5b6de9439ff8e141a Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 1 Feb 2020 19:00:44 -0800 Subject: [PATCH 3/3] fixup! fixup! doc: add note in BUILDING.md about running `make distclean` --- BUILDING.md | 37 ++++++++++--------------------------- 1 file changed, 10 insertions(+), 27 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index c054335f962b9b..a8499c0bc521a9 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -28,14 +28,13 @@ file a new issue. * [Running Coverage](#running-coverage) * [Building the documentation](#building-the-documentation) * [Building a debug build](#building-a-debug-build) - * [Cleaning up the build](#cleaning-up-the-build) + * [Troubleshooting Unix and macOS builds](#troubleshooting-unix-and-macos-builds) * [Windows](#windows) * [Prerequisites](#prerequisites) * [Option 1: Manual install](#option-1-manual-install) * [Option 2: Automated install with Boxstarter](#option-2-automated-install-with-boxstarter) * [Building Node.js](#building-nodejs-2) * [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os) - * [Troubleshooting Build failures](#troubleshooting-build-failures) * [`Intl` (ECMA-402) support](#intl-ecma-402-support) * [Build with full ICU support (all locales supported by ICU)](#build-with-full-icu-support-all-locales-supported-by-icu) * [Unix/macOS](#unixmacos) @@ -490,26 +489,16 @@ $ gdb /opt/node-debug/node core.node.8.1535359906 $ backtrace ``` -#### Cleaning up the build +#### Troubleshooting Unix and macOS builds -Always try - -``` console -$ make clean -$ make -j4 -``` - -first, to clean the current build and build again. - -For a more thorough clean up, try - -``` console -$ make distclean -$ ./configure -$ make -j4 -``` -```distclean``` should be followed by ```./configure```, and therefore takes -significantly longer to rebuild than using ```make clean```. +Stale builds can sometimes result in `file not found` errors while building. +This and some other problems can be resolved with `make distclean`. The +`distclean` recipe aggressively removes build artifacts. You will need to +build again (`make -j4`). Since all build artifacts have been removed, this +rebuild may take a lot more time than previous builds. Additionally, +`distclean` removes the file that stores the results of `./configure`. If you +ran `./configure` with non-default options (such as `--debug`), you will need +to run it again before invoking `make -j4`. ### Windows @@ -619,12 +608,6 @@ $ ./android-configure /path/to/your/android-ndk $ make ``` -### Troubleshooting Build failures -Error: ``` fatal error: 'src/snapshot/macros.h' file not found``` - -This is probably due to a stale build, and should be fixed with a full clean. -Refer to [Cleaning up the build](#cleaning-up-the-build) - ## `Intl` (ECMA-402) support [Intl](https://github.com/nodejs/node/blob/master/doc/api/intl.md) support is