From 91fa1764e50c45a6dbede417b3d5ec83ca1e99d2 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Wed, 29 Aug 2018 21:30:03 +0800 Subject: [PATCH] docs: generate toolchain download links --- docs/conf_common.py | 6 ++ docs/en/get-started/linux-setup-scratch.rst | 7 +- docs/en/get-started/linux-setup.rst | 18 +++-- docs/en/get-started/macos-setup-scratch.rst | 7 +- docs/en/get-started/macos-setup.rst | 10 +-- docs/en/get-started/windows-setup-scratch.rst | 4 +- docs/gen-toolchain-links.py | 78 +++++++++++++++++++ .../zh_CN/get-started/linux-setup-scratch.rst | 7 +- docs/zh_CN/get-started/linux-setup.rst | 18 +++-- .../zh_CN/get-started/macos-setup-scratch.rst | 7 +- docs/zh_CN/get-started/macos-setup.rst | 10 +-- tools/toolchain_versions.mk | 1 + 12 files changed, 130 insertions(+), 43 deletions(-) create mode 100644 docs/gen-toolchain-links.py diff --git a/docs/conf_common.py b/docs/conf_common.py index 1ff9d351dd..2832f83f46 100644 --- 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 72756852f5..40b5e432fa 100644 --- 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 1cddf42844..00d024ac5c 100644 --- 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: diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index 7311227233..f743d99952 100644 --- 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 00e5be4315..2708dc6e66 100644 --- 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 4c772eeb3f..fc64e2a233 100644 --- 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 index 0000000000..10c2aeef97 --- /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 ") + 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 732a37e4eb..3610ce06f0 100644 --- 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 28b4b37706..d1d658924e 100644 --- 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: diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst index 5b0ab044c5..30d7d7f738 100644 --- 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 255a792a74..781a6d7465 100644 --- 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 c1a7aa059d..cf74ef5ec6 100644 --- 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