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

Merge branch 'feature/docs_impr_idf_tools' into 'master'

Browse Source 
Docs: Improve the Downloadable Tools page with missing information

Closes IDF-4579

See merge request espressif/esp-idf!16860
This commit is contained in:
Roland Dobai 2022-01-20 10:48:22 +00:00
commit 483e16a86a
1 changed files with 21 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/en/api-guides/tools/idf-tools.rst
View File

@ -35,10 +35,13 @@ Tools installation directory
``IDF_TOOLS_PATH`` environment variable specifies the location where the tools are to be downloaded and installed. If not set, ``IDF_TOOLS_PATH`` defaults to ``HOME/.espressif`` on Linux and macOS, and ``%USER_PROFILE%\.espressif`` on Windows.
Inside ``IDF_TOOLS_PATH``, the scripts performing tools installation create the following directories:
Inside ``IDF_TOOLS_PATH``, the scripts performing tools installation create the following directories and files:
- ``dist`` — where the archives of the tools are downloaded.
- ``tools`` — where the tools are extracted. The tools are extracted into subdirectories: ``tools/TOOL_NAME/VERSION/``. This arrangement allows different versions of tools to be installed side by side.
- ``idf-env.json`` — user install options (targets, features) are stored in this file. Targets are selected chip targets for which tools are installed and kept up-to-date. Features determine the Python package set which should be installed. These options will be discussed later.
- ``python_env`` — not tools related; virtual Python environments are installed in the sub-directories.
- ``espidf.constraints.*.txt`` — one constraint file for each ESP-IDF release containing Python package version requirements.
GitHub Assets Mirror
--------------------
@ -101,9 +104,9 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo
* ``check``: For each tool, checks whether the tool is available in the system path and in ``IDF_TOOLS_PATH``.
* ``install-python-env``: Create Python virtual environment and install the required Python packages.
* ``install-python-env``: Create a Python virtual environment in the ``${IDF_TOOLS_PATH}/python_env`` directory and install there the required Python packages. An optional ``--features`` argument allows one to specify a comma-separated list of features. For each feature a requirements file must exist. For example, feature ``XY`` is a valid feature if ``${IDF_PATH}/requirements.XY.txt`` is an existing file with a list of Python packages to be installed. There is one mandatory ``core`` feature ensuring core functionality of ESP-IDF (build, flash, monitor, debug in console). There can be an arbitrary number of optional features. The selected list of features is stored in ``idf-env.json``. The requirement files contain a list of the desired Python packages to be installed and ``espidf.constraints.*.txt`` downloaded from https://dl.espressif.com and stored in ``${IDF_TOOLS_PATH}`` the package version requirements for a given ESP-IDF version.
* ``check-python-dependencies``: Checks if all required Python packages are installed.
* ``check-python-dependencies``: Checks if all required Python packages are installed. Packages from ``${IDF_PATH}/requirements.*.txt`` files selected by the feature list of ``idf-env.json`` are checked with the package versions specified in the ``espidf.constraints.*.txt`` file. The constraint file will be downloaded from https://dl.espressif.com if this step hasn't been done already in the last day.
.. _idf-tools-install:
@ -115,9 +118,18 @@ Shell-specific user-facing scripts are provided in the root of ESP-IDF repositor
* ``install.bat`` for Windows Command Prompt
* ``install.ps1`` for Powershell
* ``install.sh`` for Bash
* ``install.fish`` for Fish
Aside from downloading and installing the tools into ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment.
These scripts accept optionally a comma separated list of chip targets and ``--enable-*`` arguments for enabling features. These arguments are passed to the ``idf_tools.py`` script which stores them in ``idf-env.json``. Therefore, chip targets and features can be enabled incrementally.
Running the scripts without any optional arguments will install tools for all chip targets (by running ``idf_tools.py install --targets=all``) and Python packages for core ESP-IDF functionality (by running ``idf_tools.py install-python-env --features=core``).
Or for example, ``install.sh esp32`` will install tools only for ESP32. See the :ref:`Getting Started Guide <get-started-set-up-tools>` for more examples.
``install.sh --enable-XY`` will enable feature ``XY`` (by running ``idf_tools.py install-python-env --features=core,XY``).
.. _idf-tools-export:
Export scripts
@ -128,6 +140,7 @@ Since the installed tools are not permanently added into the user or system ``PA
* ``export.bat`` for Windows Command Prompt
* ``export.ps1`` for Powershell
* ``export.sh`` for Bash
* ``export.fish`` for Fish
.. note::