esp-idf/docs/windows-setup-scratch.rst

Set up Windows Toolchain from Scratch
*************************************

This is an **optional alternative to the normal Windows Guide**.

:doc:`See the main Windows setup page for the quickest and simplest Windows setup guide </windows-setup>`.

Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customise the install. The pre-built environment has been prepared by following these steps.

Configure toolchain & environment from scratch
==============================================

This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.

* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``.

* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**

* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.

  *(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)*

* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer.

* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.

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

     *** 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 Mirrors in China
~~~~~~~~~~~~~~~~~~~~~~

There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China.

To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (ie ``c:\msys2\etc\pacman.d``).

Add these lines at the top of ``mirrorlist.mingw32``::

  Server = http://mirrors.ustc.edu.cn/msys2/mingw/i686/
  Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686

Add these lines at the top of ``mirrorlist.msys``::

  Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch
  Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch


HTTP Proxy
~~~~~~~~~~

You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script::

    export http_proxy='http://http.proxy.server:PORT'

Or with credentials::

    export http_proxy='http://user:password@http.proxy.server:PORT'

Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS.

.. _MSYS2: https://msys2.github.io/