1********************************************
2Setup Windows Toolchain from Scratch
3********************************************
4
5:link_to_translation:`zh_CN:[中文]`
6
7This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer <windows-setup>` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install.
8
9To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
10
11.. note::
12   The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
13
14.. _get-esp-idf-windows-command-line:
15
16Get ESP-IDF
17===========
18
19.. note::
20
21        Previous versions of ESP-IDF used the **MSYS2 bash terminal** command line. The current cmake-based build system can run in the regular **Windows Command Prompt** which is used here.
22
23        If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below.
24
25Open Command Prompt and run the following commands:
26
27.. include-build-file:: inc/git-clone-windows.inc
28
29ESP-IDF will be downloaded into ``%userprofile%\esp\esp-idf``.
30
31Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
32
33.. include-build-file:: inc/git-clone-notes.inc
34
35.. note::
36
37    Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
38
39        cd esp-idf
40        git submodule update --init
41
42
43Tools
44=====
45
46CMake
47^^^^^
48
49Download the latest stable release of CMake_ for Windows and run the installer.
50
51When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
52
53Ninja build
54^^^^^^^^^^^
55
56.. note::
57    Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
58
59Download the Ninja_ latest stable Windows release from the (`download page <ninja-dl_>`_).
60
61The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then :ref:`added to your Path <add-directory-windows-path>` (or you can choose a directory which is already on your Path).
62
63
64Python
65^^^^^^
66
67Download the latest Python_ for Windows installer, and run it.
68
69The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
70
71Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
72
73  pip install --user pyserial
74
75Toolchain Setup
76===============
77
78.. include-build-file:: inc/download-links.inc
79
80Download the precompiled Windows toolchain:
81
82|download_link_win32|
83
84Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``{IDF_TARGET_TOOLCHAIN_PREFIX}``.
85
86Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path <add-directory-windows-path>`. For example, the directory to add may be ``C:\Program Files\{IDF_TARGET_TOOLCHAIN_PREFIX}\bin``.
87
88.. note::
89   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\{IDF_TARGET_TOOLCHAIN_PREFIX}\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
90
91
92.. _add-directory-windows-path:
93
94Adding Directory to Path
95========================
96
97To add any new directory to your Windows Path environment variable:
98
99Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
100
101Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
102
103
104Next Steps
105==========
106
107To carry on with development environment setup, proceed to :ref:`get-started-set-up-tools`.
108
109.. _CMake: https://cmake.org/download/
110.. _Ninja: https://ninja-build.org/
111.. _ninja-dl: https://github.com/ninja-build/ninja/releases
112.. _Python: https://www.python.org/downloads/windows/
113.. _MSYS2: https://www.msys2.org/
114.. _kconfig-frontends releases page: https://github.com/espressif/kconfig-frontends/releases
115.. Note: These two targets may be used from git-clone-notes.inc depending on version, don't remove
116.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
117.. _Releases page: https://github.com/espressif/esp-idf/releases