docs: generate toolchain download links

diff --git a/docs/conf_common.py b/docs/conf_common.py
index 1ff9d351dd45871d8499c8a678c470d9f11870b4..2832f83f468a700b926a1c1d192d757626b818e6 100644 (file)
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -89,6 +89,12 @@ def generate_version_specific_includes(app):
     call_with_python('../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir))
     copy_if_modified(version_tmpdir, '{}/inc'.format(builddir))
 
+# Generate toolchain download links
+print("Generating toolchain download links")
+base_url = 'https://dl.espressif.com/dl/'
+toolchain_tmpdir = '{}/toolchain_inc'.format(builddir)
+call_with_python('../gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(base_url, toolchain_tmpdir))
+copy_if_modified(toolchain_tmpdir, '{}/inc'.format(builddir))
 
 # http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
 # 

diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst
index 72756852f52f8311e72e81540b97419e24003888..40b5e432faaddae6f0d457465288d5be78f7c6c5 100644 (file)
--- a/docs/en/get-started/linux-setup-scratch.rst
+++ b/docs/en/get-started/linux-setup-scratch.rst
@@ -49,12 +49,9 @@ Compile the Toolchain from Source
 
         TODO
 
-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::
 

diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst
index 1cddf4284468be31f3f7e31c829578fd3d04bcc5..00d024ac5ce44993a48b915c8a312b29d5b94daa 100644 (file)
--- a/docs/en/get-started/linux-setup.rst
+++ b/docs/en/get-started/linux-setup.rst
@@ -29,21 +29,27 @@ To compile with ESP-IDF you need to get the following packages:
 Toolchain Setup
 ===============
 
+.. include:: /_build/inc/download-links.inc
+
 ESP32 toolchain for Linux is available for download from Espressif website:
 
 - for 64-bit Linux:
 
-  https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+  |download_link_linux64|
 
 - for 32-bit Linux:
 
-  https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
+  |download_link_linux32|
+
+1.  Download this file, then extract it in ``~/esp`` directory:
+
+    - for 64-bit Linux:
+
+      .. include:: /_build/inc/unpack-code-linux64.inc
 
-1.  Download this file, then extract it in ``~/esp`` directory::
+    - for 32-bit Linux:
 
-        mkdir -p ~/esp
-        cd ~/esp
-        tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+      .. include:: /_build/inc/unpack-code-linux32.inc
 
 .. _setup-linux-toolchain-add-it-to-path:
 

diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst
index 731122723323d9d0c537070cf2aa9ecbd92c6ace..f743d99952ae4e02f265d9c5cc9e4bee7f9e4e65 100644 (file)
--- a/docs/en/get-started/macos-setup-scratch.rst
+++ b/docs/en/get-started/macos-setup-scratch.rst
@@ -44,12 +44,9 @@ Create a symlink to your work directory::
     cd ~/esp
     ln -s /Volumes/ctng crosstool-NG
 
-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::
 

diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst
index 00e5be4315c6bce244c8180c57466360fd4fc3b9..2708dc6e661933d713e4acb4337ec39d85cb55cd 100644 (file)
--- a/docs/en/get-started/macos-setup.rst
+++ b/docs/en/get-started/macos-setup.rst
@@ -17,15 +17,15 @@ Install Prerequisites
 Toolchain Setup
 ===============
 
+.. include:: /_build/inc/download-links.inc
+
 ESP32 toolchain for macOS is available for download from Espressif website:
 
-https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
+|download_link_osx|
 
-Download this file, then extract it in ``~/esp`` directory::
+Download this file, then extract it in ``~/esp`` directory:
 
-    mkdir -p ~/esp
-    cd ~/esp
-    tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
+.. include:: /_build/inc/unpack-code-osx.inc
 
 .. _setup-macos-toolchain-add-it-to-path:
 

diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst
index 4c772eeb3fca62bd2f226c2b5dbffc176fc91fd5..fc64e2a23343a2e740303b6f646d18ba9b60911b 100644 (file)
--- a/docs/en/get-started/windows-setup-scratch.rst
+++ b/docs/en/get-started/windows-setup-scratch.rst
@@ -76,9 +76,11 @@ Add this line to ``/etc/profile`` in the MSYS directory in order to permanently
 Alternative Setup: Just download a toolchain
 ============================================
 
+.. include:: /_build/inc/download-links.inc
+
 If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
 
-https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
+|download_link_win32|
 
 .. note::
 

diff --git a/docs/gen-toolchain-links.py b/docs/gen-toolchain-links.py
new file mode 100644 (file)
index 0000000..10c2aee
--- /dev/null
+++ b/docs/gen-toolchain-links.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# This script generates toolchain download links and toolchain unpacking
+# code snippets based on information found in $IDF_PATH/tools/toolchain_versions.mk
+#
+
+from __future__ import print_function
+
+import sys
+import os
+
+def main():
+    if len(sys.argv) != 4:
+        print("Usage: gen-toolchain-links.py <versions file> <base download URL> <output directory>")
+        sys.exit(1)
+
+    out_dir = sys.argv[3]
+    if not os.path.exists(out_dir):
+        print("Creating directory %s" % out_dir)
+        os.mkdir(out_dir)
+
+    base_url = sys.argv[2]
+
+    versions_file = sys.argv[1]
+    version_vars = {}
+    with open(versions_file) as f:
+        for line in f:
+            name, var = line.partition("=")[::2]
+            version_vars[name.strip()] = var.strip()
+
+    gcc_version = version_vars["CURRENT_TOOLCHAIN_GCC_VERSION"]
+    toolchain_desc = version_vars["CURRENT_TOOLCHAIN_COMMIT_DESC_SHORT"]
+
+    unpack_code_linux_macos = """
+::
+
+    mkdir -p ~/esp
+    cd ~/esp
+    tar -x{}f ~/Downloads/{}
+"""
+
+    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
+"""
+
+    platform_info = [ ["linux64", "tar.gz", "z", unpack_code_linux_macos],
+                      ["linux32", "tar.gz", "z", unpack_code_linux_macos],
+                      ["osx", "tar.gz", "z", unpack_code_linux_macos],
+                      ["win32", "zip", None, None]]
+
+    with open(os.path.join(out_dir, 'download-links.inc'), "w") as links_file:
+        for p in platform_info:
+            platform_name = p[0]
+            extension = p[1]
+            unpack_cmd = p[2]
+            unpack_code = p[3]
+
+            archive_name = 'xtensa-esp32-elf-{}-{}-{}.{}'.format(
+                    platform_name, toolchain_desc, gcc_version, extension)
+            
+            print('.. |download_link_{}| replace:: {}{}'.format(
+                platform_name, base_url, archive_name), file=links_file)
+
+            if unpack_code is not None:
+                with open(os.path.join(out_dir, 'unpack-code-%s.inc' % platform_name), "w") as f:
+                    print(unpack_code.format(unpack_cmd, archive_name), file=f)
+
+    with open(os.path.join(out_dir, 'scratch-build-code.inc'), "w") as code_file:
+        print(scratch_build_code_linux_macos, file=code_file)
+
+if __name__ == "__main__":
+    main()

diff --git a/docs/zh_CN/get-started/linux-setup-scratch.rst b/docs/zh_CN/get-started/linux-setup-scratch.rst
index 732a37e4eb045df9d511aa780e50c2dceab48bef..3610ce06f01c44c634f49c7b948186163ad09b81 100644 (file)
--- a/docs/zh_CN/get-started/linux-setup-scratch.rst
+++ b/docs/zh_CN/get-started/linux-setup-scratch.rst
@@ -48,12 +48,9 @@
 
         TODO
 
-下载 ``crosstool-NG`` 然后编译::
+下载 ``crosstool-NG`` 然后编译:
 
-    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
 
 编译工具链::
 

diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst
index 28b4b3770628b87d48a6f7d220652609ce16a617..d1d658924ece0315b00f28f8aff135e06ba94072 100644 (file)
--- a/docs/zh_CN/get-started/linux-setup.rst
+++ b/docs/zh_CN/get-started/linux-setup.rst
@@ -30,21 +30,27 @@ Linux 平台工具链的标准设置
 工具链的设置
 ===============
 
+.. include:: /_build/inc/download-links.inc
+
 Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
 
 - 64-bit Linux：
 
-  https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+  |download_link_linux64|
 
 - 32-bit Linux：
 
-  https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
+  |download_link_linux32|
+
+1. 下载完成后，将它解压到 ``~/esp`` 目录： :
+
+    - 64-bit Linux:
+
+      .. include:: /_build/inc/unpack-code-linux64.inc
 
-1. 下载完成后，将它解压到 ``~/esp`` 目录： ::
+    - 32-bit Linux:
 
-        mkdir -p ~/esp
-        cd ~/esp
-        tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+      .. include:: /_build/inc/unpack-code-linux32.inc
 
 .. _setup-linux-toolchain-add-it-to-path:  
 

diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst
index 5b0ab044c5915352ce455c9abad5fcd76c55169f..30d7d7f738d9e3c0e7d7b8bb05467b904d5eaa61 100644 (file)
--- a/docs/zh_CN/get-started/macos-setup-scratch.rst
+++ b/docs/zh_CN/get-started/macos-setup-scratch.rst
@@ -44,12 +44,9 @@
     cd ~/esp
     ln -s /Volumes/ctng crosstool-NG
 
-下载 ``crosstool-NG`` 然后编译::
+下载 ``crosstool-NG`` 然后编译:
 
-    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
 
 编译工具链::
 

diff --git a/docs/zh_CN/get-started/macos-setup.rst b/docs/zh_CN/get-started/macos-setup.rst
index 255a792a74b3baab72afd31cfffcc6622c514b10..781a6d7465a42996d6904a07d60bdf07ced40093 100644 (file)
--- a/docs/zh_CN/get-started/macos-setup.rst
+++ b/docs/zh_CN/get-started/macos-setup.rst
@@ -19,15 +19,15 @@
 安装工具链
 ===============
 
+.. include:: /_build/inc/download-links.inc
+
 Mac OS 版本的 ESP32 工具链可以从以下地址下载：
 
-https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-75-gbaf03c2-5.2.0.tar.gz
+|download_link_osx|
 
-下载压缩文件之后，解压到 ``~/esp`` 目录中::
+下载压缩文件之后，解压到 ``~/esp`` 目录中:
 
-    mkdir -p ~/esp
-    cd ~/esp
-    tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-75-gbaf03c2-5.2.0.tar.gz
+.. include:: /_build/inc/unpack-code-osx.inc
 
 .. _setup-macos-toolchain-add-it-to-path:
 

diff --git a/tools/toolchain_versions.mk b/tools/toolchain_versions.mk
index c1a7aa059db7a0c5a6aa232a4c720e336942fa51..cf74ef5ec62db46fc5fc1b7cc2121094743b8b0b 100644 (file)
--- a/tools/toolchain_versions.mk
+++ b/tools/toolchain_versions.mk
@@ -2,4 +2,5 @@ SUPPORTED_TOOLCHAIN_COMMIT_DESC = crosstool-ng-1.22.0-80-g6c4433a
 SUPPORTED_TOOLCHAIN_GCC_VERSIONS = 5.2.0
 
 CURRENT_TOOLCHAIN_COMMIT_DESC = crosstool-ng-1.22.0-80-g6c4433a
+CURRENT_TOOLCHAIN_COMMIT_DESC_SHORT = 1.22.0-80-g6c4433a
 CURRENT_TOOLCHAIN_GCC_VERSION = 5.2.0