doc: Add steps to update Windows environment installations

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

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 <updating-existing-windows-environment>`, although this is more complex.
 
 Related Documents
 =================

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