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 'tidy_build_system_docs' into 'master'

Browse Source 
Docs: Move the documentation about idf.py out from the build system documentation

Closes IDF-2431

See merge request espressif/esp-idf!17789
This commit is contained in:
Roland Dobai 2022-04-25 16:09:08 +08:00
commit 2448639245
6 changed files with 260 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
docs/en/api-guides/build-system.rst
View File

@ -50,83 +50,10 @@ idf.py
The ``idf.py`` command-line tool provides a front-end for easily managing your project builds. It manages the following tools:
- CMake_, which configures the project to be built
- A command-line build tool (either Ninja_ build or `GNU Make`)
- Ninja_ which builds the project
- `esptool.py`_ for flashing the target.
The :ref:`getting started guide <get-started-configure>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
``idf.py`` should be run in an ESP-IDF "project" directory, i.e. one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
Type ``idf.py --help`` for a list of commands. Here are a summary of the most useful ones:
- ``idf.py set-target <target>`` sets the target (chip) for which the project is built. See :ref:`selecting-idf-target`.
- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
- Create the build directory if needed. The sub-directory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
- Run CMake_ as necessary to configure the project and generate build files for the main build tool.
- Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted.
- ``idf.py flash`` will automatically build the project if necessary, and then flash it to the target. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
- ``idf.py monitor`` will display serial output from the target. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor.
Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the target before running the serial monitor.
For commands that are not known to ``idf.py`` an attempt to execute them as a build system target will be made.
The command ``idf.py`` supports `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ for bash, zsh and fish shells.
In order to make `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ supported, please make sure you have at least Python 3.5 and `click <https://click.palletsprojects.com/>`_ 7.1 or newer (:ref:`see also <get-started-get-prerequisites>`).
To enable autocompletion for ``idf.py`` use the ``export`` command (:ref:`see this <get-started-set-up-env>`). Autocompletion is initiated by pressing the TAB key. Type "idf.py -" and press the TAB key to autocomplete options.
The autocomplete support for PowerShell is planned in the future.
.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
Advanced Commands
^^^^^^^^^^^^^^^^^
- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition-table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the target.
- ``idf.py -p PORT erase-flash`` will use esptool.py to erase the target's entire flash chip.
- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text. See ``idf.py-size`` for more information.
- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
- ``idf.py python-clean`` deletes generated Python byte code from the IDF directory which may cause issues when switching between IDF and Python versions. It is advised to run this target after switching versions of Python.
- ``idf.py docs`` will open direct link to documentation for project's chip target and version in browser. To see all options use ``idf.py docs --help``
The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
idf.py options
^^^^^^^^^^^^^^
To list all available root level options, run ``idf.py --help``. To list options that are specific for a subcommand, run ``idf.py <command> --help``, for example ``idf.py monitor --help``. Here is a list of some useful options:
- ``-C <dir>`` allows overriding the project directory from the default current working directory.
- ``-B <dir>`` allows overriding the build directory from the default ``build`` subdirectory of the project directory.
- ``--ccache`` flag can be used to enable CCache_ when compiling source files, if the CCache_ tool is installed. This can dramatically reduce some build times.
Note that some older versions of CCache may exhibit bugs on some platforms, so if files are not rebuilt as expected then try disabling CCache and build again. CCache can be enabled by default by setting the ``IDF_CCACHE_ENABLE`` environment variable to a non-zero value.
- ``-v`` flag causes both ``idf.py`` and the build system to produce verbose build output. This can be useful for debugging build problems.
- ``--cmake-warn-uninitialized`` (or ``-w``) will cause CMake to print uninitialized variable warnings inside the project directory (not for directories not found inside the project directory). This only controls CMake variable warnings inside CMake itself, not other types of build warnings. This option can also be set permanently by setting the ``IDF_CMAKE_WARN_UNINITIALIZED`` environment variable to a non-zero value.
Start a new project
-------------------
Use the command ``idf.py create-project`` for starting a new project. Execute ``idf.py create-project --help`` for more information.
Example:
.. code-block:: bash
idf.py create-project --path my_projects my_new_project
This example will create a new project called my_new_project directly into the directory my_projects.
You can read more about configuring the build system using ``idf.py`` :doc:`here <tools/idf-py>`.
Using CMake Directly
--------------------
@ -386,19 +313,6 @@ There are other arguments that can be passed to ``idf_component_register``. Thes
See `example component requirements`_ and `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
Create a new component
----------------------
Use the command ``idf.py create-component`` for creating a new component. The new component will contain set of files necessary for building a component. You may include the component's header file into your project and use its functionality. For more information execute ``idf.py create-component --help``.
Example:
.. code-block:: bash
idf.py -C components create-component my_component
The example will create a new component in the subdirectory `components` under the current working directory. For more information about components follow the documentation page :ref:`see above <component-directories>`.
.. _component variables:
Preset Component Variables
@ -1051,41 +965,10 @@ The build directory also contains a generated file ``flasher_args.json`` which c
Building the Bootloader
=======================
The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``.
The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
.. _selecting-idf-target:
Selecting the Target
====================
ESP-IDF supports multiple targets (chips). A full list of supported targets in your version of ESP-IDF can be seen by running `idf.py --list-targets`.
To select the target before building the project, use ``idf.py set-target <target>`` command, for example::
idf.py set-target esp32s2
.. important::
``idf.py set-target`` will clear the build directory and re-generate the ``sdkconfig`` file from scratch. The old ``sdkconfig`` file will be saved as ``sdkconfig.old``.
.. note::
The behavior of ``idf.py set-target`` command is equivalent to:
1. clearing the build directory (``idf.py fullclean``)
2. removing the sdkconfig file (``mv sdkconfig sdkconfig.old``)
3. configuring the project with the new target (``idf.py -DIDF_TARGET=esp32 reconfigure``)
It is also possible to pass the desired ``IDF_TARGET`` as an environment variable (e.g. ``export IDF_TARGET=esp32s2``) or as a CMake variable (e.g. ``-DIDF_TARGET=esp32s2`` argument to CMake or idf.py). Setting the environment variable is a convenient method if you mostly work with one type of the chip.
To specify the _default_ value of ``IDF_TARGET`` for a given project, add ``CONFIG_IDF_TARGET`` value to ``sdkconfig.defaults``. For example, ``CONFIG_IDF_TARGET="esp32s2"``. This value will be used if ``IDF_TARGET`` is not specified by other method: using an environment variable, CMake variable, or ``idf.py set-target`` command.
If the target has not been set by any of these methods, the build system will default to ``esp32`` target.
.. _write-pure-component:
Writing Pure CMake Components
@ -1617,4 +1500,3 @@ Flashing from make
.. _quirc: https://github.com/dlbeer/quirc
.. _pyenv: https://github.com/pyenv/pyenv#readme
.. _virtualenv: https://virtualenv.pypa.io/en/stable/
.. _CCache: https://ccache.dev/

240
docs/en/api-guides/tools/idf-py.rst Normal file
View File

@ -0,0 +1,240 @@
IDF Frontend - idf.py
*********************
The ``idf.py`` command-line tool provides a front-end for easily managing your project builds, deployment and debugging, and more.
It manages several tools, for example:
- CMake_, which configures the project to be built
- Ninja_ which builds the project
- `esptool.py`_ for flashing the target.
The :ref:`getting started guide <get-started-configure>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
.. important::
``idf.py`` should be run in an ESP-IDF "project" directory, i.e. one containing a ``CMakeLists.txt`` file.
Older style projects with a ``Makefile`` will not work with ``idf.py``.
Commands
========
Start a new project: create-project
------------------------------------
.. code-block:: bash
idf.py create-project <project name>
This will create a new ESP-IDF project, additionally folder where the project will
be created can be specified by the ``--path`` option.
Create a new component: create-component
----------------------------------------
This command creates a new component, which will have a minimum set of files
necessary for building.
.. code-block:: bash
idf.py create-component <component name>
The ``-C`` option can be used to specify the directory the component will be
created in.
For more information about components see the :ref:`build system page <component-directories>`.
.. _selecting-idf-target:
Select the Target Chip: set-target
----------------------------------
ESP-IDF supports multiple targets (chips). A full list of supported targets in your version of ESP-IDF can be seen by running ``idf.py --list-targets``.
This sets the current project target:
.. code-block:: bash
idf.py set-target <target>
.. important::
``idf.py set-target`` will clear the build directory and re-generate the ``sdkconfig`` file from scratch. The old ``sdkconfig`` file will be saved as ``sdkconfig.old``.
.. note::
The behavior of ``idf.py set-target`` command is equivalent to:
1. clearing the build directory (``idf.py fullclean``)
2. removing the sdkconfig file (``mv sdkconfig sdkconfig.old``)
3. configuring the project with the new target (``idf.py -DIDF_TARGET=esp32 reconfigure``)
It is also possible to pass the desired ``IDF_TARGET`` as an environment variable (e.g. ``export IDF_TARGET=esp32s2``) or as a CMake variable (e.g. ``-DIDF_TARGET=esp32s2`` argument to CMake or idf.py). Setting the environment variable is a convenient method if you mostly work with one type of the chip.
To specify the _default_ value of ``IDF_TARGET`` for a given project, add ``CONFIG_IDF_TARGET`` value to ``sdkconfig.defaults``. For example, ``CONFIG_IDF_TARGET="esp32s2"``. This value will be used if ``IDF_TARGET`` is not specified by other method: using an environment variable, CMake variable, or ``idf.py set-target`` command.
If the target has not been set by any of these methods, the build system will default to ``esp32`` target.
Start the graphical configuration tool: menuconfig
--------------------------------------------------
.. code-block:: bash
idf.py menuconfig
Build the project: build
------------------------
.. code-block:: bash
idf.py build
Running this command will build the project found in the current directory. This can involve multiple steps:
- Create the build directory if needed. The sub-directory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
- Run CMake_ as necessary to configure the project and generate build files for the main build tool.
- Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
Additionally, the command can be run with ``app``, ``bootloader`` and
``partition-table`` arguments to build only the app, bootloader or partition table
as applicable.
Remove the build output: clean
------------------------------
It is possible to remove the project build output files from the build directory by
using:
.. code-block:: bash
idf.py clean
The project will be fully rebuilt on next build.
Using this does not remove the CMake configuration output inside the build folder.
Delete the entire build contents: fullclean
-------------------------------------------
.. code-block:: bash
idf.py fullclean
Running this command will delete the entire "build" directory contents.
This includes all CMake configuration output.
The next time the project is built, CMake will configure it from scratch.
Note that this option recursively deletes *all* files in the build directory, so use with care.
Project configuration is not deleted.
Flash the project: flash
------------------------
Running the following command:
.. code-block:: bash
idf.py flash
will automatically build the project if necessary, and then flash it to the target.
You can use ``-p`` and ``-b`` options to set serial port name and flasher baud rate, respectively.
.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
Similarly to the ``build`` command, the command can be run with ``app``,
``bootloader`` and ``partition-table`` arguments to flash only the app, bootloader
or partition table as applicable.
Important notes
===============
Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the target before running the serial monitor.
The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (i.e. building before flashing, erasing before flashing, etc.).
For commands that are not known to ``idf.py`` an attempt to execute them as a build system target will be made.
The command ``idf.py`` supports `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ for bash, zsh and fish shells.
In order to make `shell autocompletion <https://click.palletsprojects.com/shell-completion/>`_ supported, please make sure you have at least Python 3.5 and `click <https://click.palletsprojects.com/>`_ 7.1 or newer (:ref:`see also <get-started-get-prerequisites>`).
To enable autocompletion for ``idf.py`` use the ``export`` command (:ref:`see this <get-started-set-up-env>`). Autocompletion is initiated by pressing the TAB key. Type ``idf.py -`` and press the TAB key to autocomplete options.
The autocomplete support for PowerShell is planned in the future.
Advanced Commands
=================
Open the documentation: docs
----------------------------
Using the following command the documentation for the projects target and version
will be opened in the browser:
.. code-block:: bash
idf.py docs
Show size: size
---------------
.. code-block:: bash
idf.py size
Will print app size information including occupied RAM and FLASH and section sizes.
.. code-block:: bash
idf.py size
Similarly, this will print the same information for each component used in the project.
.. code-block:: bash
idf.py size-files
Will print size information per source file in the project.
If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text. See ``idf.py-size`` for more information.
Reconfigure the project: reconfigure
------------------------------------
.. code-block:: bash
idf.py reconfigure
This command re-runs CMake_ even if it doesn't seem to need re-running.
This isn't necessary during normal usage, but can be useful after adding/removing
files from the source tree, or when modifying CMake cache variables.
For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
Clean the python byte code: python-clean
----------------------------------------
Generated python byte code can be deleted from the IDF directory using:
.. code-block:: bash
idf.py python-clean
The byte code may cause issues when switching between IDF and Python versions.
It is advised to run this target after switching versions of Python.
Global Options
==============
To list all available root level options, run ``idf.py --help``. To list options that are specific for a subcommand, run ``idf.py <command> --help``, for example ``idf.py monitor --help``. Here is a list of some useful options:
- ``-C <dir>`` allows overriding the project directory from the default current working directory.
- ``-B <dir>`` allows overriding the build directory from the default ``build`` subdirectory of the project directory.
- ``--ccache`` flag can be used to enable CCache_ when compiling source files, if the CCache_ tool is installed. This can dramatically reduce some build times.
Note that some older versions of CCache may exhibit bugs on some platforms, so if files are not rebuilt as expected then try disabling CCache and build again. CCache can be enabled by default by setting the ``IDF_CCACHE_ENABLE`` environment variable to a non-zero value.
- ``-v`` flag causes both ``idf.py`` and the build system to produce verbose build output. This can be useful for debugging build problems.
- ``--cmake-warn-uninitialized`` (or ``-w``) will cause CMake to print uninitialized variable warnings found in the project directory only. This only controls CMake variable warnings inside CMake itself, not other types of build warnings. This option can also be set permanently by setting the ``IDF_CMAKE_WARN_UNINITIALIZED`` environment variable to a non-zero value.
.. _cmake: https://cmake.org
.. _ninja: https://ninja-build.org
.. _esptool.py: https://github.com/espressif/esptool/#readme
.. _CCache: https://ccache.dev/

