diff --git a/docs/en/api-guides/tools/idf-tools.rst b/docs/en/api-guides/tools/idf-tools.rst index 0120cfcae1..64a223780a 100644 --- a/docs/en/api-guides/tools/idf-tools.rst +++ b/docs/en/api-guides/tools/idf-tools.rst @@ -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 -------------------- @@ -60,7 +63,7 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo :idf_file:`tools/idf_tools.py` script bundled with ESP-IDF performs several functions: * ``install``: Download the tool into ``${IDF_TOOLS_PATH}/dist`` directory, extract it into ``${IDF_TOOLS_PATH}/tools/TOOL_NAME/VERSION``. - + ``install`` command accepts the list of tools to install, in ``TOOL_NAME`` or ``TOOL_NAME@VERSION`` format. If ``all`` is given, all the tools (required and optional ones) are installed. If no argument or ``required`` is given, only the required tools are installed. * ``download``: Similar to ``install`` but doesn't extract the tools. An optional ``--platform`` argument may be used to download the tools for the specific platform. @@ -72,7 +75,7 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo - ``shell`` produces output suitable for evaluation in the shell. For example, :: - + export PATH="/home/user/.espressif/tools/tool/v1.0.0/bin:$PATH" on Linux and macOS, and @@ -80,7 +83,7 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo :: set "PATH=C:\Users\user\.espressif\tools\v1.0.0\bin;%PATH%" - + on Windows. .. note:: @@ -94,16 +97,16 @@ Any mirror server can be used provided the URL matches the ``github.com`` downlo - ``key-value`` produces output in `VARIABLE=VALUE` format, suitable for parsing by other scripts:: PATH=/home/user/.espressif/tools/tool/v1.0.0:$PATH - - Note that the script consuming this output has to perform expansion of ``$VAR`` or ``%VAR%`` patterns found in the output. + + Note that the script consuming this output has to perform expansion of ``$VAR`` or ``%VAR%`` patterns found in the output. * ``list``: Lists the known versions of the tools, and indicates which ones are installed. * ``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 ` 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::