From ab531c0b483a3ee52b81c9d3803c790d05130667 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 21 Sep 2017 11:15:09 +1000 Subject: [PATCH] doc: Add steps to update Windows environment installations --- docs/get-started/windows-setup-scratch.rst | 25 ++++++++++++++++++- docs/get-started/windows-setup.rst | 16 +++++++++++- .../windows/windows_install_prerequisites.sh | 6 ++--- 3 files changed, 42 insertions(+), 5 deletions(-) diff --git a/docs/get-started/windows-setup-scratch.rst b/docs/get-started/windows-setup-scratch.rst index b750a6c55..9b5d4603f 100644 --- a/docs/get-started/windows-setup-scratch.rst +++ b/docs/get-started/windows-setup-scratch.rst @@ -28,12 +28,18 @@ This process involves installing MSYS2_, then installing the MSYS2_ and Python p * The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain. -* During the initial update step, MSYS may update itself into a state where it can no longer operate. You may see errors like the following:: + +Troubleshooting +~~~~~~~~~~~~~~~ + +* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following:: *** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL. If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step. +* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_. + MSYS2 Mirrors in China ~~~~~~~~~~~~~~~~~~~~~~ @@ -88,5 +94,22 @@ Next Steps To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +.. _updating-existing-windows-environment: + +Updating The Environment +======================== + +When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment. + +Rather than setting up a new environment, you can update an existing Windows environment & toolchain: + +- Update IDF to the new version you want to use. +- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version. + +The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_. + +If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default. .. _MSYS2: https://msys2.github.io/ +.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/ +.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new diff --git a/docs/get-started/windows-setup.rst b/docs/get-started/windows-setup.rst index b5523e212..51e42b4db 100644 --- a/docs/get-started/windows-setup.rst +++ b/docs/get-started/windows-setup.rst @@ -11,7 +11,7 @@ Windows doesn't have a built-in "make" environment, so as well as installing the Toolchain Setup =============== -The quick setup is to download the Windows all-in-one toolchain & MSYS zip file from dl.espressif.com: +The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com: https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20170918.zip @@ -38,6 +38,20 @@ Next Steps To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +Updating The Environment +======================== + +When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one: + +- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``). +- Download the new precompiled environment using the steps above. +- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location). +- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``. +- You can now delete the ``C:\msys32_old`` directory if you no longer need it. + +You can have independent different MSYS2 environments on your system, as long as they are in different directories. + +There are :ref:`also steps to update the existing environment without downloading a new one `, although this is more complex. Related Documents ================= diff --git a/tools/windows/windows_install_prerequisites.sh b/tools/windows/windows_install_prerequisites.sh index 165977b0a..e3f6cf953 100644 --- a/tools/windows/windows_install_prerequisites.sh +++ b/tools/windows/windows_install_prerequisites.sh @@ -37,7 +37,7 @@ pacman --noconfirm -S --needed gettext-devel gcc git make ncurses-devel flex bis # Workaround for errors when running "git submodule" commands # See https://github.com/Alexpux/MSYS2-packages/issues/735 -rm /mingw32/bin/envsubst.exe +rm -f /mingw32/bin/envsubst.exe python -m pip install --upgrade pip @@ -49,6 +49,7 @@ echo "Downloading precompiled toolchain ${TOOLCHAIN_ZIP}..." cd ~ curl -LO --retry 10 http://dl.espressif.com/dl/${TOOLCHAIN_ZIP} cd /opt +rm -rf /opt/xtensa-esp32-elf # for upgrades unzip ~/${TOOLCHAIN_ZIP} rm ~/${TOOLCHAIN_ZIP} @@ -58,8 +59,7 @@ cat > /etc/profile.d/esp32_toolchain.sh << EOF export PATH="\$PATH:/opt/xtensa-esp32-elf/bin" EOF -# clean up pacman packages to save some disk space -pacman --noconfirm -R unzip +# clean up pacman package cache to save some disk space pacman --noconfirm -Scc cat << EOF