docs: fix instructions for building toolchain on macOS

Closes https://github.com/espressif/esp-idf/issues/503
Closes https://github.com/espressif/esp-idf/issues/2607

diff --git a/docs/en/get-started-cmake/linux-setup-scratch.rst b/docs/en/get-started-cmake/linux-setup-scratch.rst
index 57f461afc760d0101afd3d7dae08992438149cd0..7a1582ee7ac98bd86730687142b80d40c53e0f4d 100644 (file)
--- a/docs/en/get-started-cmake/linux-setup-scratch.rst
+++ b/docs/en/get-started-cmake/linux-setup-scratch.rst
@@ -51,12 +51,14 @@ Compile the Toolchain from Source
 
         TODO
 
-Download ``crosstool-NG`` and build it::
+Create the working directory and go into it::
 
-    cd ~/esp
-    git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
-    cd crosstool-NG
-    ./bootstrap && ./configure --enable-local && make install
+  mkdir -p ~/esp
+  cd ~/esp
+
+Download ``crosstool-NG`` and build it:
+
+.. include:: /_build/inc/scratch-build-code.inc
 
 Build the toolchain::
 

diff --git a/docs/en/get-started-cmake/macos-setup-scratch.rst b/docs/en/get-started-cmake/macos-setup-scratch.rst
index d75a1a8bb1b69a183c7219be510c817aa5c6e213..d74a35487554391c4000beca32ad5835e944b10e 100644 (file)
--- a/docs/en/get-started-cmake/macos-setup-scratch.rst
+++ b/docs/en/get-started-cmake/macos-setup-scratch.rst
@@ -14,6 +14,8 @@ MacPorts needs a full XCode installation, while homebrew only needs XCode comman
     .. _homebrew: https://brew.sh/
     .. _MacPorts: https://www.macports.org/install.php
 
+See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
+
 Install Prerequisites
 =====================
 
@@ -58,15 +60,16 @@ Mount it::
 
 Create a symlink to your work directory::
 
-    cd ~/esp
-    ln -s /Volumes/ctng crosstool-NG
+    mkdir -p ~/esp
+    ln -s /Volumes/ctng ~/esp/ctng-volume
+
+Go into the newly created directory::
+
+    cd ~/esp/ctng-volume
 
-Download ``crosstool-NG`` and build it::
+Download ``crosstool-NG`` and build it:
 
-    cd ~/esp
-    git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
-    cd crosstool-NG
-    ./bootstrap && ./configure --enable-local && make install
+.. include:: /_build/inc/scratch-build-code.inc
 
 Build the toolchain::
 
@@ -74,7 +77,7 @@ Build the toolchain::
     ./ct-ng build
     chmod -R u+w builds/xtensa-esp32-elf
 
-Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path-cmake>` to add the toolchain to your ``PATH``.
+Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path-cmake>` to add the toolchain to your ``PATH``.
 
 
 Next Steps

diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst
index 40b5e432faaddae6f0d457465288d5be78f7c6c5..b14530f6d4a7006b390df0eda2ac5214a4bd2413 100644 (file)
--- a/docs/en/get-started/linux-setup-scratch.rst
+++ b/docs/en/get-started/linux-setup-scratch.rst
@@ -2,8 +2,9 @@
 Setup Linux Toolchain from Scratch
 **********************************
 
-The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
-
+.. note::
+    
+    Standard process for installing the toolchain is described :doc:`here <linux-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
 
 Install Prerequisites
 =====================
@@ -49,6 +50,11 @@ Compile the Toolchain from Source
 
         TODO
 
+Create the working directory and go into it::
+
+  mkdir -p ~/esp
+  cd ~/esp
+
 Download ``crosstool-NG`` and build it:
 
 .. include:: /_build/inc/scratch-build-code.inc

diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst
index f743d99952ae4e02f265d9c5cc9e4bee7f9e4e65..0cf8130bf3476546d370f8791515855373a9af94 100644 (file)
--- a/docs/en/get-started/macos-setup-scratch.rst
+++ b/docs/en/get-started/macos-setup-scratch.rst
@@ -2,6 +2,10 @@
 Setup Toolchain for Mac OS from Scratch
 ***************************************
 
+.. note::
+    
+    Standard process for installing the toolchain is described :doc:`here <macos-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
+
 Install Prerequisites
 =====================
 
@@ -41,8 +45,12 @@ Mount it::
 
 Create a symlink to your work directory::
 
-    cd ~/esp
-    ln -s /Volumes/ctng crosstool-NG
+    mkdir -p ~/esp
+    ln -s /Volumes/ctng ~/esp/ctng-volume
+
+Go into the newly created directory::
+
+    cd ~/esp/ctng-volume
 
 Download ``crosstool-NG`` and build it:
 
@@ -54,7 +62,7 @@ Build the toolchain::
     ./ct-ng build
     chmod -R u+w builds/xtensa-esp32-elf
 
-Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
+Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
 
 
 Next Steps

diff --git a/docs/gen-toolchain-links.py b/docs/gen-toolchain-links.py
index 10c2aeef9713b189e482c6a63f26fb758b1b8292..aa824b93c1299d4d182d6c6050c95238e45d2742 100644 (file)
--- a/docs/gen-toolchain-links.py
+++ b/docs/gen-toolchain-links.py
@@ -43,7 +43,6 @@ def main():
     scratch_build_code_linux_macos = """
 ::
 
-    cd ~/esp
     git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
     cd crosstool-NG
     ./bootstrap && ./configure --enable-local && make install