granicus.if.org Git - esp-idf/blob - docs/windows-setup.rst

   1 Set up of Toolchain for Windows
   2 *******************************
   3
   4 Step 1: Quick Steps
   5 ===================
   6
   7 Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide.
   8  You don't need to use this environment all the time (you can use Eclipse_ or some other front-end), but it runs behind the scenes.
   9
  10 The quick setup is to download the Windows all-in-one toolchain & MSYS zip file from dl.espressif.com:
  11
  12 https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20160816.zip
  13
  14 Unzip the zip file to C:\ and it will create an "msys32" directory with a pre-prepared environment.
  15
  16
  17 Alternative Step 1: Configure toolchain & environment from scratch
  18 ==================================================================
  19
  20 As an alternative to getting a pre-prepared environment, you can set up the environment from scratch:
  21
  22 * 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.)
  23
  24 * Run through the installer steps, and accept the "Run MSYS2 now" option at the end. A window will open with a MSYS2 terminal.
  25
  26 * The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't downloaded the ESP-IDF yet, that's OK - you can just `download that one file in Raw format from here <https://github.com/espressif/esp-idf/raw/master/tools/windows/windows_install_prerequisites.sh>`_. Save it somewhere on your computer.
  27
  28 * 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.
  29
  30 * If you use the 201602 MSYS2 installer, the first time you run ``windows_install_prerequisites.sh`` it will update the MSYS2 core system. At the end of this update, you will be prompted to close the MSYS2 terminal and re-open. When you re-open after the update, re-run ``windows_install_prerequisites.sh``. The next version of MSYS2 (after 201602) will not need this interim step.
  31
  32 * The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain.
  33
  34 Note: You may encounter a bug where svchost.exe uses 100% CPU in Windows after setup is finished, resulting in the ESP-IDF building very slowly. Terminating svchost.exe or restarting Windows will solve this problem.
  35
  36 Another Alternative Step 1: Just download a toolchain
  37 =====================================================
  38
  39 If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
  40
  41 https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-59.zip
  42
  43 If you followed one of the above options for Step 1, you won't need this download.
  44
  45 Important: Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).
  46
  47 Step 2: Getting the esp-idf repository from github
  48 ==================================================
  49
  50 Open an MSYS2 terminal window by running ``C:\msys32\msys2_shell.cmd``. The environment in this window is a bash shell.
  51
  52 Change to the directory you want to clone the SDK into by typing a command like this one: ``cd "C:/path/to/dir"`` (note the forward-slashes in the path). Then type ``git clone --recursive https://github.com/espressif/esp-idf.git``
  53
  54 If you'd rather use a Windows UI tool to manage your git repositories, this is also possible. A wide range are available.
  55
  56 *NOTE*: While cloning submodules, the ``git clone`` command may print some output starting ``': not a valid identifier...``. This is a `known issue`_ but the git clone still succeeds without any problems.
  57
  58 Step 3: Starting a project
  59 ==========================
  60
  61 ESP-IDF by itself does not build a binary to run on the ESP32. The binary "app" comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory on your computer.
  62
  63 The easiest way to start a project is to download the Getting Started project from github_.
  64
  65 The process is the same as for checking out the ESP-IDF from github. Change to the parent directory and run ``git clone https://github.com/espressif/esp-idf-template.git``.
  66
  67 **IMPORTANT:** The esp-idf build system does not support spaces in paths to esp-idf or to projects.
  68
  69 Step 4: Configuring the project
  70 ===============================
  71
  72 Open an MSYS2 terminal window by running ``C:\msys32\msys2_shell.cmd``. The environment in this window is a bash shell.
  73
  74 Type a command like this to set the path to ESP-IDF directory: ``export IDF_PATH="C:/path/to/esp-idf"`` (note the forward-slashes not back-slashes for the path). If you don't want to run this command every time you open an MSYS2 window, create a new file in ``C:/msys32/etc/profile.d/`` and paste this line in - then it will be run each time you open an MYS2 terminal.
  75
  76 Use ``cd`` to change to the project directory (not the ESP-IDF directory.) Type ``make menuconfig`` to configure your project, then ``make`` to build it, ``make clean`` to remove built files, and ``make flash`` to flash (use the menuconfig to set the serial port for flashing.)
  77
  78 If you'd like to use the Eclipse IDE instead of running ``make``, check out the Eclipse setup guide in this directory.
  79
  80
  81 .. _Eclipse: eclipse-setup.rst
  82 .. _MSYS2: https://msys2.github.io/
  83 .. _github: https://github.com/espressif/esp-idf-template
  84 .. _known issue: https://github.com/espressif/esp-idf/issues/11