13
docs/en/api-guides/tools/index.rst
View File

@ -4,9 +4,10 @@ Tools
.. toctree::
:maxdepth: 1
IDF Tools <idf-tools>
IDF Monitor <idf-monitor>
IDF Docker image <idf-docker-image>
IDF Windows Installer <idf-windows-installer>
IDF Component Manager <idf-component-manager>
IDF Clang Tidy <idf-clang-tidy>
idf-py
idf-monitor
idf-docker-image
idf-windows-installer
idf-component-manager
idf-clang-tidy
idf-tools

4
docs/zh_CN/api-guides/build-system.rst
View File

@ -1057,7 +1057,9 @@ Flash 参数
子项目通过 :idf_file:`/components/bootloader/project_include.cmake` 文件作为外部项目插入到项目的顶层，主构建进程会运行子项目的 CMake，包括查找组件（主项目使用的组件的子集），生成引导程序专用的配置文件（从主 ``sdkconfig`` 文件中派生）。
.. _selecting-idf-target:
..
Label removed here because of the conflict with the english docs restructuring.
When translating please follow the structure in the english docs.
选择目标芯片
====================

1
docs/zh_CN/api-guides/tools/idf-py.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../../en/api-guides/tools/idf-py.rst

13
docs/zh_CN/api-guides/tools/index.rst
View File

@ -4,9 +4,10 @@
.. toctree::
:maxdepth: 1
IDF Tools <idf-tools>
IDF 监视器 <idf-monitor>
IDF Docker image <idf-docker-image>
IDF Windows Installer <idf-windows-installer>
IDF Component Manager <idf-component-manager>
IDF Clang Tidy <idf-clang-tidy>
idf-py
idf-monitor
idf-docker-image
idf-windows-installer
idf-component-manager
idf-clang-tidy
idf-tools