alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
1b4e4c37b7
esp-idf/docs/en/get-started/windows-setup.rst

133 lines
6.2 KiB
ReStructuredText
Raw Normal View History

docs: Make CMake build system default, mark GNU Make as legacy option All `-cmake` suffixes are removed Where a GNU Make option is renamed, the `-legacy` suffix is used
2019-06-24 21:26:53 -04:00
***********************************************
Standard Setup of Toolchain for Windows
***********************************************
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
doc(global): build cross-language links for translated documents
2018-04-27 02:46:13 -04:00
:link_to_translation:`zh_CN:[中文]`
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Add "explicit only" directive & use only:: to block out some chip-specific parts of docs
2019-11-22 00:57:09 -05:00
.. only:: esp32
.. note::
Currently only 64-bit versions of Windows are supported. 32-bit Windows can use the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>`.
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
Getting started guides
2017-03-26 18:01:52 -04:00
Introduction
============
Doc: Remove menuconfig tool which is not used anymore
2019-11-19 09:33:10 -05:00
ESP-IDF requires some prerequisite tools to be installed so you can build firmware for supported chips. The prerequisite tools include Python, Git, cross-compilers, CMake and Ninja build tools.
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Add 'toctree filter' directive & filter out ESP32-only pages from S2 docs
2019-11-22 00:58:04 -05:00
.. only:: esp32
docs: Mark some more docs sections as ESP32 only
2019-11-26 01:22:50 -05:00
docs: Add 'toctree filter' directive & filter out ESP32-only pages from S2 docs
2019-11-22 00:58:04 -05:00
.. note::
Previous versions of ESP-IDF used the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>` and MSYS2_ Unix compatibility environment. This is no longer required, ESP-IDF can be used from the Windows Command Prompt.
Getting started guides
2017-03-26 18:01:52 -04:00
docs: add ESP-IDF Windows Installation limitations.
2020-11-24 08:09:38 -05:00
.. note::
Limitation: the installation path of Python or ESP-IDF must not contain white spaces or parentheses.
Limitation: the installation path of Python or ESP-IDF should not contain special characters (non-ASCII) unless the operating system is configured with "Unicode UTF-8" support.
System Administrator can enable the support via Control Panel - Change date, time, or number formats - Administrative tab - Change system locale - check the option "Beta: Use Unicode UTF-8 for worldwide language support" - Ok and reboot the computer.
docs: Make CMake build system default, mark GNU Make as legacy option All `-cmake` suffixes are removed Where a GNU Make option is renamed, the `-legacy` suffix is used
2019-06-24 21:26:53 -04:00
.. _get-started-windows-tools-installer:
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
ESP-IDF Tools Installer
=======================
Getting started guides
2017-03-26 18:01:52 -04:00
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
The easiest way to install ESP-IDF's prerequisites is to download one of ESP-IDF Tools Installers from this URL:
Getting started guides
2017-03-26 18:01:52 -04:00
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
- Online Installer (30 MB): https://dl.espressif.com/dl/esp-idf-tools-setup-online-2.5.exe
- Offline Installer - includes ESP-IDF v4.2, v4.1.1 (810 MB): https://dl.espressif.com/dl/esp-idf-tools-setup-offline-2.5.exe
Getting started guides
2017-03-26 18:01:52 -04:00
tools: Use GitHub download URLs for all files that can be downloaded from GitHub
2020-09-25 05:19:17 -04:00
.. IMPORTANT: Next time this link is updated, please go to get-started/index.rst and rewrite the section under "Alternative File Downloads ... Windows". Then delete this comment.
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
What is the usecase for Online and Offline Installer
----------------------------------------------------
Getting started guides
2017-03-26 18:01:52 -04:00
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
Online Installer is very small and allows the installation of all available releases of ESP-IDF. The installer will download only necessary dependencies including `Git For Windows`_ during the installation process. The installer stores downloaded files in the cache directory ``%userprofile%\.espressif``
docs: add a command to create an esp directory before cloning esp-idf
2020-08-11 02:08:45 -04:00
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
Offline Installer does not require any network connection. The installer contains all required dependencies including `Git For Windows`_ . The installer allows the installation of ESP-IDF with the following tags: v4.2, v4.1.1.
docs: add a command to create an esp directory before cloning esp-idf
2020-08-11 02:08:45 -04:00
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
Components of the installation
------------------------------
docs: add a command to create an esp directory before cloning esp-idf
2020-08-11 02:08:45 -04:00
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
The installer deploys the following components:
Updated get started instructions for windows following https://esp32.com/viewtopic.php?f=13&t=4232
2018-01-24 14:41:35 -05:00
docs: add links to Windows installer 2.5 Offline and Online versions
2021-02-02 07:48:11 -05:00
- Embedded Python
- Cross-compilers
- OpenOCD
- CMake_ and Ninja_ build tools
- ESP-IDF
The installer also allows reusing the existing directory with ESP-IDF. The recommended directory is ``%userprofile%\Desktop\esp-idf`` where ``%userprofile%`` is your home directory.
Launching ESP-IDF Environment
-----------------------------
At the end of the installation process you can check out option ``Run ESP-IDF PowerShell Environment`` or ``Run ESP-IDF Command Prompt (cmd.exe)``. The installer will launch ESP-IDF environment in selected prompt.
``Run ESP-IDF PowerShell Environment``:
.. figure:: ../../_static/esp-idf-installer-screenshot-powershell.png
:align: center
:alt: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment
:figclass: align-center
Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF PowerShell Environment
.. figure:: ../../_static/esp-idf-installer-powershell.png
:align: center
:alt: ESP-IDF PowerShell
:figclass: align-center
ESP-IDF PowerShell
``Run ESP-IDF Command Prompt (cmd.exe)``:
docs: Update FreeRTOS version, add tips to set up instructions for Windows
2021-01-22 02:51:15 -05:00
.. figure:: ../../_static/esp-idf-installer-screenshot.png
:align: center
:alt: Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF Command Prompt (cmd.exe)
:figclass: align-center
Completing the ESP-IDF Tools Setup Wizard with Run ESP-IDF Command Prompt (cmd.exe)
.. figure:: ../../_static/esp-idf-installer-command-prompt.png
:align: center
:alt: ESP-IDF Command Prompt
:figclass: align-center
ESP-IDF Command Prompt
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
Using the Command Prompt
========================
Updated get started instructions for windows following https://esp32.com/viewtopic.php?f=13&t=4232
2018-01-24 14:41:35 -05:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
For the remaining Getting Started steps, we're going to use the Windows Command Prompt.
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Update FreeRTOS version, add tips to set up instructions for Windows
2021-01-22 02:51:15 -05:00
ESP-IDF Tools Installer also creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This shortcut launches the Command Prompt (cmd.exe) and runs ``export.bat`` script to set up the environment variables (``PATH``, ``IDF_PATH`` and others). Inside this command prompt, all the installed tools are available.
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
Note that this shortcut is specific to the ESP-IDF directory selected in the ESP-IDF Tools Installer. If you have multiple ESP-IDF directories on the computer (for example, to work with different versions of ESP-IDF), you have two options to use them:
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
1. Create a copy of the shortcut created by the ESP-IDF Tools Installer, and change the working directory of the new shortcut to the ESP-IDF directory you wish to use.
Getting started guides
2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
2. Alternatively, run ``cmd.exe``, then change to the ESP-IDF directory you wish to use, and run ``export.bat``. Note that unlike the previous option, this way requires Python and Git to be present in ``PATH``. If you get errors related to Python or Git not being found, use the first option.
Getting started guides
2017-03-26 18:01:52 -04:00
Next Steps
==========
docs: Make CMake build system default, mark GNU Make as legacy option All `-cmake` suffixes are removed Where a GNU Make option is renamed, the `-legacy` suffix is used
2019-06-24 21:26:53 -04:00
If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project`.
Getting started guides
2017-03-26 18:01:52 -04:00
Related Documents
=================
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
For advanced users who want to customize the install process:
Getting started guides
2017-03-26 18:01:52 -04:00
.. toctree::
:maxdepth: 1
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
windows-setup-update
Getting started guides
2017-03-26 18:01:52 -04:00
doc: Getting Started Guide, remove shortcuts to 'build toolchain from scratch' instructions
2020-09-03 14:05:24 -04:00
docs: Fix broken URLs & permanent redirects
2020-03-22 19:27:51 -04:00
.. _MSYS2: https://www.msys2.org/
docs: add ESP-IDF Windows Installation limitations.
2020-11-24 08:09:38 -05:00
.. _CMake: https://cmake.org/download/
.. _Ninja: https://ninja-build.org/
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
2019-06-24 21:29:49 -04:00
.. _Python: https://www.python.org/downloads/windows/
.. _Git for Windows: https://gitforwindows.org/
Provide CN translation for get-started section in MR12242
2021-02-18 09:04:35 -05:00
.. _Github Desktop: https://desktop.github.com/
Reference in New Issue Copy Permalink