docs: generate toolchain download links

2018-08-29 21:30:03 +08:00 · 2018-08-29 21:30:03 +08:00 · 91fa1764e5
commit 91fa1764e5
--- 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
 # 
--- 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::

--- 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::
+1.  Download this file, then extract it in ``~/esp`` directory:

-        mkdir -p ~/esp
-        cd ~/esp
-        tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+    - for 64-bit Linux:
+
+      .. include:: /_build/inc/unpack-code-linux64.inc
+
+    - for 32-bit Linux:
+
+      .. include:: /_build/inc/unpack-code-linux32.inc

 .. _setup-linux-toolchain-add-it-to-path:

--- 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::

--- 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:

--- 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::

--- a/docs/gen-toolchain-links.py
+++ 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()
--- 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

 编译工具链::

--- 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`` 目录： ::
+1. 下载完成后，将它解压到 ``~/esp`` 目录： :

-        mkdir -p ~/esp
-        cd ~/esp
-        tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+    - 64-bit Linux:
+
+      .. include:: /_build/inc/unpack-code-linux64.inc
+
+    - 32-bit Linux:
+
+      .. include:: /_build/inc/unpack-code-linux32.inc

 .. _setup-linux-toolchain-add-it-to-path:  

--- 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

 编译工具链::

--- 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:

--- 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