docs: update CMake getting started guide to use install.bat and export.bat
This commit is contained in:
Ivan Grokhotkov
parent
04d24c750a
commit
6f5c7a21ac
11 changed files with 175 additions and 280 deletions
|
|
@ -1,75 +1,3 @@
|
|||
Add IDF_PATH & idf.py PATH to User Profile (CMake)
|
||||
==================================================
|
||||
:orphan:
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. include:: ../cmake-warning.rst
|
||||
|
||||
To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
|
||||
|
||||
- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
|
||||
- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
|
||||
|
||||
To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
|
||||
|
||||
.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
|
||||
|
||||
.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
|
||||
|
||||
.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
|
||||
|
||||
.. _add-paths-to-profile-windows-cmake:
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
|
||||
|
||||
On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
|
||||
|
||||
You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
|
||||
|
||||
- Click ``New...`` to add a new system variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\user-name\esp\esp-idf``.
|
||||
- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
|
||||
|
||||
If you got here from :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then you can continue with :ref:`get-started-get-packages-cmake`.
|
||||
|
||||
|
||||
.. _add-idf_path-to-profile-linux-macos-cmake:
|
||||
|
||||
Linux and MacOS
|
||||
---------------
|
||||
|
||||
Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to your ``~/.profile`` file::
|
||||
|
||||
export IDF_PATH=~/esp/esp-idf
|
||||
export PATH="$IDF_PATH/tools:$PATH"
|
||||
|
||||
.. note::
|
||||
|
||||
``~/.profile`` means a file named ``.profile`` in your user's home directory (which is abbreviated ``~`` in the shell).
|
||||
|
||||
Log off and log in back to make this change effective.
|
||||
|
||||
.. note::
|
||||
|
||||
Not all shells use ``.profile``. If you have ``/bin/bash`` and ``.bash_profile`` exists then update this file instead. For ``zsh``, update ``.zprofile``. Other shells may use other profile files (consult the shell's documentation).
|
||||
|
||||
Run the following command to check if ``IDF_PATH`` is set::
|
||||
|
||||
printenv IDF_PATH
|
||||
|
||||
The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
|
||||
|
||||
To verify ``idf.py`` is now on the ``PATH``, you can run the following::
|
||||
|
||||
which idf.py
|
||||
|
||||
A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
|
||||
|
||||
If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
|
||||
|
||||
export IDF_PATH=~/esp/esp-idf
|
||||
export PATH="$IDF_PATH/tools:$PATH"
|
||||
|
||||
If you got here from :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then you can continue with :ref:`get-started-get-packages-cmake`.
|
||||
.. Remove this file when the Chinese translation of CMake getting started guide is updated
|
||||
|
|
|
|||
|
|
@ -78,10 +78,10 @@ This is a detailed roadmap to walk you through the installation process.
|
|||
Setting up Development Environment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* :ref:`get-started-setup-toolchain-cmake` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`MacOS <macos-setup>`
|
||||
* :ref:`get-started-get-prerequisites-cmake` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`macOS <macos-setup>`
|
||||
* :ref:`get-started-get-esp-idf-cmake`
|
||||
* :ref:`get-started-setup-path-cmake`
|
||||
* :ref:`get-started-get-packages-cmake`
|
||||
* :ref:`get-started-set-up-tools-cmake`
|
||||
* :ref:`get-started-set-up-env-cmake`
|
||||
|
||||
Creating Your First Project
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -94,60 +94,40 @@ Creating Your First Project
|
|||
* :ref:`get-started-build-monitor-cmake`
|
||||
|
||||
|
||||
.. _get-started-setup-toolchain-cmake:
|
||||
.. _get-started-get-prerequisites-cmake:
|
||||
|
||||
Step 1. Set up the Toolchain
|
||||
============================
|
||||
Step 1. Install prerequisites
|
||||
=============================
|
||||
|
||||
The toolchain is a set of programs for compiling code and building applications.
|
||||
|
||||
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow the provided instructions.
|
||||
Some tools need to be installed on the computer before proceeding to the next steps. Follow the links below for the instructions for your OS:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
Windows <windows-setup>
|
||||
Linux <linux-setup>
|
||||
MacOS <macos-setup>
|
||||
|
||||
+-------------------+-------------------+-------------------+
|
||||
| |windows-logo| | |linux-logo| | |macos-logo| |
|
||||
+-------------------+-------------------+-------------------+
|
||||
| `Windows`_ | `Linux`_ | `Mac OS`_ |
|
||||
+-------------------+-------------------+-------------------+
|
||||
|
||||
.. |windows-logo| image:: ../../_static/windows-logo.png
|
||||
:target: ../get-started-cmake/windows-setup.html
|
||||
|
||||
.. |linux-logo| image:: ../../_static/linux-logo.png
|
||||
:target: ../get-started-cmake/linux-setup.html
|
||||
|
||||
.. |macos-logo| image:: ../../_static/macos-logo.png
|
||||
:target: ../get-started-cmake/macos-setup.html
|
||||
|
||||
.. _Windows: ../get-started-cmake/windows-setup.html
|
||||
.. _Linux: ../get-started-cmake/linux-setup.html
|
||||
.. _Mac OS: ../get-started-cmake/macos-setup.html
|
||||
|
||||
.. note::
|
||||
|
||||
This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths.
|
||||
|
||||
Depending on your experience and preferences, you may want to customize your environment instead of using a prebuilt toolchain. To set up the system your own way go to Section :ref:`get-started-customized-setup-cmake`.
|
||||
Linux <linux-setup>
|
||||
macOS <macos-setup>
|
||||
|
||||
* :doc:`windows-setup`
|
||||
* :doc:`linux-setup`
|
||||
* :doc:`macos-setup`
|
||||
|
||||
.. _get-started-get-esp-idf-cmake:
|
||||
|
||||
Step 2. Get ESP-IDF
|
||||
===================
|
||||
|
||||
Besides the toolchain, you also need ESP32-specific API (software libraries and source code). They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
|
||||
To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
|
||||
|
||||
Get ESP-IDF in accordance with your operating system.
|
||||
|
||||
To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``.
|
||||
|
||||
Linux and MacOS
|
||||
.. note::
|
||||
|
||||
This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths.
|
||||
|
||||
Linux and macOS
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Open Terminal, and run the following commands:
|
||||
|
|
@ -161,60 +141,76 @@ Consult :doc:`/versions` for information about which ESP-IDF version to use in a
|
|||
Windows
|
||||
~~~~~~~
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
|
||||
If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below.
|
||||
|
||||
Open Command Prompt and run the following commands:
|
||||
|
||||
.. include:: /_build/inc/git-clone-windows.inc
|
||||
|
||||
ESP-IDF will be downloaded into ``%userprofile%\esp\esp-idf``.
|
||||
In addition to installing the tools, :ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF.
|
||||
|
||||
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
|
||||
|
||||
.. include:: /_build/inc/git-clone-notes.inc
|
||||
If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions <get-esp-idf-windows-command-line-cmake>`.
|
||||
|
||||
.. note::
|
||||
.. _get-started-set-up-tools-cmake:
|
||||
|
||||
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
|
||||
Step 3. Set up the tools
|
||||
========================
|
||||
|
||||
cd esp-idf
|
||||
git submodule update --init
|
||||
Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc.
|
||||
|
||||
Windows
|
||||
~~~~~~~
|
||||
|
||||
.. _get-started-setup-path-cmake:
|
||||
:ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools.
|
||||
|
||||
Step 3. Set Environment Variables
|
||||
=================================
|
||||
If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps:
|
||||
|
||||
Set the following environment variables on your computer, so that projects can be built:
|
||||
.. code-block:: batch
|
||||
|
||||
- Create ``IDF_PATH`` and assign it the path to the ESP-IDF directory.
|
||||
- Add to ``PATH`` the path to the ``tools`` directory inside the ``IDF_PATH`` directory.
|
||||
cd %userprofile%\esp\esp-idf
|
||||
install.bat
|
||||
|
||||
These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in Section :doc:`add-idf_path-to-profile`.
|
||||
Linux and macOS
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
.. _get-started-get-packages-cmake:
|
||||
cd ~/esp/esp-idf
|
||||
./install.sh
|
||||
|
||||
Step 4. Install the Required Python Packages
|
||||
============================================
|
||||
Customizing the tools installation path
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running::
|
||||
The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user has sufficient permissions to read and write this path.
|
||||
|
||||
python -m pip install --user -r $IDF_PATH/requirements.txt
|
||||
If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the ``install.bat``/``install.sh`` and ``export.bat``/``export.sh`` scripts are executed.
|
||||
|
||||
.. note::
|
||||
.. _get-started-set-up-env-cmake:
|
||||
|
||||
Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run
|
||||
the command ``python --version`` and depending on the result, you might want to use ``python2``, ``python2.7``
|
||||
or similar instead of just ``python``, e.g.::
|
||||
Step 4. Set up the environment variables
|
||||
========================================
|
||||
|
||||
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
|
||||
The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-IDF provides another script which does that.
|
||||
|
||||
Windows
|
||||
~~~~~~~
|
||||
|
||||
:ref:`get-started-cmake-windows-tools-installer` for Windows creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step.
|
||||
|
||||
Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
%userprofile%\esp\esp-idf\export.bat
|
||||
|
||||
Linux and macOS
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
In the terminal where you are going to use ESP-IDF, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. $HOME/esp/esp-idf/export.sh
|
||||
|
||||
Note the space between the leading dot and the path!
|
||||
|
||||
You can also automate this step, making ESP-IDF tools available in every terminal, by adding this line to your ``.profile`` or ``.bash_profile`` script.
|
||||
|
||||
.. _get-started-start-project-cmake:
|
||||
|
||||
|
|
@ -225,7 +221,7 @@ Now you are ready to prepare your application for ESP32. You can start with :exa
|
|||
|
||||
Copy :example:`get-started/hello_world` to ``~/esp`` directory:
|
||||
|
||||
Linux and MacOS
|
||||
Linux and macOS
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -247,7 +243,7 @@ It is also possible to build examples in-place, without copying them first.
|
|||
|
||||
.. important::
|
||||
|
||||
The esp-idf build system does not support spaces in the paths to either esp-idf or to projects.
|
||||
The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects.
|
||||
|
||||
.. _get-started-connect-cmake:
|
||||
|
||||
|
|
@ -276,7 +272,7 @@ Step 7. Configure
|
|||
|
||||
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-cmake` and run the project configuration utility ``menuconfig``.
|
||||
|
||||
Linux and MacOS
|
||||
Linux and macOS
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -294,12 +290,6 @@ Windows
|
|||
cd %userprofile%\esp\hello_world
|
||||
idf.py menuconfig
|
||||
|
||||
The Python 2.7 installer will try to configure Windows to associate ``.py`` files with Python 2. If a separately installed program, such as Visual Studio Python Tools, has created an association with a different version of Python, then running ``idf.py`` may not work (it opens the file in Visual Studio instead). You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
|
||||
|
||||
.. note::
|
||||
|
||||
If you get an error ``idf.py not found``, make sure that the ``PATH`` environment variable was set correctly in :ref:`get-started-setup-path-cmake`. If there is no ``idf.py`` in ``tools``, make sure you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf-cmake`.
|
||||
|
||||
If the previous steps have been done correctly, the following menu appears:
|
||||
|
||||
.. figure:: ../../_static/project-configuration.png
|
||||
|
|
@ -480,17 +470,18 @@ Updating ESP-IDF
|
|||
|
||||
You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf-cmake`.
|
||||
|
||||
If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts can find ESP-IDF in its release specific location.
|
||||
|
||||
Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
|
||||
|
||||
After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools-cmake`.
|
||||
|
||||
Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env-cmake`.
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
add-idf_path-to-profile
|
||||
establish-serial-connection
|
||||
eclipse-setup
|
||||
../api-guides/tools/idf-monitor
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ Build the toolchain::
|
|||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-esp32-elf
|
||||
|
||||
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow `instructions for standard setup <setup-linux-toolchain-add-it-to-path-cmake>`_ to add the toolchain to your ``PATH``.
|
||||
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable.
|
||||
|
||||
|
||||
Next Steps
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
*********************************************
|
||||
Standard Setup of Toolchain for Linux (CMake)
|
||||
*********************************************
|
||||
***********************************************
|
||||
Installation of Prerequisites for Linux (CMake)
|
||||
***********************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
|
@ -26,61 +26,9 @@ To compile with ESP-IDF you need to get the following packages:
|
|||
.. note::
|
||||
CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
|
||||
|
||||
Toolchain Setup
|
||||
Additional Tips
|
||||
===============
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
ESP32 toolchain for Linux is available for download from Espressif website:
|
||||
|
||||
- for 64-bit Linux:
|
||||
|
||||
|download_link_linux64|
|
||||
|
||||
- for 32-bit Linux:
|
||||
|
||||
|download_link_linux32|
|
||||
|
||||
1. Download this file, then extract it in ``~/esp`` directory:
|
||||
|
||||
- for 64-bit Linux:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-linux64.inc
|
||||
|
||||
- for 32-bit Linux:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-linux32.inc
|
||||
|
||||
.. _setup-linux-toolchain-add-it-to-path-cmake:
|
||||
|
||||
2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
|
||||
|
||||
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
|
||||
|
||||
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
|
||||
|
||||
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
|
||||
|
||||
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
|
||||
|
||||
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
|
||||
|
||||
.. note::
|
||||
|
||||
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
|
||||
|
||||
3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
|
||||
|
||||
printenv PATH
|
||||
|
||||
You are looking for similar result containing toolchain's path at the beginning of displayed string::
|
||||
|
||||
$ printenv PATH
|
||||
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
|
||||
|
||||
Instead of ``/home/user-name`` there should be a home path specific to your installation.
|
||||
|
||||
|
||||
Permission issues /dev/ttyUSB0
|
||||
------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ Build the toolchain::
|
|||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-esp32-elf
|
||||
|
||||
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path-cmake>` to add the toolchain to your ``PATH``.
|
||||
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable.
|
||||
|
||||
|
||||
Next Steps
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
**********************************************
|
||||
Standard Setup of Toolchain for Mac OS (CMake)
|
||||
**********************************************
|
||||
***********************************************
|
||||
Installation of Prerequisites for macOS (CMake)
|
||||
***********************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
|
@ -9,7 +9,7 @@ Standard Setup of Toolchain for Mac OS (CMake)
|
|||
Install Prerequisites
|
||||
=====================
|
||||
|
||||
ESP-IDF will use the version of Python installed by default on Mac OS.
|
||||
ESP-IDF will use the version of Python installed by default on macOS.
|
||||
|
||||
- install pip::
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ ESP-IDF will use the version of Python installed by default on Mac OS.
|
|||
|
||||
sudo port install cmake ninja
|
||||
|
||||
- Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation downloads.
|
||||
- Otherwise, consult the CMake_ and Ninja_ home pages for macOS installation downloads.
|
||||
|
||||
- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
|
||||
|
||||
|
|
@ -38,39 +38,7 @@ ESP-IDF will use the version of Python installed by default on Mac OS.
|
|||
|
||||
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
|
||||
|
||||
Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
|
||||
|
||||
Toolchain Setup
|
||||
===============
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
ESP32 toolchain for macOS is available for download from Espressif website:
|
||||
|
||||
|download_link_osx|
|
||||
|
||||
Download this file, then extract it in ``~/esp`` directory:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-osx.inc
|
||||
|
||||
.. _setup-macos-toolchain-add-it-to-path-cmake:
|
||||
|
||||
The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
|
||||
|
||||
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
|
||||
|
||||
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
|
||||
|
||||
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
|
||||
|
||||
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
|
||||
|
||||
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
|
||||
|
||||
Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
|
||||
|
||||
printenv PATH
|
||||
|
||||
Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Customized Setup of Toolchain (CMake)
|
|||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain-cmake`) you may build the toolchain yourself.
|
||||
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-set-up-tools-cmake`) you may build the toolchain yourself.
|
||||
|
||||
If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
********************************************
|
||||
Setup Windows Toolchain from Scratch (CMake)
|
||||
********************************************
|
||||
**********************************
|
||||
Windows Setup from Scratch (CMake)
|
||||
**********************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
|
@ -10,10 +10,38 @@ This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer
|
|||
|
||||
To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
|
||||
|
||||
|
||||
.. note::
|
||||
The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
|
||||
|
||||
.. _get-esp-idf-windows-command-line-cmake:
|
||||
|
||||
Get ESP-IDF
|
||||
===========
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
|
||||
If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below.
|
||||
|
||||
Open Command Prompt and run the following commands:
|
||||
|
||||
.. include:: /_build/inc/git-clone-windows.inc
|
||||
|
||||
ESP-IDF will be downloaded into ``%userprofile%\esp\esp-idf``.
|
||||
|
||||
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
|
||||
|
||||
.. include:: /_build/inc/git-clone-notes.inc
|
||||
|
||||
.. note::
|
||||
|
||||
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
|
||||
|
||||
cd esp-idf
|
||||
git submodule update --init
|
||||
|
||||
|
||||
Tools
|
||||
=====
|
||||
|
||||
|
|
@ -90,4 +118,5 @@ To carry on with development environment setup, proceed to :ref:`get-started-get
|
|||
.. _ninja: https://ninja-build.org/
|
||||
.. _Python: https://www.python.org/downloads/windows/
|
||||
.. _MSYS2: https://msys2.github.io/
|
||||
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
|
||||
|
||||
|
|
|
|||
31
docs/en/get-started-cmake/windows-setup-update.rst
Normal file
31
docs/en/get-started-cmake/windows-setup-update.rst
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
*********************************
|
||||
Updating ESP-IDF tools on Windows
|
||||
*********************************
|
||||
|
||||
.. _get-started-cmake-install_bat-windows:
|
||||
|
||||
Install ESP-IDF tools using ``install.bat``
|
||||
===========================================
|
||||
|
||||
From the Windows Command Prompt, change to the directory where ESP-IDF is installed. Then run::
|
||||
|
||||
install.bat
|
||||
|
||||
This will download and install the tools necessary to use ESP-IDF. If the specific version of the tool is already installed, no action will be taken.
|
||||
The tools are downloaded and installed into a directory specified during ESP-IDF Tools Installer process. By default, this is ``C:\Users\username\.espressif``.
|
||||
|
||||
.. _get-started-cmake-export_bat-windows:
|
||||
|
||||
Add ESP-IDF tools to PATH using ``export.bat``
|
||||
==============================================
|
||||
|
||||
ESP-IDF tools installer creates a Start menu shortcut for "ESP-IDF Command Prompt". This shortcut opens a Command Prompt window where all the tools are already available.
|
||||
|
||||
In some cases, you may want to work with ESP-IDF in a Command Prompt window which wasn't started using that shortcut. If this is the case, follow the instructions below to add ESP-IDF tools to PATH.
|
||||
|
||||
In the command prompt where you need to use ESP-IDF, change to the directory where ESP-IDF is installed, then execute ``export.bat``::
|
||||
|
||||
cd %userprofile%\esp\esp-idf
|
||||
export.bat
|
||||
|
||||
When this is done, the tools will be available in this command prompt.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
***********************************************
|
||||
Standard Setup of Toolchain for Windows (CMake)
|
||||
***********************************************
|
||||
*************************************************
|
||||
Installation of Prerequisites for Windows (CMake)
|
||||
*************************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
|
@ -12,46 +12,43 @@ Standard Setup of Toolchain for Windows (CMake)
|
|||
Introduction
|
||||
============
|
||||
|
||||
ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Git, a cross-compiler and the CMake build tool. We'll go over each one in this document.
|
||||
ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Python, Git, cross-compilers, menuconfig tool, CMake and Ninja build tools.
|
||||
|
||||
For this Getting Started we're going to use a command prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
|
||||
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.
|
||||
|
||||
.. note::
|
||||
The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
|
||||
|
||||
.. _get-started-cmake-windows-tools-installer:
|
||||
|
||||
ESP-IDF Tools Installer
|
||||
=======================
|
||||
|
||||
The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
|
||||
|
||||
https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe
|
||||
https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe
|
||||
|
||||
The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
|
||||
The installer includes the cross-compilers, OpenOCD, cmake_ and Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for Python_ 3.7 and `Git For Windows`_ if they are not already installed on the computer.
|
||||
|
||||
By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
|
||||
The installer also offers to download one of the ESP-IDF release versions.
|
||||
|
||||
Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
|
||||
Using the Command Prompt
|
||||
========================
|
||||
|
||||
Installing Git
|
||||
==============
|
||||
For the remaining Getting Started steps, we're going to use the Windows Command Prompt.
|
||||
|
||||
The ESP-IDF tools installer does not install Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a command line Git for Windows (along with the "Git Bash" terminal) from `Git For Windows`_.
|
||||
ESP-IDF Tools Installer 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.
|
||||
|
||||
If you prefer to use a different graphical Git client, then you can install one such as `Github Desktop`. You will need to translate the Git commands in the Getting Started guide for use with your chosen Git client.
|
||||
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:
|
||||
|
||||
Using a Terminal
|
||||
================
|
||||
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.
|
||||
|
||||
For the remaining Getting Started steps, we're going to use a terminal command prompt. It doesn't matter which command prompt you use:
|
||||
|
||||
- You can use the built-in Windows Command Prompt, under the Start menu. All Windows command line instructions in this documentation are "batch" commands for use with the Windows Command Prompt.
|
||||
- You can use the "Git Bash" terminal which is part of `Git for Windows`_. This uses the same "bash" command prompt syntax as is given for Mac OS or Linux. You can find it in the Start menu once installed.
|
||||
- If you have MSYS2_ installed (maybe from a previous ESP-IDF version), then you can also use the MSYS terminal.
|
||||
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.
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`.
|
||||
If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project-cmake`.
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
|
@ -62,7 +59,7 @@ For advanced users who want to customize the install process:
|
|||
:maxdepth: 1
|
||||
|
||||
windows-setup-scratch
|
||||
|
||||
windows-setup-update
|
||||
|
||||
.. _MSYS2: https://msys2.github.io/
|
||||
.. _cmake: https://cmake.org/download/
|
||||
|
|
|
|||
3
docs/zh_CN/get-started-cmake/windows-setup-update.rst
Normal file
3
docs/zh_CN/get-started-cmake/windows-setup-update.rst
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
:orphan:
|
||||
|
||||
.. Remove this file when the Chinese translation of CMake getting started guide is updated
|
||||
Loading…
Reference in a new issue