diff --git a/Kconfig b/Kconfig index e4c1a89b1..ad049f5db 100644 --- a/Kconfig +++ b/Kconfig @@ -46,11 +46,11 @@ mainmenu "Espressif IoT Development Framework Configuration" The executable name/path that is used to run python. On some systems Python 2.x may need to be invoked as python2. - (Note: This option is used with the GNU Make build system only, not idf.py - or CMake-based builds.) + (Note: This option is used with the legacy GNU Make build system only.) config SDK_MAKE_WARN_UNDEFINED_VARIABLES bool "'make' warns on undefined variables" + depends on !IDF_CMAKE default "y" help Adds --warn-undefined-variables to MAKEFLAGS. This causes make to @@ -60,6 +60,8 @@ mainmenu "Espressif IoT Development Framework Configuration" or otherwise missing, but it can be unwanted if you have Makefiles which depend on undefined variables expanding to an empty string. + (Note: this option is used with the legacy GNU Make build system only.) + endmenu # SDK tool configuration source "$COMPONENT_KCONFIGS_PROJBUILD" diff --git a/README.md b/README.md index bbb8d3a54..19c9980dd 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,17 @@ To start your own project based on an example, copy the example project director See the Getting Started guide links above for a detailed setup guide. This is a quick reference for common commands when working with ESP-IDF projects: +## Setup Build Environment + +(See Getting Started guide for a full list of required steps with details.) + +* Install host build dependencies mentioned in Getting Started guide. +* Add `tools/` directory to the PATH +* Run `python -m pip install requirements.txt` to install Python dependencies + ## Configuring the Project -`make menuconfig` +`idf.py menuconfig` * Opens a text-based configuration menu for the project. * Use up & down arrow keys to navigate the menu. @@ -49,76 +57,48 @@ Once done configuring, press Escape multiple times to exit and say "Yes" to save ## Compiling the Project -`make -j4 all` +`idf.py build` ... will compile app, bootloader and generate a partition table based on the config. -NOTE: The `-j4` option causes `make` to run 4 parallel jobs. This is much faster than the default single job. The recommended number to pass to this option is `-j(number of CPUs + 1)`. - ## Flashing the Project When the build finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this automatically by running: -`make -j4 flash` +`idf.py -p PORT flash` -This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`. +Replace PORT with the name of your serial port (like `COM3` on Windows, `/dev/ttyUSB0` on Linux, or `/dev/cu.usbserial-X` on MacOS. If the `-p` option is left out, `idf.py flash` will try to flash the first available serial port. -You don't need to run `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it. +This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `idf.py menuconfig`. + +You don't need to run `idf.py build` before running `idf.py flash`, `idf.py flash` will automatically rebuild anything which needs it. ## Viewing Serial Output -The `make monitor` target uses the [idf_monitor tool](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html). +The `idf.py monitor` target uses the [idf_monitor tool](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/idf-monitor.html). Exit the monitor by typing Ctrl-]. To build, flash and monitor output in one pass, you can run: -`make -j4 flash monitor` +`idf.py flash monitor` ## Compiling & Flashing Only the App After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table: -* `make app` - build just the app. -* `make app-flash` - flash just the app. +* `idf.py app` - build just the app. +* `idf.py app-flash` - flash just the app. -`make app-flash` will automatically rebuild the app if any source files have changed. +`idf.py app-flash` will automatically rebuild the app if any source files have changed. (In normal development there's no downside to reflashing the bootloader and partition table each time, if they haven't changed.) -## Parallel Builds - -ESP-IDF supports compiling multiple files in parallel, so all of the above commands can be run as `make -jN` where `N` is the number of parallel make processes to run (generally N should be equal to the number of CPU cores in your system, plus one.) - -Multiple make functions can be combined into one. For example: to build the app & bootloader using 5 jobs in parallel, then flash everything, and then display serial output from the ESP32 run: - -``` -make -j5 flash monitor -``` - - -## The Partition Table - -Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader. - -A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x8000 in the flash. - -Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded. - -The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables: - -* "Single factory app, no OTA" -* "Factory app, two OTA definitions" - -In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table. - -For more details about partition tables and how to create custom variations, view the [`docs/en/api-guides/partition-tables.rst`](docs/en/api-guides/partition-tables.rst) file. - ## Erasing Flash -The `make flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `make erase_flash`. +The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase_flash`. -This can be combined with other targets, ie `make erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table. +This can be combined with other targets, ie `idf.py -p PORT erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table. # Resources diff --git a/components/esptool_py/Kconfig.projbuild b/components/esptool_py/Kconfig.projbuild index 95919bd00..e11f9c7d5 100644 --- a/components/esptool_py/Kconfig.projbuild +++ b/components/esptool_py/Kconfig.projbuild @@ -135,8 +135,9 @@ menu "Serial flasher config" bool "Detect flash size when flashing bootloader" default y help - If this option is set, 'make flash' targets will automatically detect - the flash size and update the bootloader image when flashing. + If this option is set, flashing the project will automatically detect + the flash size of the target chip and update the bootloader image + before it is flashed. choice ESPTOOLPY_BEFORE prompt "Before flashing" @@ -181,11 +182,11 @@ menu "Serial flasher config" default "no_reset" if ESPTOOLPY_AFTER_NORESET choice ESPTOOLPY_MONITOR_BAUD - prompt "'make monitor' baud rate" + prompt "'idf.py monitor' baud rate" default ESPTOOLPY_MONITOR_BAUD_115200B help - Baud rate to use when running 'make monitor' to view serial output - from a running chip. + Baud rate to use when running 'idf.py monitor' or 'make monitor' + to view serial output from a running chip. Can override by setting the MONITORBAUD environment variable. diff --git a/components/nvs_flash/README.rst b/components/nvs_flash/README.rst index f8c2f4a1f..4638b644b 100644 --- a/components/nvs_flash/README.rst +++ b/components/nvs_flash/README.rst @@ -14,7 +14,7 @@ Currently, NVS uses a portion of main flash memory through ``spi_flash_{read|wri Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc. -.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``make erase_flash`` target to erase all contents of the flash chip. +.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``idf.py erase_flash`` target to erase all contents of the flash chip. .. note:: NVS works best for storing many small values, rather than a few large values of the type 'string' and 'blob'. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library. diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index 782dfbba9..f9c7ecaa0 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -73,7 +73,7 @@ SPI Flash Size The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000. -By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. +By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in project configuration. If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``esp_flash_*`` functions (in both software & ROM) to check the bounds. diff --git a/components/spi_flash/README_legacy.rst b/components/spi_flash/README_legacy.rst index a8e5da15a..a9a2c6913 100644 --- a/components/spi_flash/README_legacy.rst +++ b/components/spi_flash/README_legacy.rst @@ -29,7 +29,7 @@ SPI Flash Size The SPI flash size is configured by writing a field in the software bootloader image header, flashed at offset 0x1000. -By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. +By default, the SPI flash size is detected by esptool.py when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE` in project configuration. If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``spi_flash_*`` functions (in both software & ROM) to check the bounds. diff --git a/docs/TEMPLATE_EXAMPLE_README.md b/docs/TEMPLATE_EXAMPLE_README.md index 81bf6b342..c641f8d64 100644 --- a/docs/TEMPLATE_EXAMPLE_README.md +++ b/docs/TEMPLATE_EXAMPLE_README.md @@ -23,21 +23,21 @@ _If any other items (server, BLE device, app, second chip, whatever) are needed, ### Configure the project ``` -make menuconfig +idf.py menuconfig ``` -* Set serial port under Serial Flasher Options. - -* _If there is any menuconfig configuration that the user user must set for this example, mention this here._ +* _If there is any project configuration that the user must set for this example, mention this here._ ### Build and Flash Build the project and flash it to the board, then run monitor tool to view serial output: ``` -make -j4 flash monitor +idf.py -p PORT flash monitor ``` +(Replace PORT with the name of the serial port to use.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. diff --git a/docs/conf_common.py b/docs/conf_common.py index 8bd4eb988..8fd13cbaf 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -18,6 +18,7 @@ from __future__ import print_function from __future__ import unicode_literals import sys import os +import re import subprocess # Note: If extensions (or modules to document with autodoc) are in another directory, @@ -235,25 +236,14 @@ pygments_style = 'sphinx' # Custom added feature to allow redirecting old URLs # -# list of tuples (old_url, new_url) for pages to redirect -# (URLs should be relative to document root, only) -html_redirect_pages = [('api-reference/ethernet/index', 'api-reference/network/index'), - ('api-reference/ethernet/esp_eth', 'api-reference/network/esp_eth'), - ('api-reference/mesh/index', 'api-reference/network/index'), - ('api-reference/mesh/esp_mesh', 'api-reference/network/esp_mesh'), - ('api-reference/wifi/index', 'api-reference/network/index'), - ('api-reference/wifi/esp_now', 'api-reference/network/esp_now'), - ('api-reference/wifi/esp_smartconfig', 'api-reference/network/esp_smartconfig'), - ('api-reference/wifi/esp_wifi', 'api-reference/network/esp_wifi'), - ('api-reference/system/tcpip_adapter', 'api-reference/network/tcpip_adapter'), - ('get-started/idf-monitor', 'api-guides/tools/idf-monitor'), - ('get-started-cmake/idf-monitor', 'api-guides/tools/idf-monitor'), - ('get-started/get-started-devkitc', 'hw-reference/get-started-devkitc'), - ('get-started/get-started-wrover-kit', 'hw-reference/get-started-wrover-kit'), - ('get-started/get-started-pico-kit', 'hw-reference/get-started-pico-kit'), - ('get-started-cmake/get-started-devkitc', 'hw-reference/get-started-devkitc'), - ('get-started-cmake/get-started-wrover-kit', 'hw-reference/get-started-wrover-kit'), - ('get-started-cmake/get-started-pico-kit', 'hw-reference/get-started-pico-kit')] +# Redirects should be listed in page_redirects.xt +# +with open("../page_redirects.txt") as f: + lines = [re.sub(" +", " ", l.strip()) for l in f.readlines() if l.strip() != "" and not l.startswith("#")] + for line in lines: # check for well-formed entries + if len(line.split(' ')) != 2: + raise RuntimeError("Invalid line in page_redirects.txt: %s" % line) +html_redirect_pages = [tuple(l.split(' ')) for l in lines] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. diff --git a/docs/en/api-guides/app_trace.rst b/docs/en/api-guides/app_trace.rst index f2e348497..ccc9379de 100644 --- a/docs/en/api-guides/app_trace.rst +++ b/docs/en/api-guides/app_trace.rst @@ -149,7 +149,7 @@ In general user should decide what type of data should be transferred in every d return res; } -2. The next step is to build the program image and download it to the target as described in :doc:`Build and Flash <../get-started/make-project>`. +2. The next step is to build the program image and download it to the target as described in the :ref:`Getting Started Guide `. 3. Run OpenOCD (see :doc:`JTAG Debugging <../api-guides/jtag-debugging/index>`). 4. Connect to OpenOCD telnet server. It can be done using the following command in terminal ``telnet 4444``. If telnet session is opened on the same machine which runs OpenOCD you can use ``localhost`` as ```` in the command above. 5. Start trace data collection using special OpenOCD command. This command will transfer tracing data and redirect them to specified file or socket (currently only files are supported as trace data destination). For description of the corresponding commands see `OpenOCD Application Level Tracing Commands`_. diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst deleted file mode 100644 index ec63c0fc4..000000000 --- a/docs/en/api-guides/build-system-cmake.rst +++ /dev/null @@ -1,1311 +0,0 @@ -Build System (CMake) -******************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -.. include:: ../cmake-pending-features.rst - -This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components". :doc:`Documentation for the GNU Make based build system ` is also available - -Read this document if you want to know how to organise and build a new ESP-IDF project or component using the CMake-based build system. - - -Overview -======== - -An ESP-IDF project can be seen as an amalgamation of a number of components. -For example, for a webserver that shows the current humidity, there could be: - -- The ESP32 base libraries (libc, ROM bindings, etc) -- The WiFi drivers -- A TCP/IP stack -- The FreeRTOS operating system -- A webserver -- A driver for the humidity sensor -- Main code tying it all together - -ESP-IDF makes these components explicit and configurable. To do that, -when a project is compiled, the build system will look up all the -components in the ESP-IDF directories, the project directories and -(optionally) in additional custom component directories. It then -allows the user to configure the ESP-IDF project using a a text-based -menu system to customize each component. After the components in the -project are configured, the build system will compile the project. - -Concepts --------- - -- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader. - -- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. - -- An "app" is an executable which is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). - -- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places. - -- "Target" is the hardware for which an application is built. At the moment, ESP-IDF supports only one target, ``esp32``. - -Some things are not part of the project: - -- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project. - -- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH. - -Using the Build System -====================== - -.. _idf.py: - -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`) -- `esptool.py`_ for flashing ESP32. - -The :ref:`getting started guide ` 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, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``. - -Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones: - -- ``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 an ESP32. 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 ESP32. 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 ESP32 before running the serial monitor. - -.. 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. - -.. _idf.py-size: - -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 ESP32. -- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32'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. -- ``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``. - -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.). - -Using CMake Directly --------------------- - -:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer. - -.. highlight:: bash - -When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt):: - - mkdir -p build - cd build - cmake .. -G Ninja # or 'Unix Makefiles' - ninja - -In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: running ``ninja`` actually builds the project. - -It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration. - -If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``. - -.. note:: - If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components. - -.. _flash-with-ninja-or-make: - -Flashing with ninja or make -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It's possible to build and flash directly from ninja or make by running a target like:: - - ninja flash - -Or:: - - make app-flash - -Available targets are: ``flash``, ``app-flash`` (app only), ``bootloader-flash`` (bootloader only). - -When flashing this way, optionally set the ``ESPPORT`` and ``ESPBAUD`` environment variables to specify the serial port and baud rate. You can set environment variables in your operating system or IDE project. Alternatively, set them directly on the command line:: - - ESPPORT=/dev/ttyUSB0 ninja flash - -.. note:: Providing environment variables at the start of the command like this is Bash shell Syntax. It will work on Linux and macOS. It won't work when using Windows Command Prompt, but it will work when using Bash-like shells on Windows. - -Or:: - - make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000 - -.. note:: Providing variables at the end of the command line is ``make`` syntax, and works for ``make`` on all platforms. - - -Using CMake in an IDE ---------------------- - -You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE. - -When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands. - -For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_. - -.. _setting-python-interpreter: - -Setting the Python Interpreter ------------------------------- - -Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems. - -If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command. - -If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter. - -If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter. - -To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version. - -.. _example-project-structure: - -Example Project -=============== - -.. highlight:: none - -An example project directory tree might look like this:: - - - myProject/ - - CMakeLists.txt - - sdkconfig - - components/ - component1/ - CMakeLists.txt - - Kconfig - - src1.c - - component2/ - CMakeLists.txt - - Kconfig - - src1.c - - include/ - component2.h - - main/ - src1.c - - src2.c - - - build/ - -This example "myProject" contains the following elements: - -- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file :idf_file:`/tools/cmake/project.cmake` which - implements the rest of the build system. Finally, it sets the project name and defines the project. - -- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project. - -- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF. - -- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places. See the :ref:`renaming main ` section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main". - -- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. - -Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions -to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details. - -Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_. - -Project CMakeLists File -======================= - -Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal. - -Minimal Example CMakeLists --------------------------- - -.. highlight:: cmake - -Minimal project:: - - cmake_minimum_required(VERSION 3.5) - include($ENV{IDF_PATH}/tools/cmake/project.cmake) - project(myProject) - - -.. _project-mandatory-parts: - -Mandatory Parts ---------------- - -The inclusion of these three lines, in the order shown above, is necessary for every project: - -- ``cmake_minimum_required(VERSION 3.5)`` tells CMake the minimum version that is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file. -- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc. -- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file. - - -Optional Project Variables --------------------------- - -These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details. - -- ``COMPONENT_DIRS``,``COMPONENTS_DIRS``: Directories to search for components. Defaults to `IDF_PATH/components`, `PROJECT_DIR/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. -- ``EXTRA_COMPONENT_DIRS``, ``EXTRA_COMPONENTS_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute. -- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via the REQUIRES or PRIV_REQUIRES arguments on component registration will automatically have it added to this list, so the ``COMPONENTS`` list can be very short. - -Any paths in these variables can be absolute paths, or set relative to the project directory. - -To set these variables, use the `cmake set command `_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line. - -.. _rename-main-cmake: - -Renaming ``main`` component ----------------------------- - -The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided -that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, -saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component -causes the loss of these behind-the-scences heavy lifting, requiring the user to specify the location of the newly renamed component -and manually specifying its dependencies. Specifically, the steps to renaming ``main`` are as follows: - -1. Rename ``main`` directory. -2. Set ``EXTRA_COMPONENT_DIRS`` in the project CMakeLists.txt to include the renamed ``main`` directory. -3. Specify the dependencies in the renamed component's CMakeLists.txt file via REQUIRES or PRIV_REQUIRES arguments :ref:`on component registration`. - -.. _component-directories-cmake: - -Component CMakeLists Files -========================== - -Each project contains one or more components. Components can be part of ESP-IDF, part of the project's own components directory, or added from custom component directories (:ref:`see above `). - -A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file. - -Searching for Components ------------------------- - -The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose sub-directories are components. - -When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components. - -Multiple components with the same name --------------------------------------- - -When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories -contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components -with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. -If used in this way, the ESP-IDF directory itself can remain untouched. - -.. _cmake_minimal_component_cmakelists: - -Minimal Component CMakeLists ----------------------------- - -.. highlight:: cmake - -The minimal component ``CMakeLists.txt`` file simply registers the component to the build system using ``idf_component_register``:: - - idf_component_register(SRCS "foo.c" "bar.c" - INCLUDE_DIRS "include") - -- ``SRCS`` is a list of source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``). These source files will be compiled into the component library. -- ``INCLUDE_DIRS`` is a list of directories to add to the global include search path for any component which requires this component, and also the main source files. - -A library with the name of the component will be built and linked into the final app. -Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute. - -There are other arguments that can be passed to ``idf_component_register``. These arguments -are discussed :ref:`here`. - -See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples. - -.. _component variables: - -Preset Component Variables --------------------------- - -The following component-specific variables are available for use inside component CMakeLists, but should not be modified: - -- ``COMPONENT_DIR``: The component directory. Evaluates to the absolute path of the directory containing ``CMakeLists.txt``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable. -- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory. -- ``COMPONENT_ALIAS``: Alias of the library created internally by the build system for the component. -- ``COMPONENT_LIB``: Name of the library created internally by the build system for the component. - -The following variables are set at the project level, but available for use in component CMakeLists: - -- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in cmake. All names begin with ``CONFIG_``. :doc:`More information here `. -- ``ESP_PLATFORM``: Set to 1 when the CMake file is processed within ESP-IDF build system. - -Build/Project Variables ------------------------- - -The following are some project/build variables that are available as build properties and whose values can be queried using ``idf_build_get_property`` -from the component CMakeLists.txt: - -- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file. -- ``PROJECT_DIR``: Absolute path of the project directory containing the project CMakeLists. Same as the ``CMAKE_SOURCE_DIR`` variable. -- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list. -- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``) -- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``IDF_VERSION_*`` variables, but different ``IDF_VER`` values. -- ``IDF_TARGET``: Name of the target for which the project is being built. -- ``PROJECT_VER``: Project version. - - * If ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used. - * Else, if the ``PROJECT_DIR/version.txt`` exists, its contents will be used as ``PROJECT_VER``. - * Else, if the project is located inside a Git repository, the output of git describe will be used. - * Otherwise, ``PROJECT_VER`` will be "1". - -Other build properties are listed :ref:`here`. - -Controlling Component Compilation ---------------------------------- - -.. highlight:: cmake - -To pass compiler options when compiling source files belonging to a particular component, use the ``target_compile_options`` function:: - - target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable) - -To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command:: - - set_source_files_properties(mysrc.c - PROPERTIES COMPILE_FLAGS - -Wno-unused-variable - ) - -This can be useful if there is upstream code that emits warnings. - -When using these commands, place them after the call to ``idf_component_register`` in the component CMakeLists file. - -.. _component-configuration-cmake: - -Component Configuration -======================= - -Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains -configuration settings to add to the configuration menu for this component. - -These settings are found under the "Component Settings" menu when menuconfig is run. - -To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF. - -For an example, see `Adding conditional configuration`_. - -Preprocessor Definitions -======================== - -The ESP-IDF build system adds the following C preprocessor definitions on the command line: - -- ``ESP_PLATFORM`` : Can be used to detect that build happens within ESP-IDF. -- ``IDF_VER`` : Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit. - -Component Requirements -====================== - -When compiling each component, the ESP-IDF build system recursively evaluates its components. - -Each component's source file is compiled with these include path directories, as specified in the passed arguments -to ``idf_component_register``: - -- The current component's ``INCLUDE_DIRS`` and ``PRIV_INCLUDE_DIRS``. -- The ``INCLUDE_DIRS`` set by all components in the current component's ``REQUIRES`` and ``PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies). -- All of the ``REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded). - -When writing a component ------------------------- - -- ``REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component. -- ``PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly. -- ``REQUIRES`` and/or ``PRIV_REQUIRES`` should be set before calling ``idf_component_register()``. -- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices. -- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset. - -Components which support only some targets (values of ``IDF_TARGET``) may specify ``REQUIRED_IDF_TARGETS`` in the ``idf_component_register`` call to express these requirements. In this case the build system will generate an error if the component is included into the build, but does not support selected target. - -When creating a project ------------------------ - -- By default, every component is included in the build. -- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include: - - - Components mentioned explicitly in ``COMPONENTS``. - - Those components' requirements (evaluated recursively). - - The "common" components that every component depends on. -- Setting ``COMPONENTS`` to the minimal list of required components can significantly reduce compile times. - -.. _component-requirements-implementation: - -Requirements in the build system implementation ------------------------------------------------ - -- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory. -- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable). The ``BUILD_COMPONENTS`` variable is sorted so dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies. -- The value of ``BUILD_COMPONENTS`` is logged by CMake as "Component names: " -- Configuration is then evaluated for the components included in the build. -- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build. - -Component Dependency Order -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The order of components in the ``BUILD_COMPONENTS`` variable determines other orderings during the build: - -- Order that :ref:`project_include.cmake` files are included into the project. -- Order that the list of header paths is generated for compilation (via ``-I`` argument). (Note that for a given component's source files, only that component's dependency's header paths are passed to the compiler.) - -Build Process Internals -======================= - -For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`_. - -project.cmake contents ----------------------- - -When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environment. - -It also defines an overridden custom version of the built-in CMake_ ``project`` function. This function is overridden to add all of the ESP-IDF specific project functionality. - -project function ----------------- - -The custom ``project()`` function performs the following steps: - -- Determines the target (set by ``IDF_TARGET`` environment variable) and saves the target in CMake cache. If the target set in the environment does not match the one in cache, exits with an error. -- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above`). -- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set). -- Loads the project configuration from the ``sdkconfig`` file and generates a ``sdkconfig.cmake`` file and a ``sdkconfig.h`` header. These define configuration values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to re-generate these files and re-configure the project. -- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the correct toolchain file, depending on the target. -- Declares the actual cmake-level project by calling the `CMake project function `_. -- Loads the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_. -- Includes :ref:`project_include.cmake` files from any components which have them. -- Adds each component to the build. Each component CMakeLists file calls ``idf_component_register``, calls the CMake `add_library `_ function to add a library and then adds source files, compile options, etc. -- Adds the final app executable to the build. -- Goes back and adds inter-component dependencies between components (ie adding the public header directories of each component to each other component). - -Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details. - -Debugging CMake ---------------- - -Some tips for debugging the ESP-IDF CMake-based build system: - -- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths. -- Running ``cmake -DDEBUG=1`` will produce more verbose diagnostic output from the IDF build system. -- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_. - -.. _warn-undefined-variables-cmake: - -Warning On Undefined Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files. - -If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``. - -Overriding Parts of the Project -------------------------------- - -.. _project_include.cmake: - -project_include.cmake -^^^^^^^^^^^^^^^^^^^^^ - -For components that have build requirements which must be evaluated before any component CMakeLists -files are evaluated, you can create a file called ``project_include.cmake`` in the -component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project. - -``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". - -Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cmake`` file the current source directory (``CMAKE_CURRENT_SOURCE_DIR`` and working directory) is the project directory. Use the variable ``COMPONENT_DIR`` for the absolute directory of the component. - -Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details. - -``project_include.cmake`` files are included in the order given in ``BUILD_COMPONENTS`` variable (as logged by CMake). This means that a component's ``project_include.cmake`` file will be included after it's all dependencies' ``project_include.cmake`` files, unless both components are part of a dependency cycle. This is important if a ``project_include.cmake`` file relies on variables set by another component. See also :ref:`above`. - -Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components! - -KConfig.projbuild -^^^^^^^^^^^^^^^^^ - -This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration-cmake` KConfig files. If you want to include -configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file. - -Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for :ref:`component-configuration-cmake`. - - -Configuration-Only Components -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``idf_component_register()`` with no -arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths. - -Example Component CMakeLists -============================ - -Because the build environment tries to set reasonable defaults that will work most -of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality. - -Here are some more advanced examples of component CMakeLists files. - -Adding conditional configuration --------------------------------- - -The configuration system can be used to conditionally compile some files -depending on the options selected in the project configuration. - -.. highlight:: none - -``Kconfig``:: - - config FOO_ENABLE_BAR - bool "Enable the BAR feature." - help - This enables the BAR feature of the FOO component. - -``CMakeLists.txt``:: - - set(COMPONENT_SRCS "foo.c" "more_foo.c") - - if(CONFIG_FOO_ENABLE_BAR) - list(APPEND COMPONENT_SRCS "bar.c") - endif() - -This example makes use of the CMake `if `_ function and `list APPEND `_ function. - -This can also be used to select or stub out an implementation, as such: - -``Kconfig``:: - - config ENABLE_LCD_OUTPUT - bool "Enable LCD output." - help - Select this if your board has a LCD. - - config ENABLE_LCD_CONSOLE - bool "Output console text to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output debugging output to the lcd - - config ENABLE_LCD_PLOT - bool "Output temperature plots to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output temperature plots - -.. highlight:: cmake - -``CMakeLists.txt``:: - - if(CONFIG_ENABLE_LCD_OUTPUT) - set(COMPONENT_SRCS lcd-real.c lcd-spi.c) - else() - set(COMPONENT_SRCS lcd-dummy.c) - endif() - - # We need font if either console or plot is enabled - if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT) - list(APPEND COMPONENT_SRCS "font.c") - endif() - - -Conditions which depend on the target -------------------------------------- - -The current target is available to CMake files via ``IDF_TARGET`` variable. - -In addition to that, if target ``xyz`` is used (``IDF_TARGET=xyz``), then Kconfig variable ``CONFIG_IDF_TARGET_XYZ`` will be set. - -Note that component dependencies may depend on ``IDF_TARGET`` variable, but not on Kconfig variables. Also one can not use Kconfig variables in ``include`` statements in CMake files, but ``IDF_TARGET`` can be used in such context. - - -Source Code Generation ----------------------- - -Some components will have a situation where a source file isn't -supplied with the component itself but has to be generated from -another file. Say our component has a header file that consists of the -converted binary data of a BMP file, converted using a hypothetical -tool called bmp2h. The header file is then included in as C source -file called graphics_lib.c:: - - add_custom_command(OUTPUT logo.h - COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h - DEPENDS ${COMPONENT_DIR}/logo.bmp - VERBATIM) - - add_custom_target(logo DEPENDS logo.h) - add_dependencies(${COMPONENT_LIB} logo) - - set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY - ADDITIONAL_MAKE_CLEAN_FILES logo.h) - -This answer is adapted from the `CMake FAQ entry `_, which contains some other examples that will also work with ESP-IDF builds. - -In this example, logo.h will be generated in the -current directory (the build directory) while logo.bmp comes with the -component and resides under the component path. Because logo.h is a -generated file, it should be cleaned when the project is cleaned. For this reason -it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property. - -.. note:: - - If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use build property ``PROJECT_DIR`` instead of ``${COMPONENT_DIR}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_LIB}``.) - -If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between -the two components, to ensure that the component source files were always compiled in the correct order. - -.. _cmake_embed_data: - -Embedding Binary Data ---------------------- - -Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source. - -You can specify argument ``COMPONENT_EMBED_FILES`` in the component registration, giving space-delimited names of the files to embed:: - - idf_component_register(... - EMBED_FILES server_root_cert.der) - - -Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string:: - - idf_component_register(... - EMBED_TXTFILES server_root_cert.pem) - -.. highlight:: c - -The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows:: - - extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); - extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); - -The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. - -.. highlight:: cmake - -To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this:: - - target_add_binary_data(myproject.elf "main/data.bin" TEXT) - -Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is. - -For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time. - -Code and Data Placements ------------------------- - -ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through -linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking -app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion -of the mechanism. - -.. _component-build-full-override: - -Fully Overriding The Component Build Process --------------------------------------------- - -.. highlight:: cmake - -Obviously, there are cases where all these recipes are insufficient for a -certain component, for example when the component is basically a wrapper -around another third-party component not originally intended to be -compiled under this build system. In that case, it's possible to forego -the ESP-IDF build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists:: - - # External build process for quirc, runs in source dir and - # produces libquirc.a - externalproject_add(quirc_build - PREFIX ${COMPONENT_DIR} - SOURCE_DIR ${COMPONENT_DIR}/quirc - CONFIGURE_COMMAND "" - BUILD_IN_SOURCE 1 - BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a - INSTALL_COMMAND "" - ) - - # Add libquirc.a to the build process - # - add_library(quirc STATIC IMPORTED GLOBAL) - add_dependencies(quirc quirc_build) - - set_target_properties(quirc PROPERTIES IMPORTED_LOCATION - ${COMPONENT_DIR}/quirc/libquirc.a) - set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES - ${COMPONENT_DIR}/quirc/lib) - - set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES - "${COMPONENT_DIR}/quirc/libquirc.a") - -(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.) - -- ``externalproject_add`` defines an external build system. - - - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds. - - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``. - - Consult the ExternalProject_ documentation for more details about ``externalproject_add()`` - -- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is. -- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.) - -.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. - -.. _ADDITIONAL_MAKE_CLEAN_FILES_note: - -ExternalProject dependencies, clean builds -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CMake has some unusual behaviour around external project builds: - -- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning. -- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run. -- Therefore, there are two alternative recommended ways to configure the external build command: - - 1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.) - 2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run. - -The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project. - -.. _custom-sdkconfig-defaults-cmake: - -Custom sdkconfig defaults -========================= - -For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file. - -To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable. - -Target-dependent sdkconfig defaults ------------------------------------ - -In addition to ``sdkconfig.defaults`` file, build system will also load defaults from ``sdkconfig.defaults.TARGET_NAME`` file, where ``TARGET_NAME`` is the value of ``IDF_TARGET``. For example, for ``esp32`` target, default settings will be taken from ``sdkconfig.defaults`` first, and then from ``sdkconfig.defaults.esp32``. - -If ``SDKCONFIG_DEFAULTS`` is used to override the name of defaults file, the name of target-specific defaults file will be derived from ``SDKCONFIG_DEFAULTS`` value. - - -Flash arguments -=============== - -There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. - -After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files: - -- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured). -- ``flash_app_args`` contains arguments to flash only the app. -- ``flash_bootloader_args`` contains arguments to flash only the bootloader. - -.. highlight:: bash - -You can pass any of these flasher argument files to ``esptool.py`` as follows:: - - python esptool.py --chip esp32 write_flash @build/flash_project_args - -Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line. - -The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build. - -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 the Target -==================== - -Currently ESP-IDF supports one target, ``esp32``. It is used by default by the build system. Developers working on adding multiple target support can change the target as follows:: - - rm sdkconfig - idf.py -DIDF_TARGET=new_target reconfigure - - -Writing Pure CMake Components -============================= - -The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build. - -However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake. - -.. highlight:: cmake - -Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``:: - - add_library(json STATIC - cJSON/cJSON.c - cJSON/cJSON_Utils.c) - - target_include_directories(json PUBLIC cJSON) - -- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`. -- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.) -- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands. - - -Using Third-Party CMake Projects with Components -================================================ - -CMake is used for a lot of open-source C and C++ projects — code that users can tap into for their applications. One of the benefits of having a CMake build system -is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may -not yet be provided by a component, or use another library for the same functionality. - -.. highlight:: cmake - -Importing a library might look like this for a hypothetical library ``foo`` to be used in the ``main`` component:: - - # Register the component - idf_component_register() - - # Set values of hypothetical variables that control the build of `foo` - set(FOO_BUILD_STATIC OFF) - set(FOO_BUILD_TESTS OFF) - - # Create and import the library targets - add_subdirectory(foo) - - # Link `foo` to `main` component - target_link_libraries(main foo) - -For an actual example, take a look at :example:`build_system/cmake/import_lib`. Take note that what needs to be done in order to import -the library may vary. It is recommended to read up on the library's documentation for instructions on how to -import it from other projects. Studying the library's CMakeLists.txt and build structure can also be helpful. - -It is also possible to wrap a third-party library to be used as a component in this manner. For example, the :component:`mbedtls` component is a wrapper for -Espressif's fork of `mbedtls `_. See its :component_file:`component CMakeLists.txt `. - -The CMake variable ``ESP_PLATFORM`` is set to 1 whenever the ESP-IDF build system is being used. Tests such as ``if (ESP_PLATFORM)`` can be used in generic CMake code if special IDF-specific logic is required. - - -Using ESP-IDF in Custom CMake Projects -====================================== - -ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already -have an existing CMake project or may want to create a custom one. In these cases it is desirable to be able to consume IDF components -as libraries to be linked to the user's targets (libraries/ executables). - -It is possible to do so by using the :ref:`build system APIs provided` by :idf_file:`tools/cmake/idf.cmake`. For example: - -.. code-block:: cmake - - cmake_minimum_required(VERSION 3.5) - project(my_custom_app C) - - # Include CMake file that provides ESP-IDF CMake build system APIs. - include($ENV{IDF_PATH}/tools/cmake/idf.cmake) - - # Include ESP-IDF components in the build, may be thought as an equivalent of - # add_subdirectory() but with some additional procesing and magic for ESP-IDF build - # specific build processes. - idf_build_process(esp32) - - # Create the project executable and plainly link the newlib component to it using - # its alias, idf::newlib. - add_executable(${CMAKE_PROJECT_NAME}.elf main.c) - target_link_libraries(${CMAKE_PROJECT_NAME}.elf idf::newlib) - - # Let the build system know what the project executable is to attach more targets, dependencies, etc. - idf_build_executable(${CMAKE_PROJECT_NAME}.elf) - -The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creation of an application equivalent to :example:`hello world application ` -using a custom CMake project. - -.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. -.. _cmake_buildsystem_api: - -ESP-IDF CMake Build System API -============================== - -idf-build-commands ------------------- - -.. code-block:: none - - idf_build_get_property(var property [GENERATOR_EXPRESSION]) - -Retrieve a :ref:`build property` *property* and store it in *var* accessible from the current scope. Specifying -*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which -can be used with CMake commands that support generator expressions. - -.. code-block:: none - - idf_build_set_property(property val [APPEND]) - -Set a :ref:`build property` *property* with value *val*. Specifying *APPEND* will append the specified value to the current -value of the property. If the property does not previously exist or it is currently empty, the specified value becomes -the first element/member instead. - -.. code-block:: none - - idf_build_component(component_dir) - -Present a directory *component_dir* that contains a component to the build system. Relative paths are converted to absolute paths with respect to current directory. -All calls to this command must be performed before `idf_build_process`. - -This command does not guarantee that the component will be processed during build (see the `COMPONENTS` argument description for `idf_build_process`) - -.. code-block:: none - - idf_build_process(target - [PROJECT_DIR project_dir] - [PROJECT_VER project_ver] - [PROJECT_NAME project_name] - [SDKCONFIG sdkconfig] - [SDKCONFIG_DEFAULTS sdkconfig_defaults] - [BUILD_DIR build_dir] - [COMPONENTS component1 component2 ...]) - -Performs the bulk of the behind-the-scenes magic for including ESP-IDF components such as component configuration, libraries creation, -dependency expansion and resolution. Among these functions, perhaps the most important -from a user's perspective is the libraries creation by calling each component's ``idf_component_register``. This command creates the libraries for each component, which are accessible using aliases in the form -idf::*component_name*. These aliases can be used to link the components to the user's own targets, either libraries -or executables. - -The call requires the target chip to be specified with *target* argument. Optional arguments for the call include: - -- PROJECT_DIR - directory of the project; defaults to CMAKE_SOURCE_DIR -- PROJECT_NAME - name of the project; defaults to CMAKE_PROJECT_NAME -- PROJECT_VER - version/revision of the project; defaults to "0.0.0" -- SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set -- SDKCONFIG_DEFAULTS - defaults file to use for the build; defaults to empty -- BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, components; defaults to CMAKE_BINARY_DIR -- COMPONENTS - select components to process among the components known by the build system (added via `idf_build_component`). This argument is used to trim the build. - Other components are automatically added if they are required in the dependency chain, i.e. - the public and private requirements of the components in this list are automatically added, and in turn the public and private requirements of those requirements, - so on and so forth. If not specified, all components known to the build system are processed. - -.. code-block:: none - - idf_build_executable(executable) - -Specify the executable *executable* for ESP-IDF build. This attaches additional targets such as dependencies related to -flashing, generating additional binary files, etc. Should be called after ``idf_build_process``. - -.. code-block:: none - - idf_build_get_config(var config [GENERATOR_EXPRESSION]) - -Get the value of the specified config. Much like build properties, specifying -*GENERATOR_EXPRESSION* will retrieve the generator expression string for that config, instead of the actual value, which -can be used with CMake commands that support generator expressions. Actual config values are only known after call to `idf_build_process`, however. - -.. _cmake-build-properties: - -idf-build-properties --------------------- - -These are properties that describe the build. Values of build properties can be retrieved by using the build command ``idf_build_get_property``. -For example, to get the Python interpreter used for the build: - -.. code-block: cmake - - idf_build_get_property(python PYTHON) - message(STATUS "The Python intepreter is: ${python}") - - - BUILD_DIR - build directory; set from ``idf_build_process`` BUILD_DIR argument - - BUILD_COMPONENTS - list of components (more specifically, component aliases) included in the build; set by ``idf_build_process`` - - C_COMPILE_OPTIONS - compile options applied to all components' C source files - - COMPILE_OPTIONS - compile options applied to all components' source files, regardless of it being C or C++ - - COMPILE_DEFINITIONS - compile definitions applied to all component source files - - CXX_COMPILE_OPTIONS - compile options applied to all components' C++ source files - - EXECUTABLE - project executable; set by call to ``idf_build_executable`` - - EXECUTABLE_NAME - name of project executable without extension; set by call to ``idf_build_executable`` - - IDF_PATH - ESP-IDF path; set from IDF_PATH environment variable, if not, inferred from the location of ``idf.cmake`` - - IDF_TARGET - target chip for the build; set from the required target argument for ``idf_build_process`` - - IDF_VER - ESP-IDF version; set from either a version file or the Git revision of the IDF_PATH repository - - INCLUDE_DIRECTORIES - include directories for all component source files - - KCONFIGS - list of Kconfig files found in components in build; set by ``idf_build_process`` - - KCONFIG_PROJBUILDS - list of Kconfig.projbuild diles found in components in build; set by ``idf_build_process`` - - PROJECT_NAME - name of the project; set from ``idf_build_process`` PROJECT_NAME argument - - PROJECT_DIR - directory of the project; set from ``idf_build_process`` PROJECT_DIR argument - - PROJECT_VER - version of the project; set from ``idf_build_process`` PROJECT_VER argument - - PYTHON - Python interpreter used for the build; set from PYTHON environment variable if available, if not "python" is used - - SDKCONFIG - full path to output config file; set from ``idf_build_process`` SDKCONFIG argument - - SDKCONFIG_DEFAULTS - full path to config defaults file; set from ``idf_build_process`` SDKCONFIG_DEFAULTS argument - - SDKCONFIG_HEADER - full path to C/C++ header file containing component configuration; set by ``idf_build_process`` - - SDKCONFIG_CMAKE - full path to CMake file containing component configuration; set by ``idf_build_process`` - - SDKCONFIG_JSON - full path to JSON file containing component configuration; set by ``idf_build_process`` - - SDKCONFIG_JSON_MENUS - full path to JSON file containing config menus; set by ``idf_build_process`` - -idf-component-commands ----------------------- - -.. code-block:: none - - idf_component_get_property(var component property [GENERATOR_EXPRESSION]) - -Retrieve a specified *component*'s :ref:`component property`, *property* and store it in *var* accessible from the current scope. Specifying -*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which -can be used with CMake commands that support generator expressions. - -.. code-block:: none - - idf_component_set_property(property val [APPEND]) - -Set a specified *component*'s :ref:`component property`, *property* with value *val*. Specifying *APPEND* will append the specified value to the current -value of the property. If the property does not previously exist or it is currently empty, the specified value becomes -the first element/member instead. - -.. _cmake-component-register: - -.. code-block:: none - - idf_component_register([[SRCS src1 src2 ...] | [[SRC_DIRS dir1 dir2 ...] [EXCLUDE_SRCS src1 src2 ...]] - [INCLUDE_DIRS dir1 dir2 ...] - [PRIV_INCLUDE_DIRS dir1 dir2 ...] - [REQUIRES component1 component2 ...] - [PRIV_REQUIRES component1 component2 ...] - [LDFRAGMENTS ldfragment1 ldfragment2 ...] - [REQUIRED_IDF_TARGETS target1 target2 ...] - [EMBED_FILES file1 file2 ...] - [EMBED_TXTFILES file1 file2 ...]) - -Register a component to the build system. Much like the ``project()`` CMake command, this should be called from the component's -CMakeLists.txt directly (not through a function or macro) and is recommended to be called before any other command. Here are some -guidelines on what commands can **not** be called before ``idf_component_register``: - - - commands that are not valid in CMake script mode - - custom commands defined in project_include.cmake - - build system API commands except ``idf_build_get_property``; although consider whether the property may not have been set yet - -Commands that set and operate on variables are generally okay to call before ``idf_component_register``. - -The arguments for ``idf_component_register`` include: - - - SRCS - component source files used for creating a static library for the component; if not specified, component is a treated as a - config-only component and an interface library is created instead. - - SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of specifying source files manually via SRCS. - Note that this is subject to the :ref:`limitations of globbing in CMake`. Source files specified in EXCLUDE_SRCS are removed from the globbed files. - - INCLUDE_DIRS - paths, relative to the component directory, which will be added to the include search path for all other components which require the current component - - PRIV_INCLUDE_DIRS - directory paths, must be relative to the component directory, which will be added to the include search path for this component's source files only - - REQUIRES - public component requirements for the component - - PRIV_REQUIRES - private component requirements for the component; ignored on config-only components - - LDFRAGMENTS - component linker fragment files - - REQUIRED_IDF_TARGETS - specify the only target the component supports - -The following are used for :ref:`embedding data into the component`, and is considered as source files -when determining if a component is config-only. This means that even if the component does not specify source files, a static library is still -created internally for the component if it specifies either: - - - EMBED_FILES - binary files to be embedded in the component - - EMBED_TXTFILES - text files to be embedded in the component - -.. _cmake-component-properties: - -idf-component-properties ------------------------- - -These are properties that describe a component. Values of component properties can be retrieved by using the build command ``idf_component_get_property``. -For example, to get the directory of the ``freertos`` component: - -.. code-block: cmake - - idf_component_get_property(dir freertos COMPONENT_DIR) - message(STATUS "The 'freertos' component directory is: ${dir}") - -- COMPONENT_ALIAS - alias for COMPONENT_LIB used for linking the component to external targets; set by ``idf_build_component`` and alias library itself - is created by ``idf_component_register`` -- COMPONENT_DIR - component directory; set by ``idf_build_component`` -- COMPONENT_LIB - name for created component static/interface library; set by ``idf_build_component`` and library itself - is created by ``idf_component_register`` -- COMPONENT_NAME - name of the component; set by ``idf_build_component`` based on the component directory name -- COMPONENT_TYPE - type of the component, whether LIBRARY or CONFIG_ONLY. A component is of type LIBRARY if it specifies - source files or embeds a file -- EMBED_FILES - list of files to embed in component; set from ``idf_component_register`` EMBED_FILES argument -- EMBED_TXTFILES - list of text files to embed in component; set from ``idf_component_register`` EMBED_TXTFILES argument -- INCLUDE_DIRS - list of component include directories; set from ``idf_component_register`` INCLUDE_DIRS argument -- KCONFIG - component Kconfig file; set by ``idf_build_component`` -- KCONFIG_PROJBUILD - component Kconfig.projbuild; set by ``idf_build_component`` -- LDFRAGMENTS - list of component linker fragment files; set from ``idf_component_register`` LDFRAGMENTS argument -- PRIV_INCLUDE_DIRS - list of component private include directories; set from ``idf_component_register`` PRIV_INCLUDE_DIRS on components of type LIBRARY -- PRIV_REQUIRES - list of private component dependentices; set from ``idf_component_register`` PRIV_REQUIRES argument -- REQUIRED_IDF_TARGETS - list of targets the component supports; set from ``idf_component_register`` EMBED_TXTFILES argument -- REQUIRES - list of public component dependencies; set from ``idf_component_register`` REQUIRES argument -- SRCS - list of component source files; set from SRCS or SRC_DIRS/EXCLUDE_SRCS argument of ``idf_component_register`` - -.. _cmake-file-globbing: - -File Globbing & Incremental Builds -================================== - -.. highlight:: cmake - -The preferred way to include source files in an ESP-IDF component is to list them manually via SRCS argument to ``idf_component_register``:: - - idf_component_register(SRCS library/a.c library/b.c platform/platform.c - ...) - -This preference reflects the `CMake best practice `_ of manually listing source files. This could, however, be inconvenient when there are lots of source files to add to the build. The ESP-IDF build system provides an alternative way for specifying source files using ``SRC_DIRS``:: - - idf_component_register(SRC_DIRS library platform - ...) - -This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new source file is added and this method is used, then CMake won't know to automatically re-run and this file won't be added to the build. - -The trade-off is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git... - -For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun. - -For project components (not part of ESP-IDF), there are a few different options: - -- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes. -- If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to automatically trigger re-runs of CMake when the Git revision changes. -- If not using Git, remember to manually run ``idf.py reconfigure`` whenever a source file may change. -- To avoid this problem entirely, use ``COMPONENT_SRCS`` to list all source files in project components. - -The best option will depend on your particular project and its users. - -Build System Metadata -===================== - -For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command). - -- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it. -- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc. -- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_. -- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc. -- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values. -- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs. - -JSON Configuration Server -------------------------- - -.. highlight :: json - -A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout. - -You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator. - -The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``:: - - {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } } - -Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.) - -The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline:: - - {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } } - -The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes:: - - {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}} - -Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value. - -If the range of a config item changes, due to conditional range depending on another value, then this is also sent:: - - {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } } - -If invalid data is passed, an "error" field is present on the object:: - - {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]} - -By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent:: - - {"version": 1, "save": null } - -To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent:: - - {"version": 1, "load": null } - -The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname. - -The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started. - -Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command. - -.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited. - -.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run. - -.. _gnu-make-to-cmake: - -Migrating from ESP-IDF GNU Make System -====================================== - -Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax. - -Automatic Conversion Tool -------------------------- - -.. highlight:: bash - -An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this:: - - $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir - -The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH. - -The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files. - -It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables. - -The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand. - -No Longer Available in CMake ----------------------------- - -Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system: - -- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead. -- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component. -- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here `_. -- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually. -- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead. -- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``. -- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repository. -- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute). -- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``. -- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead. -- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality `. -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details. -- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_. -- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_. - - -No Default Values ------------------ - -The following variables no longer have default values: - -- ``COMPONENT_SRCDIRS`` -- ``COMPONENT_ADD_INCLUDEDIRS`` - -No Longer Necessary -------------------- - -It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCS`` is ignored if ``COMPONENT_SRCDIRS`` is set). - -Flashing from make ------------------- - -``make flash`` and similar targets still work to build and flash. However, project ``sdkconfig`` no longer specifies serial port and baud rate. Environment variables can be used to override these. See :ref:`flash-with-ninja-or-make` for more details. - -.. _esp-idf-template: https://github.com/espressif/esp-idf-template -.. _cmake: https://cmake.org -.. _ninja: https://ninja-build.org -.. _esptool.py: https://github.com/espressif/esptool/#readme -.. _CMake v3.5 documentation: https://cmake.org/cmake/help/v3.5/index.html -.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options -.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/add_library.html -.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html -.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html -.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html -.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html -.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html -.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F -.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html -.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html -.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages -.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html -.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html -.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries -.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html -.. _quirc: https://github.com/dlbeer/quirc -.. _pyenv: https://github.com/pyenv/pyenv#README -.. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/en/api-guides/build-system-legacy.rst b/docs/en/api-guides/build-system-legacy.rst new file mode 100644 index 000000000..52ca8642c --- /dev/null +++ b/docs/en/api-guides/build-system-legacy.rst @@ -0,0 +1,652 @@ +Build System (Legacy GNU Make) +****************************** +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +This document explains the legacy GNU Make Espressif IoT Development Framework build system and the +concept of "components" + +Read this document if you want to know how to organise an ESP-IDF project using GNU Make build system. + +We recommend using the esp-idf-template_ project as a starting point for your project. + +Using the Build System +====================== + +The esp-idf README file contains a description of how to use the build system to build your project. + +Overview +======== + +An ESP-IDF project can be seen as an amalgamation of a number of components. +For example, for a webserver that shows the current humidity, there could be: + +- The ESP32 base libraries (libc, rom bindings etc) +- The Wi-Fi drivers +- A TCP/IP stack +- The FreeRTOS operating system +- A webserver +- A driver for the humidity sensor +- Main code tying it all together + +ESP-IDF makes these components explicit and configurable. To do that, +when a project is compiled, the build environment will look up all the +components in the ESP-IDF directories, the project directories and +(optionally) in additional custom component directories. It then +allows the user to configure the ESP-IDF project using a a text-based +menu system to customize each component. After the components in the +project are configured, the build process will compile the project. + +Concepts +-------- + +- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader. + +- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. + +- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). + +- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places. + +Some things are not part of the project: + +- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project. + +- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration. + + +Example Project +--------------- + +An example project directory tree might look like this:: + + - myProject/ + - Makefile + - sdkconfig + - components/ - component1/ - component.mk + - Kconfig + - src1.c + - component2/ - component.mk + - Kconfig + - src1.c + - include/ - component2.h + - main/ - src1.c + - src2.c + - component.mk + + - build/ + +This example "myProject" contains the following elements: + +- A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) defines + other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which + implements the rest of the ESP-IDF build system. + +- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project. + +- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF. + +- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places. + +- "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. + +Component directories contain a component makefile - ``component.mk``. This may contain variable definitions +to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details. + +Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`. + +Project Makefiles +----------------- + +Each project has a single Makefile that contains build settings for the entire project. By default, the project Makefile can be quite minimal. + +Minimal Example Makefile +^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + PROJECT_NAME := myProject + + include $(IDF_PATH)/make/project.mk + + +Mandatory Project Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin, myProject.elf. + +Optional Project Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These variables all have default values that can be overridden for custom behaviour. Look in ``make/project.mk`` for all of the implementation details. + +- ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile. Many other project variables are based on this variable. The project path cannot contain spaces. +- ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJECT_PATH)/build``. +- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `$(PROJECT_PATH)/components`, ``$(PROJECT_PATH)/main`` and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. +- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. +- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories. +- ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Note that this decreases build time, but not binary size. +- ``TEST_EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process of unit tests. + +Any paths in these Makefile variables should be absolute paths. You can convert relative paths using ``$(PROJECT_PATH)/xxx``, ``$(IDF_PATH)/xxx``, or use the Make function ``$(abspath xxx)``. + +These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile. + +Component Makefiles +------------------- + +Each project contains one or more components, which can either be part of esp-idf or added from other component directories. + +A component is any directory that contains a ``component.mk`` file. + +Searching for Components +------------------------ + +The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `component.mk` file), or they can be top-level directories whose subdirectories are components. + +Running the ``make list-components`` target dumps many of these variables and can help debug the discovery of component directories. + +Multiple components with the same name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the +idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories +contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components +with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. +If used in this way, the esp-idf directory itself can remain untouched. + +Minimal Component Makefile +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set: + +- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) will be compiled into the component library +- A sub-directory "include" will be added to the global include search path for all other components. +- The component library will be linked into the project app. + +See `example component makefiles`_ for more complete component makefile examples. + +Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process. + +.. component variables: + +Preset Component Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following component-specific variables are available for use inside ``component.mk``, but should not be modified: + +- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. +- ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory. +- ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a directory inside `$(BUILD_DIR_BASE)` where this component's source files are to be built. This is also the Current Working Directory any time the component is being built, so relative paths in make targets, etc. will be relative to this directory. +- ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory) that will be built for this component. Defaults to ``$(COMPONENT_NAME).a``. + +The following variables are set at the project level, but exported for use in the component build: + +- ``PROJECT_NAME``: Name of the project, as set in project Makefile +- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. +- ``COMPONENTS``: Name of all components that are included in this build. +- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. +- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. +- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. +- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`. +- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values. +- ``PROJECT_VER``: Project version. + + * If ``PROJECT_VER`` variable is set in project Makefile file, its value will be used. + * Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``. + * Else, if the project is located inside a Git repository, the output of git describe will be used. + * Otherwise, ``PROJECT_VER`` will be "1". + +If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug. + +Optional Project-Wide Component Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables can be set inside ``component.mk`` to control build settings across the entire project: + +- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component + directory, which will be added to the include search path for + all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile + this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead. +- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for + the app executable. Defaults to ``-l$(COMPONENT_NAME)``. If + adding pre-compiled libraries to this directory, add them as + absolute paths - ie $(COMPONENT_PATH)/libwhatever.a +- ``COMPONENT_DEPENDS``: Optional list of component names that should + be compiled before this component. This is not necessary for + link-time dependencies, because all component include directories + are available at all times. It is necessary if one component + generates an include file which you then want to include in another + component. Most components do not need to set this variable. +- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths + to files which should trigger a re-link of the ELF file if they change. + Typically used for linker script files and binary libraries. Most components do + not need to set this variable. + +The following variable only works for components that are part of esp-idf itself: + +- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths + (relative to COMPONENT_PATH) used by the component. These will be + checked (and initialised if necessary) by the build process. This + variable is ignored if the component is outside the IDF_PATH + directory. + + +Optional Component-Specific Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables can be set inside ``component.mk`` to control the build of that component: + +- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to + the component directory, which will be added to the include search + path for this component's source files only. +- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when + compiling the component's source files. These will be prefixed with + '-I' and passed as-is to the compiler. Similar to the + ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not + expanded relative to the component directory. +- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the + component directory, which will be searched for source files (``*.cpp``, + ``*.c``, ``*.S``). Defaults to '.', ie the component directory + itself. Override this to specify a different list of directories + which contain source files. +- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o + file for each source file that is found in ``COMPONENT_SRCDIRS``. + Overriding this list allows you to exclude source files in + ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See + `Specifying source files` +- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build + directory, of any files that are generated using custom make rules + in the component.mk file and which need to be removed as part of + ``make clean``. See `Source Code Generation`_ for an example. +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These + targets allow you to fully override the default build behaviour for + the component. See `Fully Overriding The Component Makefile`_ for + more details. +- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component + produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built), + and most other component variables are ignored. This flag is used for IDF + internal components which contain only ``KConfig.projbuild`` and/or + ``Makefile.projbuild`` files to configure the project, but no source files. +- ``CFLAGS``: Flags passed to the C compiler. A default set of + ``CFLAGS`` is defined based on project settings. Component-specific + additions can be made via ``CFLAGS +=``. It is also possible + (although not recommended) to override this variable completely for + a component. +- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp + and .S files). A default set of ``CPPFLAGS`` is defined based on + project settings. Component-specific additions can be made via + ``CPPFLAGS +=``. It is also possible (although not recommended) to + override this variable completely for a component. +- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of + ``CXXFLAGS`` is defined based on project + settings. Component-specific additions can be made via ``CXXFLAGS + +=``. It is also possible (although not recommended) to override + this variable completely for a component. +- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker + script generation functionality. See :doc:`Linker Script Generation `. + +To apply compilation flags to a single source file, you can add a variable override as a target, ie:: + + apps/dhcpserver.o: CFLAGS += -Wno-unused-variable + +This can be useful if there is upstream code that emits warnings. + +Component Configuration +----------------------- + +Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains +configuration settings to add to the "make menuconfig" for this component. + +These settings are found under the "Component Settings" menu when menuconfig is run. + +To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf. + +For an example, see `Adding conditional configuration`_. + +Preprocessor Definitions +------------------------ + +ESP-IDF build systems adds the following C preprocessor definitions on the command line: + +- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF. +- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details. + +Build Process Internals +----------------------- + +Top Level: Project Makefile +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- "make" is always run from the project directory and the project makefile, typically named Makefile. +- The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project variables` +- The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic. +- ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top. +- ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`. +- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top. +- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. +- By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets. +- In order to compile each component, a recursive make is performed for the component makefile. + +To better understand the project make process, have a read through the ``project.mk`` file itself. + +Second Level: Component Makefiles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper makefile. +- This component wrapper includes all component ``Makefile.componentbuild`` files, making any recipes, variables etc in these files available to every component. +- The ``component_wrapper.mk`` is called with the current directory set to the component build directory, and the ``COMPONENT_MAKEFILE`` variable is set to the absolute path to ``component.mk``. +- ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `component.mk` file which can override or modify these. +- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file. +- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration. + +To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf. + +Running Make Non-Interactively +------------------------------ + +When running ``make`` in a situation where you don't want interactive prompts (for example: inside an IDE or an automated build system) append ``BATCH_BUILD=1`` to the make arguments (or set it as an environment variable). + +Setting ``BATCH_BUILD`` implies the following: + +- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``. +- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item. +- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails. + +.. _make-size: + +Advanced Make Targets +--------------------- + +- ``make app``, ``make bootloader``, ``make partition table`` can be used to build only the app, bootloader, or partition table from the project as applicable. +- ``make erase_flash`` and ``make erase_ota`` will use esptool.py to erase the entire flash chip and the OTA selection setting from the flash chip, respectively. +- ``make size`` prints some size information about the app. ``make size-components`` and ``make size-files`` are similar targets which print more detailed per-component or per-source-file information, respectively. + + +Debugging The Make Process +-------------------------- + +Some tips for debugging the esp-idf build system: + +- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make. +- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands. +- Running ``make --trace`` (possibly in addition to one of the above arguments) will print out every target as it is built, and the dependency which caused it to be built. +- Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile. + +For more debugging tips and general make information, see the `GNU Make Manual`. + +.. _warn-undefined-variables-legacy: + +Warning On Undefined Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names. + +If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`. + +Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles. + +Overriding Parts of the Project +------------------------------- + +Makefile.projbuild +^^^^^^^^^^^^^^^^^^ + +For components that have build requirements that must be evaluated in the top-level +project make pass, you can create a file called ``Makefile.projbuild`` in the +component directory. This makefile is included when ``project.mk`` is evaluated. + +For example, if your component needs to add to CFLAGS for the entire +project (not just for its own source files) then you can set +``CFLAGS +=`` in Makefile.projbuild. + +``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". + +Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details. + +Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components! + +KConfig.projbuild +^^^^^^^^^^^^^^^^^ + +This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include +configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file. + +Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`. + + +Makefile.componentbuild +^^^^^^^^^^^^^^^^^^^^^^^ + +For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions +into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included +in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're +included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component. + +Configuration-Only Components +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some special components which contain no source files, only ``Kconfig.projbuild`` and ``Makefile.projbuild``, may set the flag ``COMPONENT_CONFIG_ONLY`` in the component.mk file. If this flag is set, most other component variables are ignored and no build step is run for the component. + +Example Component Makefiles +--------------------------- + +Because the build environment tries to set reasonable defaults that will work most +of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality. + +Here are some more advanced examples of ``component.mk`` makefiles: + + +Adding source directories +^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, sub-directories are ignored. If your project has sources in sub-directories +instead of in the root of the component then you can tell that to the build +system by setting ``COMPONENT_SRCDIRS``:: + + COMPONENT_SRCDIRS := src1 src2 + +This will compile all source files in the src1/ and src2/ sub-directories +instead. + +Specifying source files +^^^^^^^^^^^^^^^^^^^^^^^ + +The standard component.mk logic adds all .S and .c files in the source +directories as sources to be compiled unconditionally. It is possible +to circumvent that logic and hard-code the objects to be compiled by +manually setting the ``COMPONENT_OBJS`` variable to the name of the +objects that need to be generated:: + + COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o + COMPONENT_SRCDIRS := . thing anotherthing + +Note that ``COMPONENT_SRCDIRS`` must be set as well. + +Adding conditional configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The configuration system can be used to conditionally compile some files +depending on the options selected in ``make menuconfig``. For this, ESP-IDF +has the compile_only_if and compile_only_if_not macros: + +``Kconfig``:: + + config FOO_ENABLE_BAR + bool "Enable the BAR feature." + help + This enables the BAR feature of the FOO component. + +``component.mk``:: + + $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) + + +As can be seen in the example, the ``compile_only_if`` macro takes a condition and a +list of object files as parameters. If the condition is true (in this case: if the +BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will +always be compiled. The opposite goes as well: if the condition is not true, bar.o +will never be compiled. ``compile_only_if_not`` does the opposite: compile if the +condition is false, not compile if the condition is true. + +This can also be used to select or stub out an implementation, as such: + +``Kconfig``:: + + config ENABLE_LCD_OUTPUT + bool "Enable LCD output." + help + Select this if your board has a LCD. + + config ENABLE_LCD_CONSOLE + bool "Output console text to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output debugging output to the lcd + + config ENABLE_LCD_PLOT + bool "Output temperature plots to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output temperature plots + + +``component.mk``:: + + # If LCD is enabled, compile interface to it, otherwise compile dummy interface + $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o) + $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o) + + #We need font if either console or plot is enabled + $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) + +Note the use of the Make 'or' function to include the font file. Other substitution functions, +like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also +be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains +only whitespace to be false while a variable with any non-whitespace in it is true. + +(Note: Older versions of this document advised conditionally adding object file names to +``COMPONENT_OBJS``. While this still is possible, this will only work when all object +files for a component are named explicitely, and will not clean up deselected object files +in a ``make clean`` pass.) + +Source Code Generation +^^^^^^^^^^^^^^^^^^^^^^ + +Some components will have a situation where a source file isn't +supplied with the component itself but has to be generated from +another file. Say our component has a header file that consists of the +converted binary data of a BMP file, converted using a hypothetical +tool called bmp2h. The header file is then included in as C source +file called graphics_lib.c:: + + COMPONENT_EXTRA_CLEAN := logo.h + + graphics_lib.o: logo.h + + logo.h: $(COMPONENT_PATH)/logo.bmp + bmp2h -i $^ -o $@ + + +In this example, graphics_lib.o and logo.h will be generated in the +current directory (the build directory) while logo.bmp comes with the +component and resides under the component path. Because logo.h is a +generated file, it needs to be cleaned when make clean is called which +why it is added to the COMPONENT_EXTRA_CLEAN variable. + +Cosmetic Improvements +^^^^^^^^^^^^^^^^^^^^^ + +Because logo.h is a generated file, it needs to be cleaned when make +clean is called which why it is added to the COMPONENT_EXTRA_CLEAN +variable. + +Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be +generated before ``graphics_lib.c`` is compiled. + +If a a source file in another component included ``logo.h``, then this +component's name would have to be added to the other component's +``COMPONENT_DEPENDS`` list to ensure that the components were built +in-order. + +Embedding Binary Data +^^^^^^^^^^^^^^^^^^^^^ + +Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source. + +You can set a variable COMPONENT_EMBED_FILES in component.mk, giving the names of the files to embed in this way:: + + COMPONENT_EMBED_FILES := server_root_cert.der + +Or if the file is a string, you can use the variable COMPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string:: + + COMPONENT_EMBED_TXTFILES := server_root_cert.pem + +The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows:: + + extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); + extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); + +The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. + +For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time. + +Code and Data Placements +------------------------ + +ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through +linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking +app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion +of the mechanism. + +Fully Overriding The Component Makefile +--------------------------------------- + +Obviously, there are cases where all these recipes are insufficient for a +certain component, for example when the component is basically a wrapper +around another third-party component not originally intended to be +compiled under this build system. In that case, it's possible to forego +the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and +possibly COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk`` +target. The build target can do anything as long as it creates +$(COMPONENT_LIBRARY) for the project make process to link into the app binary. + +(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable +is overridden then the component can instruct the linker to link other binaries instead.) + +.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. + +.. _esp-idf-template: https://github.com/espressif/esp-idf-template +.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html + + +.. _custom-sdkconfig-defaults-legacy: + +Custom sdkconfig defaults +------------------------- + +For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch. + +To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable. + + +Save flash arguments +-------------------- + +There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. We can use command ``make print_flash_cmd``, it will print the flash arguments:: + + --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin + +Then use flash arguments as the arguemnts for esptool write_flash arguments:: + + python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin + +Building the Bootloader +======================= + +The bootloader is built by default as part of "make all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list-components" to see the components included in the bootloader build. + +The component in IDF components/bootloader is special, as the second stage bootloader is a separate .ELF and .BIN file to the main project. However it shares its configuration and build directory with the main project. + +This is accomplished by adding a subproject under components/bootloader/subproject. This subproject has its own Makefile, but it expects to be called from the project's own Makefile via some glue in the components/bootloader/Makefile.projectbuild file. See these files for more details. diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 5f936c05f..8a28a1e16 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -1,18 +1,12 @@ Build System ************ + :link_to_translation:`zh_CN:[中文]` -This document explains the Espressif IoT Development Framework build system and the -concept of "components" +This document explains the implementation of the ESP-IDF build system and the concept of "components". Read this document if you want to know how to organise and build a new ESP-IDF project or component. -Read this document if you want to know how to organise a new ESP-IDF project. +.. note:: This document describes the CMake-based build system, which is the default since ESP-IDF V4.0. ESP-IDF also supports a :doc:`legacy build system based on GNU Make `, which was the default before ESP-IDF V4.0. -We recommend using the esp-idf-template_ project as a starting point for your project. - -Using the Build System -====================== - -The esp-idf README file contains a description of how to use the build system to build your project. Overview ======== @@ -20,7 +14,7 @@ Overview An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be: -- The ESP32 base libraries (libc, rom bindings etc) +- The ESP32 base libraries (libc, ROM bindings, etc) - The WiFi drivers - A TCP/IP stack - The FreeRTOS operating system @@ -29,445 +23,544 @@ For example, for a webserver that shows the current humidity, there could be: - Main code tying it all together ESP-IDF makes these components explicit and configurable. To do that, -when a project is compiled, the build environment will look up all the +when a project is compiled, the build system will look up all the components in the ESP-IDF directories, the project directories and (optionally) in additional custom component directories. It then allows the user to configure the ESP-IDF project using a a text-based menu system to customize each component. After the components in the -project are configured, the build process will compile the project. +project are configured, the build system will compile the project. Concepts -------- -- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader. +- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader. -- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. +- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. -- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). +- An "app" is an executable which is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). -- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places. +- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places. + +- "Target" is the hardware for which an application is built. At the moment, ESP-IDF supports only one target, ``esp32``. Some things are not part of the project: - "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project. -- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration. +- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH. +Using the Build System +====================== + +.. _idf.py: + +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`) +- `esptool.py`_ for flashing ESP32. + +The :ref:`getting started guide ` 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, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``. + +Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones: + +- ``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 an ESP32. 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 ESP32. 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 ESP32 before running the serial monitor. + +.. 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. + +.. _idf.py-size: + +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 ESP32. +- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32'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. +- ``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``. + +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.). + +Using CMake Directly +-------------------- + +:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer. + +.. highlight:: bash + +When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt):: + + mkdir -p build + cd build + cmake .. -G Ninja # or 'Unix Makefiles' + ninja + +In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: running ``ninja`` actually builds the project. + +It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration. + +If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``. + +.. note:: + If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components. + +.. _flash-with-ninja-or-make: + +Flashing with ninja or make +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It's possible to build and flash directly from ninja or make by running a target like:: + + ninja flash + +Or:: + + make app-flash + +Available targets are: ``flash``, ``app-flash`` (app only), ``bootloader-flash`` (bootloader only). + +When flashing this way, optionally set the ``ESPPORT`` and ``ESPBAUD`` environment variables to specify the serial port and baud rate. You can set environment variables in your operating system or IDE project. Alternatively, set them directly on the command line:: + + ESPPORT=/dev/ttyUSB0 ninja flash + +.. note:: Providing environment variables at the start of the command like this is Bash shell Syntax. It will work on Linux and macOS. It won't work when using Windows Command Prompt, but it will work when using Bash-like shells on Windows. + +Or:: + + make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000 + +.. note:: Providing variables at the end of the command line is ``make`` syntax, and works for ``make`` on all platforms. + + +Using CMake in an IDE +--------------------- + +You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE. + +When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands. + +For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_. + +.. _setting-python-interpreter: + +Setting the Python Interpreter +------------------------------ + +Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems. + +If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command. + +If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter. + +If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter. + +To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version. + +.. _example-project-structure: Example Project ---------------- +=============== + +.. highlight:: none An example project directory tree might look like this:: - myProject/ - - Makefile + - CMakeLists.txt - sdkconfig - - components/ - component1/ - component.mk + - components/ - component1/ - CMakeLists.txt - Kconfig - src1.c - - component2/ - component.mk + - component2/ - CMakeLists.txt - Kconfig - src1.c - include/ - component2.h - main/ - src1.c - src2.c - - component.mk - build/ This example "myProject" contains the following elements: -- A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) defines - other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which - implements the rest of the ESP-IDF build system. +- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file :idf_file:`/tools/cmake/project.cmake` which + implements the rest of the build system. Finally, it sets the project name and defines the project. -- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project. +- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project. - Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF. -- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places. +- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places. See the :ref:`renaming main ` section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main". -- "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. +- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. -Component directories contain a component makefile - ``component.mk``. This may contain variable definitions -to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details. +Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions +to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details. -Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`. +Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_. -Project Makefiles ------------------ +Project CMakeLists File +======================= -Each project has a single Makefile that contains build settings for the entire project. By default, the project Makefile can be quite minimal. +Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal. -Minimal Example Makefile -^^^^^^^^^^^^^^^^^^^^^^^^ +Minimal Example CMakeLists +-------------------------- -:: +.. highlight:: cmake - PROJECT_NAME := myProject - - include $(IDF_PATH)/make/project.mk +Minimal project:: + + cmake_minimum_required(VERSION 3.5) + include($ENV{IDF_PATH}/tools/cmake/project.cmake) + project(myProject) -Mandatory Project Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _project-mandatory-parts: + +Mandatory Parts +--------------- + +The inclusion of these three lines, in the order shown above, is necessary for every project: + +- ``cmake_minimum_required(VERSION 3.5)`` tells CMake the minimum version that is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file. +- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc. +- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file. -- ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin, myProject.elf. Optional Project Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- -These variables all have default values that can be overridden for custom behaviour. Look in ``make/project.mk`` for all of the implementation details. +These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details. -- ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile. Many other project variables are based on this variable. The project path cannot contain spaces. -- ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJECT_PATH)/build``. -- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `$(PROJECT_PATH)/components`, ``$(PROJECT_PATH)/main`` and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. -- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. -- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories. -- ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Note that this decreases build time, but not binary size. -- ``TEST_EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process of unit tests. +- ``COMPONENT_DIRS``,``COMPONENTS_DIRS``: Directories to search for components. Defaults to `IDF_PATH/components`, `PROJECT_DIR/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. +- ``EXTRA_COMPONENT_DIRS``, ``EXTRA_COMPONENTS_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute. +- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via the REQUIRES or PRIV_REQUIRES arguments on component registration will automatically have it added to this list, so the ``COMPONENTS`` list can be very short. -Any paths in these Makefile variables should be absolute paths. You can convert relative paths using ``$(PROJECT_PATH)/xxx``, ``$(IDF_PATH)/xxx``, or use the Make function ``$(abspath xxx)``. +Any paths in these variables can be absolute paths, or set relative to the project directory. -These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile. +To set these variables, use the `cmake set command `_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line. -Component Makefiles -------------------- +.. _rename-main: -Each project contains one or more components, which can either be part of esp-idf or added from other component directories. +Renaming ``main`` component +---------------------------- -A component is any directory that contains a ``component.mk`` file. +The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided +that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, +saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component +causes the loss of these behind-the-scences heavy lifting, requiring the user to specify the location of the newly renamed component +and manually specifying its dependencies. Specifically, the steps to renaming ``main`` are as follows: + +1. Rename ``main`` directory. +2. Set ``EXTRA_COMPONENT_DIRS`` in the project CMakeLists.txt to include the renamed ``main`` directory. +3. Specify the dependencies in the renamed component's CMakeLists.txt file via REQUIRES or PRIV_REQUIRES arguments :ref:`on component registration`. + +.. _component-directories: + +Component CMakeLists Files +========================== + +Each project contains one or more components. Components can be part of ESP-IDF, part of the project's own components directory, or added from custom component directories (:ref:`see above `). + +A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file. Searching for Components ------------------------ -The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `component.mk` file), or they can be top-level directories whose subdirectories are components. +The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose sub-directories are components. -Running the ``make list-components`` target dumps many of these variables and can help debug the discovery of component directories. +When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components. Multiple components with the same name -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------- -When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the -idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories -contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components -with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. -If used in this way, the esp-idf directory itself can remain untouched. +When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories +contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components +with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. +If used in this way, the ESP-IDF directory itself can remain untouched. -Minimal Component Makefile -^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _cmake_minimal_component_cmakelists: -The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set: +Minimal Component CMakeLists +---------------------------- -- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) will be compiled into the component library -- A sub-directory "include" will be added to the global include search path for all other components. -- The component library will be linked into the project app. +.. highlight:: cmake -See `example component makefiles`_ for more complete component makefile examples. +The minimal component ``CMakeLists.txt`` file simply registers the component to the build system using ``idf_component_register``:: -Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process. + idf_component_register(SRCS "foo.c" "bar.c" + INCLUDE_DIRS "include") -.. component variables: +- ``SRCS`` is a list of source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``). These source files will be compiled into the component library. +- ``INCLUDE_DIRS`` is a list of directories to add to the global include search path for any component which requires this component, and also the main source files. + +A library with the name of the component will be built and linked into the final app. +Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute. + +There are other arguments that can be passed to ``idf_component_register``. These arguments +are discussed :ref:`here`. + +See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples. + +.. _component variables: Preset Component Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- -The following component-specific variables are available for use inside ``component.mk``, but should not be modified: +The following component-specific variables are available for use inside component CMakeLists, but should not be modified: -- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. -- ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory. -- ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a directory inside `$(BUILD_DIR_BASE)` where this component's source files are to be built. This is also the Current Working Directory any time the component is being built, so relative paths in make targets, etc. will be relative to this directory. -- ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory) that will be built for this component. Defaults to ``$(COMPONENT_NAME).a``. +- ``COMPONENT_DIR``: The component directory. Evaluates to the absolute path of the directory containing ``CMakeLists.txt``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable. +- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory. +- ``COMPONENT_ALIAS``: Alias of the library created internally by the build system for the component. +- ``COMPONENT_LIB``: Name of the library created internally by the build system for the component. -The following variables are set at the project level, but exported for use in the component build: +The following variables are set at the project level, but available for use in component CMakeLists: -- ``PROJECT_NAME``: Name of the project, as set in project Makefile -- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. -- ``COMPONENTS``: Name of all components that are included in this build. -- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. -- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. -- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. -- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`. -- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values. -- ``PROJECT_VER``: Project version. +- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in cmake. All names begin with ``CONFIG_``. :doc:`More information here `. +- ``ESP_PLATFORM``: Set to 1 when the CMake file is processed within ESP-IDF build system. - * If ``PROJECT_VER`` variable is set in project Makefile file, its value will be used. - * Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``. +Build/Project Variables +------------------------ + +The following are some project/build variables that are available as build properties and whose values can be queried using ``idf_build_get_property`` +from the component CMakeLists.txt: + +- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file. +- ``PROJECT_DIR``: Absolute path of the project directory containing the project CMakeLists. Same as the ``CMAKE_SOURCE_DIR`` variable. +- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list. +- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``) +- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``IDF_VERSION_*`` variables, but different ``IDF_VER`` values. +- ``IDF_TARGET``: Name of the target for which the project is being built. +- ``PROJECT_VER``: Project version. + + * If ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used. + * Else, if the ``PROJECT_DIR/version.txt`` exists, its contents will be used as ``PROJECT_VER``. * Else, if the project is located inside a Git repository, the output of git describe will be used. * Otherwise, ``PROJECT_VER`` will be "1". -If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug. +Other build properties are listed :ref:`here`. -Optional Project-Wide Component Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Controlling Component Compilation +--------------------------------- -The following variables can be set inside ``component.mk`` to control build settings across the entire project: +.. highlight:: cmake -- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component - directory, which will be added to the include search path for - all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile - this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead. -- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for - the app executable. Defaults to ``-l$(COMPONENT_NAME)``. If - adding pre-compiled libraries to this directory, add them as - absolute paths - ie $(COMPONENT_PATH)/libwhatever.a -- ``COMPONENT_DEPENDS``: Optional list of component names that should - be compiled before this component. This is not necessary for - link-time dependencies, because all component include directories - are available at all times. It is necessary if one component - generates an include file which you then want to include in another - component. Most components do not need to set this variable. -- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths - to files which should trigger a re-link of the ELF file if they change. - Typically used for linker script files and binary libraries. Most components do - not need to set this variable. +To pass compiler options when compiling source files belonging to a particular component, use the ``target_compile_options`` function:: -The following variable only works for components that are part of esp-idf itself: + target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable) -- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths - (relative to COMPONENT_PATH) used by the component. These will be - checked (and initialised if necessary) by the build process. This - variable is ignored if the component is outside the IDF_PATH - directory. +To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command:: - -Optional Component-Specific Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following variables can be set inside ``component.mk`` to control the build of that component: - -- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to - the component directory, which will be added to the include search - path for this component's source files only. -- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when - compiling the component's source files. These will be prefixed with - '-I' and passed as-is to the compiler. Similar to the - ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not - expanded relative to the component directory. -- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the - component directory, which will be searched for source files (``*.cpp``, - ``*.c``, ``*.S``). Defaults to '.', ie the component directory - itself. Override this to specify a different list of directories - which contain source files. -- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o - file for each source file that is found in ``COMPONENT_SRCDIRS``. - Overriding this list allows you to exclude source files in - ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See - `Specifying source files` -- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build - directory, of any files that are generated using custom make rules - in the component.mk file and which need to be removed as part of - ``make clean``. See `Source Code Generation`_ for an example. -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These - targets allow you to fully override the default build behaviour for - the component. See `Fully Overriding The Component Makefile`_ for - more details. -- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component - produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built), - and most other component variables are ignored. This flag is used for IDF - internal components which contain only ``KConfig.projbuild`` and/or - ``Makefile.projbuild`` files to configure the project, but no source files. -- ``CFLAGS``: Flags passed to the C compiler. A default set of - ``CFLAGS`` is defined based on project settings. Component-specific - additions can be made via ``CFLAGS +=``. It is also possible - (although not recommended) to override this variable completely for - a component. -- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp - and .S files). A default set of ``CPPFLAGS`` is defined based on - project settings. Component-specific additions can be made via - ``CPPFLAGS +=``. It is also possible (although not recommended) to - override this variable completely for a component. -- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of - ``CXXFLAGS`` is defined based on project - settings. Component-specific additions can be made via ``CXXFLAGS - +=``. It is also possible (although not recommended) to override - this variable completely for a component. -- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker - script generation functionality. See :doc:`Linker Script Generation `. - -To apply compilation flags to a single source file, you can add a variable override as a target, ie:: - - apps/dhcpserver.o: CFLAGS += -Wno-unused-variable + set_source_files_properties(mysrc.c + PROPERTIES COMPILE_FLAGS + -Wno-unused-variable + ) This can be useful if there is upstream code that emits warnings. -Component Configuration ------------------------ +When using these commands, place them after the call to ``idf_component_register`` in the component CMakeLists file. -Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains -configuration settings to add to the "make menuconfig" for this component. +.. _component-configuration: + +Component Configuration +======================= + +Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains +configuration settings to add to the configuration menu for this component. These settings are found under the "Component Settings" menu when menuconfig is run. -To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf. +To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF. For an example, see `Adding conditional configuration`_. Preprocessor Definitions +======================== + +The ESP-IDF build system adds the following C preprocessor definitions on the command line: + +- ``ESP_PLATFORM`` : Can be used to detect that build happens within ESP-IDF. +- ``IDF_VER`` : Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit. + +Component Requirements +====================== + +When compiling each component, the ESP-IDF build system recursively evaluates its components. + +Each component's source file is compiled with these include path directories, as specified in the passed arguments +to ``idf_component_register``: + +- The current component's ``INCLUDE_DIRS`` and ``PRIV_INCLUDE_DIRS``. +- The ``INCLUDE_DIRS`` set by all components in the current component's ``REQUIRES`` and ``PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies). +- All of the ``REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded). + +When writing a component ------------------------ -ESP-IDF build systems adds the following C preprocessor definitions on the command line: +- ``REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component. +- ``PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly. +- ``REQUIRES`` and/or ``PRIV_REQUIRES`` should be set before calling ``idf_component_register()``. +- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices. +- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset. -- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF. -- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details. +Components which support only some targets (values of ``IDF_TARGET``) may specify ``REQUIRED_IDF_TARGETS`` in the ``idf_component_register`` call to express these requirements. In this case the build system will generate an error if the component is included into the build, but does not support selected target. -Build Process Internals +When creating a project ----------------------- -Top Level: Project Makefile -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- By default, every component is included in the build. +- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include: -- "make" is always run from the project directory and the project makefile, typically named Makefile. -- The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project variables` -- The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic. -- ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top. -- ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`. -- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top. -- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. -- By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets. -- In order to compile each component, a recursive make is performed for the component makefile. + - Components mentioned explicitly in ``COMPONENTS``. + - Those components' requirements (evaluated recursively). + - The "common" components that every component depends on. +- Setting ``COMPONENTS`` to the minimal list of required components can significantly reduce compile times. -To better understand the project make process, have a read through the ``project.mk`` file itself. +.. _component-requirements-implementation: -Second Level: Component Makefiles -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Requirements in the build system implementation +----------------------------------------------- -- Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper makefile. -- This component wrapper includes all component ``Makefile.componentbuild`` files, making any recipes, variables etc in these files available to every component. -- The ``component_wrapper.mk`` is called with the current directory set to the component build directory, and the ``COMPONENT_MAKEFILE`` variable is set to the absolute path to ``component.mk``. -- ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `component.mk` file which can override or modify these. -- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file. -- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration. +- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory. +- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable). The ``BUILD_COMPONENTS`` variable is sorted so dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies. +- The value of ``BUILD_COMPONENTS`` is logged by CMake as "Component names: " +- Configuration is then evaluated for the components included in the build. +- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build. -To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf. +Component Dependency Order +^^^^^^^^^^^^^^^^^^^^^^^^^^ -Running Make Non-Interactively ------------------------------- +The order of components in the ``BUILD_COMPONENTS`` variable determines other orderings during the build: -When running ``make`` in a situation where you don't want interactive prompts (for example: inside an IDE or an automated build system) append ``BATCH_BUILD=1`` to the make arguments (or set it as an environment variable). +- Order that :ref:`project_include.cmake` files are included into the project. +- Order that the list of header paths is generated for compilation (via ``-I`` argument). (Note that for a given component's source files, only that component's dependency's header paths are passed to the compiler.) -Setting ``BATCH_BUILD`` implies the following: +Build Process Internals +======================= -- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``. -- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item. -- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails. +For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`_. -.. _make-size: +project.cmake contents +---------------------- -Advanced Make Targets ---------------------- +When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environment. -- ``make app``, ``make bootloader``, ``make partition table`` can be used to build only the app, bootloader, or partition table from the project as applicable. -- ``make erase_flash`` and ``make erase_ota`` will use esptool.py to erase the entire flash chip and the OTA selection setting from the flash chip, respectively. -- ``make size`` prints some size information about the app. ``make size-components`` and ``make size-files`` are similar targets which print more detailed per-component or per-source-file information, respectively. +It also defines an overridden custom version of the built-in CMake_ ``project`` function. This function is overridden to add all of the ESP-IDF specific project functionality. +project function +---------------- -Debugging The Make Process --------------------------- +The custom ``project()`` function performs the following steps: -Some tips for debugging the esp-idf build system: +- Determines the target (set by ``IDF_TARGET`` environment variable) and saves the target in CMake cache. If the target set in the environment does not match the one in cache, exits with an error. +- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above`). +- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set). +- Loads the project configuration from the ``sdkconfig`` file and generates a ``sdkconfig.cmake`` file and a ``sdkconfig.h`` header. These define configuration values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to re-generate these files and re-configure the project. +- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the correct toolchain file, depending on the target. +- Declares the actual cmake-level project by calling the `CMake project function `_. +- Loads the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_. +- Includes :ref:`project_include.cmake` files from any components which have them. +- Adds each component to the build. Each component CMakeLists file calls ``idf_component_register``, calls the CMake `add_library `_ function to add a library and then adds source files, compile options, etc. +- Adds the final app executable to the build. +- Goes back and adds inter-component dependencies between components (ie adding the public header directories of each component to each other component). -- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make. -- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands. -- Running ``make --trace`` (possibly in addition to one of the above arguments) will print out every target as it is built, and the dependency which caused it to be built. -- Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile. +Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details. -For more debugging tips and general make information, see the `GNU Make Manual`. +Debugging CMake +--------------- + +Some tips for debugging the ESP-IDF CMake-based build system: + +- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths. +- Running ``cmake -DDEBUG=1`` will produce more verbose diagnostic output from the IDF build system. +- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_. + +When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environment. + +It also defines an overridden custom version of the built-in CMake_ ``project`` function. This function is overridden to add all of the ESP-IDF specific project functionality. .. _warn-undefined-variables: Warning On Undefined Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names. +By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files. -If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`. +If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``. -Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles. +Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details. Overriding Parts of the Project ------------------------------- -Makefile.projbuild -^^^^^^^^^^^^^^^^^^ +.. _project_include.cmake: -For components that have build requirements that must be evaluated in the top-level -project make pass, you can create a file called ``Makefile.projbuild`` in the -component directory. This makefile is included when ``project.mk`` is evaluated. +project_include.cmake +^^^^^^^^^^^^^^^^^^^^^ -For example, if your component needs to add to CFLAGS for the entire -project (not just for its own source files) then you can set -``CFLAGS +=`` in Makefile.projbuild. +For components that have build requirements which must be evaluated before any component CMakeLists +files are evaluated, you can create a file called ``project_include.cmake`` in the +component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project. -``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". +``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". -Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details. +Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cmake`` file the current source directory (``CMAKE_CURRENT_SOURCE_DIR`` and working directory) is the project directory. Use the variable ``COMPONENT_DIR`` for the absolute directory of the component. -Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components! +Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details. + +``project_include.cmake`` files are included in the order given in ``BUILD_COMPONENTS`` variable (as logged by CMake). This means that a component's ``project_include.cmake`` file will be included after it's all dependencies' ``project_include.cmake`` files, unless both components are part of a dependency cycle. This is important if a ``project_include.cmake`` file relies on variables set by another component. See also :ref:`above`. + +Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components! KConfig.projbuild ^^^^^^^^^^^^^^^^^ -This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include -configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file. +This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration` KConfig files. If you want to include +configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file. -Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`. +Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for :ref:`component-configuration`. - -Makefile.componentbuild -^^^^^^^^^^^^^^^^^^^^^^^ - -For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions -into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included -in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're -included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component. +``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". Configuration-Only Components ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some special components which contain no source files, only ``Kconfig.projbuild`` and ``Makefile.projbuild``, may set the flag ``COMPONENT_CONFIG_ONLY`` in the component.mk file. If this flag is set, most other component variables are ignored and no build step is run for the component. +Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``idf_component_register()`` with no +arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths. -Example Component Makefiles ---------------------------- +Example Component CMakeLists +============================ Because the build environment tries to set reasonable defaults that will work most -of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality. +of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality. -Here are some more advanced examples of ``component.mk`` makefiles: - - -Adding source directories -^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, sub-directories are ignored. If your project has sources in sub-directories -instead of in the root of the component then you can tell that to the build -system by setting ``COMPONENT_SRCDIRS``:: - - COMPONENT_SRCDIRS := src1 src2 - -This will compile all source files in the src1/ and src2/ sub-directories -instead. - -Specifying source files -^^^^^^^^^^^^^^^^^^^^^^^ - -The standard component.mk logic adds all .S and .c files in the source -directories as sources to be compiled unconditionally. It is possible -to circumvent that logic and hard-code the objects to be compiled by -manually setting the ``COMPONENT_OBJS`` variable to the name of the -objects that need to be generated:: - - COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o - COMPONENT_SRCDIRS := . thing anotherthing - -Note that ``COMPONENT_SRCDIRS`` must be set as well. +Here are some more advanced examples of component CMakeLists files. Adding conditional configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------- The configuration system can be used to conditionally compile some files -depending on the options selected in ``make menuconfig``. For this, ESP-IDF -has the compile_only_if and compile_only_if_not macros: +depending on the options selected in the project configuration. + +.. highlight:: none ``Kconfig``:: @@ -476,17 +569,15 @@ has the compile_only_if and compile_only_if_not macros: help This enables the BAR feature of the FOO component. -``component.mk``:: +``CMakeLists.txt``:: - $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) + set(COMPONENT_SRCS "foo.c" "more_foo.c") + if(CONFIG_FOO_ENABLE_BAR) + list(APPEND COMPONENT_SRCS "bar.c") + endif() -As can be seen in the example, the ``compile_only_if`` macro takes a condition and a -list of object files as parameters. If the condition is true (in this case: if the -BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will -always be compiled. The opposite goes as well: if the condition is not true, bar.o -will never be compiled. ``compile_only_if_not`` does the opposite: compile if the -condition is false, not compile if the condition is true. +This example makes use of the CMake `if `_ function and `list APPEND `_ function. This can also be used to select or stub out an implementation, as such: @@ -509,28 +600,34 @@ This can also be used to select or stub out an implementation, as such: help Select this to output temperature plots +.. highlight:: cmake -``component.mk``:: +``CMakeLists.txt``:: - # If LCD is enabled, compile interface to it, otherwise compile dummy interface - $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o) - $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o) + if(CONFIG_ENABLE_LCD_OUTPUT) + set(COMPONENT_SRCS lcd-real.c lcd-spi.c) + else() + set(COMPONENT_SRCS lcd-dummy.c) + endif() - #We need font if either console or plot is enabled - $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) + # We need font if either console or plot is enabled + if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT) + list(APPEND COMPONENT_SRCS "font.c") + endif() -Note the use of the Make 'or' function to include the font file. Other substitution functions, -like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also -be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains -only whitespace to be false while a variable with any non-whitespace in it is true. -(Note: Older versions of this document advised conditionally adding object file names to -``COMPONENT_OBJS``. While this still is possible, this will only work when all object -files for a component are named explicitely, and will not clean up deselected object files -in a ``make clean`` pass.) +Conditions which depend on the target +------------------------------------- + +The current target is available to CMake files via ``IDF_TARGET`` variable. + +In addition to that, if target ``xyz`` is used (``IDF_TARGET=xyz``), then Kconfig variable ``CONFIG_IDF_TARGET_XYZ`` will be set. + +Note that component dependencies may depend on ``IDF_TARGET`` variable, but not on Kconfig variables. Also one can not use Kconfig variables in ``include`` statements in CMake files, but ``IDF_TARGET`` can be used in such context. + Source Code Generation -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- Some components will have a situation where a source file isn't supplied with the component itself but has to be generated from @@ -539,112 +636,678 @@ converted binary data of a BMP file, converted using a hypothetical tool called bmp2h. The header file is then included in as C source file called graphics_lib.c:: - COMPONENT_EXTRA_CLEAN := logo.h + add_custom_command(OUTPUT logo.h + COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h + DEPENDS ${COMPONENT_DIR}/logo.bmp + VERBATIM) - graphics_lib.o: logo.h + add_custom_target(logo DEPENDS logo.h) + add_dependencies(${COMPONENT_LIB} logo) - logo.h: $(COMPONENT_PATH)/logo.bmp - bmp2h -i $^ -o $@ + set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY + ADDITIONAL_MAKE_CLEAN_FILES logo.h) +This answer is adapted from the `CMake FAQ entry `_, which contains some other examples that will also work with ESP-IDF builds. -In this example, graphics_lib.o and logo.h will be generated in the +In this example, logo.h will be generated in the current directory (the build directory) while logo.bmp comes with the component and resides under the component path. Because logo.h is a -generated file, it needs to be cleaned when make clean is called which -why it is added to the COMPONENT_EXTRA_CLEAN variable. +generated file, it should be cleaned when the project is cleaned. For this reason +it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property. -Cosmetic Improvements -^^^^^^^^^^^^^^^^^^^^^ +.. note:: -Because logo.h is a generated file, it needs to be cleaned when make -clean is called which why it is added to the COMPONENT_EXTRA_CLEAN -variable. + If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use build property ``PROJECT_DIR`` instead of ``${COMPONENT_DIR}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_LIB}``.) -Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be -generated before ``graphics_lib.c`` is compiled. +If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between +the two components, to ensure that the component source files were always compiled in the correct order. -If a a source file in another component included ``logo.h``, then this -component's name would have to be added to the other component's -``COMPONENT_DEPENDS`` list to ensure that the components were built -in-order. +.. _cmake_embed_data: Embedding Binary Data -^^^^^^^^^^^^^^^^^^^^^ +--------------------- Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source. -You can set a variable COMPONENT_EMBED_FILES in component.mk, giving the names of the files to embed in this way:: +You can specify argument ``COMPONENT_EMBED_FILES`` in the component registration, giving space-delimited names of the files to embed:: - COMPONENT_EMBED_FILES := server_root_cert.der + idf_component_register(... + EMBED_FILES server_root_cert.der) -Or if the file is a string, you can use the variable COMPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string:: - COMPONENT_EMBED_TXTFILES := server_root_cert.pem +Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string:: + + idf_component_register(... + EMBED_TXTFILES server_root_cert.pem) + +.. highlight:: c The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows:: extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); -The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. +The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. + +.. highlight:: cmake + +To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this:: + + target_add_binary_data(myproject.elf "main/data.bin" TEXT) + +Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is. For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time. Code and Data Placements ------------------------ -ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through -linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking +ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through +linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion of the mechanism. -Fully Overriding The Component Makefile ---------------------------------------- +.. _component-build-full-override: + +Fully Overriding The Component Build Process +-------------------------------------------- + +.. highlight:: cmake Obviously, there are cases where all these recipes are insufficient for a certain component, for example when the component is basically a wrapper around another third-party component not originally intended to be compiled under this build system. In that case, it's possible to forego -the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and -possibly COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk`` -target. The build target can do anything as long as it creates -$(COMPONENT_LIBRARY) for the project make process to link into the app binary. +the ESP-IDF build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists:: -(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable -is overridden then the component can instruct the linker to link other binaries instead.) + # External build process for quirc, runs in source dir and + # produces libquirc.a + externalproject_add(quirc_build + PREFIX ${COMPONENT_DIR} + SOURCE_DIR ${COMPONENT_DIR}/quirc + CONFIGURE_COMMAND "" + BUILD_IN_SOURCE 1 + BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a + INSTALL_COMMAND "" + ) + + # Add libquirc.a to the build process + # + add_library(quirc STATIC IMPORTED GLOBAL) + add_dependencies(quirc quirc_build) + + set_target_properties(quirc PROPERTIES IMPORTED_LOCATION + ${COMPONENT_DIR}/quirc/libquirc.a) + set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES + ${COMPONENT_DIR}/quirc/lib) + + set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES + "${COMPONENT_DIR}/quirc/libquirc.a") + +(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.) + +- ``externalproject_add`` defines an external build system. + + - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds. + - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``. + - Consult the ExternalProject_ documentation for more details about ``externalproject_add()`` + +- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is. +- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.) .. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. -.. _esp-idf-template: https://github.com/espressif/esp-idf-template -.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html +.. _ADDITIONAL_MAKE_CLEAN_FILES_note: +ExternalProject dependencies, clean builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CMake has some unusual behaviour around external project builds: + +- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning. +- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run. +- Therefore, there are two alternative recommended ways to configure the external build command: + + 1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.) + 2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run. + +The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project. .. _custom-sdkconfig-defaults: Custom sdkconfig defaults -------------------------- +========================= -For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch. +For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file. To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable. +Target-dependent sdkconfig defaults +----------------------------------- -Save flash arguments --------------------- +In addition to ``sdkconfig.defaults`` file, build system will also load defaults from ``sdkconfig.defaults.TARGET_NAME`` file, where ``TARGET_NAME`` is the value of ``IDF_TARGET``. For example, for ``esp32`` target, default settings will be taken from ``sdkconfig.defaults`` first, and then from ``sdkconfig.defaults.esp32``. -There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. We can use command ``make print_flash_cmd``, it will print the flash arguments:: +If ``SDKCONFIG_DEFAULTS`` is used to override the name of defaults file, the name of target-specific defaults file will be derived from ``SDKCONFIG_DEFAULTS`` value. - --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin -Then use flash arguments as the arguemnts for esptool write_flash arguments:: +Flash arguments +=============== - python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin +There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. + +After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files: + +- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured). +- ``flash_app_args`` contains arguments to flash only the app. +- ``flash_bootloader_args`` contains arguments to flash only the bootloader. + +.. highlight:: bash + +You can pass any of these flasher argument files to ``esptool.py`` as follows:: + + python esptool.py --chip esp32 write_flash @build/flash_project_args + +Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line. + +The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build. Building the Bootloader ======================= -The bootloader is built by default as part of "make all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list-components" to see the components included in the bootloader build. +The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``. -The component in IDF components/bootloader is special, as the second stage bootloader is a separate .ELF and .BIN file to the main project. However it shares its configuration and build directory with the main project. +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. -This is accomplished by adding a subproject under components/bootloader/subproject. This subproject has its own Makefile, but it expects to be called from the project's own Makefile via some glue in the components/bootloader/Makefile.projectbuild file. See these files for more details. +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 the Target +==================== + +Currently ESP-IDF supports one target, ``esp32``. It is used by default by the build system. Developers working on adding multiple target support can change the target as follows:: + + rm sdkconfig + idf.py -DIDF_TARGET=new_target reconfigure + + +Writing Pure CMake Components +============================= + +The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build. + +However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake. + +.. highlight:: cmake + +Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``:: + + add_library(json STATIC + cJSON/cJSON.c + cJSON/cJSON_Utils.c) + + target_include_directories(json PUBLIC cJSON) + +- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`. +- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.) +- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands. + + +Using Third-Party CMake Projects with Components +================================================ + +CMake is used for a lot of open-source C and C++ projects — code that users can tap into for their applications. One of the benefits of having a CMake build system +is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may +not yet be provided by a component, or use another library for the same functionality. + +.. highlight:: cmake + +Importing a library might look like this for a hypothetical library ``foo`` to be used in the ``main`` component:: + + # Register the component + idf_component_register() + + # Set values of hypothetical variables that control the build of `foo` + set(FOO_BUILD_STATIC OFF) + set(FOO_BUILD_TESTS OFF) + + # Create and import the library targets + add_subdirectory(foo) + + # Link `foo` to `main` component + target_link_libraries(main foo) + +For an actual example, take a look at :example:`build_system/cmake/import_lib`. Take note that what needs to be done in order to import +the library may vary. It is recommended to read up on the library's documentation for instructions on how to +import it from other projects. Studying the library's CMakeLists.txt and build structure can also be helpful. + +It is also possible to wrap a third-party library to be used as a component in this manner. For example, the :component:`mbedtls` component is a wrapper for +Espressif's fork of `mbedtls `_. See its :component_file:`component CMakeLists.txt `. + +The CMake variable ``ESP_PLATFORM`` is set to 1 whenever the ESP-IDF build system is being used. Tests such as ``if (ESP_PLATFORM)`` can be used in generic CMake code if special IDF-specific logic is required. + + +Using ESP-IDF in Custom CMake Projects +====================================== + +ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already +have an existing CMake project or may want to create a custom one. In these cases it is desirable to be able to consume IDF components +as libraries to be linked to the user's targets (libraries/ executables). + +It is possible to do so by using the :ref:`build system APIs provided` by :idf_file:`tools/cmake/idf.cmake`. For example: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.5) + project(my_custom_app C) + + # Include CMake file that provides ESP-IDF CMake build system APIs. + include($ENV{IDF_PATH}/tools/cmake/idf.cmake) + + # Include ESP-IDF components in the build, may be thought as an equivalent of + # add_subdirectory() but with some additional procesing and magic for ESP-IDF build + # specific build processes. + idf_build_process(esp32) + + # Create the project executable and plainly link the newlib component to it using + # its alias, idf::newlib. + add_executable(${CMAKE_PROJECT_NAME}.elf main.c) + target_link_libraries(${CMAKE_PROJECT_NAME}.elf idf::newlib) + + # Let the build system know what the project executable is to attach more targets, dependencies, etc. + idf_build_executable(${CMAKE_PROJECT_NAME}.elf) + +The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creation of an application equivalent to :example:`hello world application ` +using a custom CMake project. + +.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. +.. _cmake_buildsystem_api: + +ESP-IDF CMake Build System API +============================== + +idf-build-commands +------------------ + +.. code-block:: none + + idf_build_get_property(var property [GENERATOR_EXPRESSION]) + +Retrieve a :ref:`build property` *property* and store it in *var* accessible from the current scope. Specifying +*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which +can be used with CMake commands that support generator expressions. + +.. code-block:: none + + idf_build_set_property(property val [APPEND]) + +Set a :ref:`build property` *property* with value *val*. Specifying *APPEND* will append the specified value to the current +value of the property. If the property does not previously exist or it is currently empty, the specified value becomes +the first element/member instead. + +.. code-block:: none + + idf_build_component(component_dir) + +Present a directory *component_dir* that contains a component to the build system. Relative paths are converted to absolute paths with respect to current directory. +All calls to this command must be performed before `idf_build_process`. + +This command does not guarantee that the component will be processed during build (see the `COMPONENTS` argument description for `idf_build_process`) + +.. code-block:: none + + idf_build_process(target + [PROJECT_DIR project_dir] + [PROJECT_VER project_ver] + [PROJECT_NAME project_name] + [SDKCONFIG sdkconfig] + [SDKCONFIG_DEFAULTS sdkconfig_defaults] + [BUILD_DIR build_dir] + [COMPONENTS component1 component2 ...]) + +Performs the bulk of the behind-the-scenes magic for including ESP-IDF components such as component configuration, libraries creation, +dependency expansion and resolution. Among these functions, perhaps the most important +from a user's perspective is the libraries creation by calling each component's ``idf_component_register``. This command creates the libraries for each component, which are accessible using aliases in the form +idf::*component_name*. These aliases can be used to link the components to the user's own targets, either libraries +or executables. + +The call requires the target chip to be specified with *target* argument. Optional arguments for the call include: + +- PROJECT_DIR - directory of the project; defaults to CMAKE_SOURCE_DIR +- PROJECT_NAME - name of the project; defaults to CMAKE_PROJECT_NAME +- PROJECT_VER - version/revision of the project; defaults to "0.0.0" +- SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set +- SDKCONFIG_DEFAULTS - defaults file to use for the build; defaults to empty +- BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, components; defaults to CMAKE_BINARY_DIR +- COMPONENTS - select components to process among the components known by the build system (added via `idf_build_component`). This argument is used to trim the build. + Other components are automatically added if they are required in the dependency chain, i.e. + the public and private requirements of the components in this list are automatically added, and in turn the public and private requirements of those requirements, + so on and so forth. If not specified, all components known to the build system are processed. + +.. code-block:: none + + idf_build_executable(executable) + +Specify the executable *executable* for ESP-IDF build. This attaches additional targets such as dependencies related to +flashing, generating additional binary files, etc. Should be called after ``idf_build_process``. + +.. code-block:: none + + idf_build_get_config(var config [GENERATOR_EXPRESSION]) + +Get the value of the specified config. Much like build properties, specifying +*GENERATOR_EXPRESSION* will retrieve the generator expression string for that config, instead of the actual value, which +can be used with CMake commands that support generator expressions. Actual config values are only known after call to `idf_build_process`, however. + +.. _cmake-build-properties: + +idf-build-properties +-------------------- + +These are properties that describe the build. Values of build properties can be retrieved by using the build command ``idf_build_get_property``. +For example, to get the Python interpreter used for the build: + +.. code-block: cmake + + idf_build_get_property(python PYTHON) + message(STATUS "The Python intepreter is: ${python}") + + - BUILD_DIR - build directory; set from ``idf_build_process`` BUILD_DIR argument + - BUILD_COMPONENTS - list of components (more specifically, component aliases) included in the build; set by ``idf_build_process`` + - C_COMPILE_OPTIONS - compile options applied to all components' C source files + - COMPILE_OPTIONS - compile options applied to all components' source files, regardless of it being C or C++ + - COMPILE_DEFINITIONS - compile definitions applied to all component source files + - CXX_COMPILE_OPTIONS - compile options applied to all components' C++ source files + - EXECUTABLE - project executable; set by call to ``idf_build_executable`` + - EXECUTABLE_NAME - name of project executable without extension; set by call to ``idf_build_executable`` + - IDF_PATH - ESP-IDF path; set from IDF_PATH environment variable, if not, inferred from the location of ``idf.cmake`` + - IDF_TARGET - target chip for the build; set from the required target argument for ``idf_build_process`` + - IDF_VER - ESP-IDF version; set from either a version file or the Git revision of the IDF_PATH repository + - INCLUDE_DIRECTORIES - include directories for all component source files + - KCONFIGS - list of Kconfig files found in components in build; set by ``idf_build_process`` + - KCONFIG_PROJBUILDS - list of Kconfig.projbuild diles found in components in build; set by ``idf_build_process`` + - PROJECT_NAME - name of the project; set from ``idf_build_process`` PROJECT_NAME argument + - PROJECT_DIR - directory of the project; set from ``idf_build_process`` PROJECT_DIR argument + - PROJECT_VER - version of the project; set from ``idf_build_process`` PROJECT_VER argument + - PYTHON - Python interpreter used for the build; set from PYTHON environment variable if available, if not "python" is used + - SDKCONFIG - full path to output config file; set from ``idf_build_process`` SDKCONFIG argument + - SDKCONFIG_DEFAULTS - full path to config defaults file; set from ``idf_build_process`` SDKCONFIG_DEFAULTS argument + - SDKCONFIG_HEADER - full path to C/C++ header file containing component configuration; set by ``idf_build_process`` + - SDKCONFIG_CMAKE - full path to CMake file containing component configuration; set by ``idf_build_process`` + - SDKCONFIG_JSON - full path to JSON file containing component configuration; set by ``idf_build_process`` + - SDKCONFIG_JSON_MENUS - full path to JSON file containing config menus; set by ``idf_build_process`` + +idf-component-commands +---------------------- + +.. code-block:: none + + idf_component_get_property(var component property [GENERATOR_EXPRESSION]) + +Retrieve a specified *component*'s :ref:`component property`, *property* and store it in *var* accessible from the current scope. Specifying +*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which +can be used with CMake commands that support generator expressions. + +.. code-block:: none + + idf_component_set_property(property val [APPEND]) + +Set a specified *component*'s :ref:`component property`, *property* with value *val*. Specifying *APPEND* will append the specified value to the current +value of the property. If the property does not previously exist or it is currently empty, the specified value becomes +the first element/member instead. + +.. _cmake-component-register: + +.. code-block:: none + + idf_component_register([[SRCS src1 src2 ...] | [[SRC_DIRS dir1 dir2 ...] [EXCLUDE_SRCS src1 src2 ...]] + [INCLUDE_DIRS dir1 dir2 ...] + [PRIV_INCLUDE_DIRS dir1 dir2 ...] + [REQUIRES component1 component2 ...] + [PRIV_REQUIRES component1 component2 ...] + [LDFRAGMENTS ldfragment1 ldfragment2 ...] + [REQUIRED_IDF_TARGETS target1 target2 ...] + [EMBED_FILES file1 file2 ...] + [EMBED_TXTFILES file1 file2 ...]) + +Register a component to the build system. Much like the ``project()`` CMake command, this should be called from the component's +CMakeLists.txt directly (not through a function or macro) and is recommended to be called before any other command. Here are some +guidelines on what commands can **not** be called before ``idf_component_register``: + + - commands that are not valid in CMake script mode + - custom commands defined in project_include.cmake + - build system API commands except ``idf_build_get_property``; although consider whether the property may not have been set yet + +Commands that set and operate on variables are generally okay to call before ``idf_component_register``. + +The arguments for ``idf_component_register`` include: + + - SRCS - component source files used for creating a static library for the component; if not specified, component is a treated as a + config-only component and an interface library is created instead. + - SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of specifying source files manually via SRCS. Note that this is subject to the :ref:`limitations of globbing in CMake`. Source files specified in EXCLUDE_SRCS are removed from the globbed files. + - INCLUDE_DIRS - paths, relative to the component directory, which will be added to the include search path for all other components which require the current component + - PRIV_INCLUDE_DIRS - directory paths, must be relative to the component directory, which will be added to the include search path for this component's source files only + - REQUIRES - public component requirements for the component + - PRIV_REQUIRES - private component requirements for the component; ignored on config-only components + - LDFRAGMENTS - component linker fragment files + - REQUIRED_IDF_TARGETS - specify the only target the component supports + +The following are used for :ref:`embedding data into the component`, and is considered as source files +when determining if a component is config-only. This means that even if the component does not specify source files, a static library is still +created internally for the component if it specifies either: + + - EMBED_FILES - binary files to be embedded in the component + - EMBED_TXTFILES - text files to be embedded in the component + +.. _cmake-component-properties: + +idf-component-properties +------------------------ + +These are properties that describe a component. Values of component properties can be retrieved by using the build command ``idf_component_get_property``. +For example, to get the directory of the ``freertos`` component: + +.. code-block: cmake + + idf_component_get_property(dir freertos COMPONENT_DIR) + message(STATUS "The 'freertos' component directory is: ${dir}") + +- COMPONENT_ALIAS - alias for COMPONENT_LIB used for linking the component to external targets; set by ``idf_build_component`` and alias library itself + is created by ``idf_component_register`` +- COMPONENT_DIR - component directory; set by ``idf_build_component`` +- COMPONENT_LIB - name for created component static/interface library; set by ``idf_build_component`` and library itself + is created by ``idf_component_register`` +- COMPONENT_NAME - name of the component; set by ``idf_build_component`` based on the component directory name +- COMPONENT_TYPE - type of the component, whether LIBRARY or CONFIG_ONLY. A component is of type LIBRARY if it specifies + source files or embeds a file +- EMBED_FILES - list of files to embed in component; set from ``idf_component_register`` EMBED_FILES argument +- EMBED_TXTFILES - list of text files to embed in component; set from ``idf_component_register`` EMBED_TXTFILES argument +- INCLUDE_DIRS - list of component include directories; set from ``idf_component_register`` INCLUDE_DIRS argument +- KCONFIG - component Kconfig file; set by ``idf_build_component`` +- KCONFIG_PROJBUILD - component Kconfig.projbuild; set by ``idf_build_component`` +- LDFRAGMENTS - list of component linker fragment files; set from ``idf_component_register`` LDFRAGMENTS argument +- PRIV_INCLUDE_DIRS - list of component private include directories; set from ``idf_component_register`` PRIV_INCLUDE_DIRS on components of type LIBRARY +- PRIV_REQUIRES - list of private component dependentices; set from ``idf_component_register`` PRIV_REQUIRES argument +- REQUIRED_IDF_TARGETS - list of targets the component supports; set from ``idf_component_register`` EMBED_TXTFILES argument +- REQUIRES - list of public component dependencies; set from ``idf_component_register`` REQUIRES argument +- SRCS - list of component source files; set from SRCS or SRC_DIRS/EXCLUDE_SRCS argument of ``idf_component_register`` + +.. _cmake-file-globbing: + +File Globbing & Incremental Builds +================================== + +.. highlight:: cmake + +The preferred way to include source files in an ESP-IDF component is to list them manually via SRCS argument to ``idf_component_register``:: + + idf_component_register(SRCS library/a.c library/b.c platform/platform.c + ...) + +This preference reflects the `CMake best practice `_ of manually listing source files. This could, however, be inconvenient when there are lots of source files to add to the build. The ESP-IDF build system provides an alternative way for specifying source files using ``SRC_DIRS``:: + + idf_component_register(SRC_DIRS library platform + ...) + +This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new source file is added and this method is used, then CMake won't know to automatically re-run and this file won't be added to the build. + +The trade-off is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git... + +For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun. + +For project components (not part of ESP-IDF), there are a few different options: + +- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes. +- If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to automatically trigger re-runs of CMake when the Git revision changes. +- If not using Git, remember to manually run ``idf.py reconfigure`` whenever a source file may change. +- To avoid this problem entirely, use ``COMPONENT_SRCS`` to list all source files in project components. + +The best option will depend on your particular project and its users. + +Build System Metadata +===================== + +For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command). + +- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it. +- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc. +- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_. +- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc. +- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values. +- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs. + +JSON Configuration Server +------------------------- + +.. highlight :: json + +A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout. + +You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator. + +The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``:: + + {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } } + +Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.) + +The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline:: + + {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } } + +The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes:: + + {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}} + +Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value. + +If the range of a config item changes, due to conditional range depending on another value, then this is also sent:: + + {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } } + +If invalid data is passed, an "error" field is present on the object:: + + {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]} + +By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent:: + + {"version": 1, "save": null } + +To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent:: + + {"version": 1, "load": null } + +The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname. + +The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started. + +Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command. + +.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited. + +.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run. + +.. _gnu-make-to-cmake: + +Migrating from ESP-IDF GNU Make System +====================================== + +Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax. + +Automatic Conversion Tool +------------------------- + +.. highlight:: bash + +An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this:: + + $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir + +The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH. + +The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files. + +It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables. + +The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand. + +No Longer Available in CMake +---------------------------- + +Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system: + +- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead. +- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component. +- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here `_. +- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually. +- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead. +- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``. +- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repository. +- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute). +- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``. +- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead. +- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality `. +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details. +- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_. +- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_. + + +No Default Values +----------------- + +The following variables no longer have default values: + +- ``COMPONENT_SRCDIRS`` +- ``COMPONENT_ADD_INCLUDEDIRS`` + +No Longer Necessary +------------------- + +It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCS`` is ignored if ``COMPONENT_SRCDIRS`` is set). + +Flashing from make +------------------ + +``make flash`` and similar targets still work to build and flash. However, project ``sdkconfig`` no longer specifies serial port and baud rate. Environment variables can be used to override these. See :ref:`flash-with-ninja-or-make` for more details. + +.. _esp-idf-template: https://github.com/espressif/esp-idf-template +.. _cmake: https://cmake.org +.. _ninja: https://ninja-build.org +.. _esptool.py: https://github.com/espressif/esptool/#readme +.. _CMake v3.5 documentation: https://cmake.org/cmake/help/v3.5/index.html +.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options +.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/add_library.html +.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html +.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html +.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html +.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html +.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html +.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F +.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html +.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html +.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages +.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html +.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html +.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries +.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html +.. _quirc: https://github.com/dlbeer/quirc +.. _pyenv: https://github.com/pyenv/pyenv#README +.. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/en/api-guides/console.rst b/docs/en/api-guides/console.rst index 5119d3ae2..3f10279db 100644 --- a/docs/en/api-guides/console.rst +++ b/docs/en/api-guides/console.rst @@ -16,7 +16,7 @@ Line editing Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key. -.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``make monitor`` from project directory). +.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory). Here is an overview of functions provided by `linenoise`_ library. diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 536d999ef..c590efeea 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -16,7 +16,7 @@ ESP-IDF provides special script `espcoredump.py` to help users to retrieve and a Configuration ------------- -There are a number of core dump related configuration options which user can choose in configuration menu of the application (`make menuconfig`). +There are a number of core dump related configuration options which user can choose in project configuration menu (`idf.py menuconfig`). 1. Core dump data destination (`Components -> ESP32-specific config -> Core dump -> Data destination`): @@ -93,7 +93,7 @@ Generic command syntax: * --gdb,-g GDB. Path to gdb to use for data retrieval. * --core,-c CORE. Path to core dump file to use (if skipped core dump will be read from flash). * --core-format,-t CORE_FORMAT. Specifies that file passed with "-c" is an ELF ("elf"), dumped raw binary ("raw") or base64-encoded ("b64") format. - * --off,-o OFF. Offset of coredump partition in flash (type `make partition_table` to see it). + * --off,-o OFF. Offset of coredump partition in flash (type `idf.py partition_table` to see it). * --save-core,-s SAVE_CORE. Save core to file. Othwerwise temporary core file will be deleted. Ignored with "-c". * --rom-elf,-r ROM_ELF. Path to ROM ELF file to use (if skipped "esp32_rom.elf" is used). * --print-mem,-m Print memory dump. Used only with "info_corefile". diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index ac3a49ec8..558f43ecd 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -74,8 +74,9 @@ used to free memory pointed to by TLSP. Call Callbacks. :ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be -configured using ``make meunconfig`` such as running ESP-IDF in Unicore Mode, -or configuring the number of Thread Local Storage Pointers each task will have. +set in the project configuration (``idf.py menuconfig``) such as running ESP-IDF in +Unicore (single core) Mode, or configuring the number of Thread Local Storage Pointers +each task will have. .. _backported-features: @@ -478,10 +479,10 @@ For more details see :doc:`FreeRTOS API reference<../api-reference/system/freert Configuring ESP-IDF FreeRTOS ---------------------------- -The ESP-IDF FreeRTOS can be configured using ``make menuconfig`` under -``Component_Config/FreeRTOS``. The following section highlights some of the -ESP-IDF FreeRTOS configuration options. For a full list of ESP-IDF -FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` +The ESP-IDF FreeRTOS can be configured in the project configuration menu +(``idf.py menuconfig``) under ``Component Config/FreeRTOS``. The following section +highlights some of the ESP-IDF FreeRTOS configuration options. For a full list of +ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only on **PRO_CPU**. Note that this is **not equivalent to running vanilla diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 17ab34fed..869f7c5d1 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -7,7 +7,7 @@ API Guides General Notes Build System - Build System (CMake) + Build System (Legacy GNU Make) Error Handling Fatal Errors Event Handling @@ -22,9 +22,9 @@ API Guides Partition Tables Secure Boot <../security/secure-boot> ULP Coprocessor - ULP Coprocessor (CMake) + ULP Coprocessor (Legacy GNU Make) Unit Testing - Unit Testing (CMake) + Unit Testing (Legacy GNU Make) Application Level Tracing Console Component ROM debug console diff --git a/docs/en/api-guides/jtag-debugging/configure-wrover.rst b/docs/en/api-guides/jtag-debugging/configure-wrover.rst index 0f1ca1f88..a851b9efa 100644 --- a/docs/en/api-guides/jtag-debugging/configure-wrover.rst +++ b/docs/en/api-guides/jtag-debugging/configure-wrover.rst @@ -8,7 +8,7 @@ All versions of ESP-WROVER-KIT boards have built-in JTAG functionality. Putting Configure Hardware ^^^^^^^^^^^^^^^^^^ -1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options-cmake`. +1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`. 2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation: diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index b65319928..c7be7711f 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -62,7 +62,7 @@ Debugging using JTAG and application loading / monitoring is integrated under th If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection. -Depending on user preferences, both `debugger` and `make` can be operated directly from terminal / command line, instead from Eclipse. +Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal / command line, instead from Eclipse. .. _jtag-debugging-selecting-jtag-adapter: @@ -197,7 +197,7 @@ You should now see similar output (this log is for ESP-WROVER-KIT):: Upload application for debugging ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Build and upload your application to ESP32 as usual, see :ref:`get-started-build-and-flash`. +Build and upload your application to ESP32 as usual, see :ref:`get-started-build`. Another option is to write application image to flash using OpenOCD via JTAG with commands like this:: diff --git a/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst b/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst index fc77d702d..67eca902a 100644 --- a/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst +++ b/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst @@ -6,7 +6,7 @@ Set up OpenOCD for Windows IDF Tools Installer =================== -If you are using CMake build system and followed the :doc:`/get-started-cmake/windows-setup` with the ``ESP-IDF Tools Installer`` V1.2 or newer, then by default you will already have ``openocd`` installed. +If you are using CMake build system and followed the :doc:`/get-started/windows-setup` with the ``ESP-IDF Tools Installer`` V1.2 or newer, then by default you will already have ``openocd`` installed. ``ESP-IDF Tools Installer`` adds ``openocd`` to the ``PATH`` so that it can be run from any directory. diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index 3911191d7..d3a76940c 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -58,7 +58,7 @@ ESP-IDF has some support options for OpenOCD debugging which can be set at compi * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger. * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details. -Please see the :ref:`make menuconfig ` menu for more details on setting compile-time options. +Please see the :ref:`project configuration menu ` menu for more details on setting compile-time options. .. _jtag-debugging-tip-freertos-support: diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index ecf236792..91fe17e0e 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -11,12 +11,12 @@ Partition table length is 0xC00 bytes (maximum 95 partition table entries). An M Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded. -The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables: +The simplest way to use the partition table is to open the project configuration menu (``idf.py menuconfig``) and choose one of the simple predefined partition tables under :ref:`CONFIG_PARTITION_TABLE_TYPE`: * "Single factory app, no OTA" * "Factory app, two OTA definitions" -In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table. +In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition_table` then it will print a summary of the partition table. Built-in Partition Tables ------------------------- @@ -100,7 +100,7 @@ The 8-bit subtype field is specific to a given partition type. esp-idf currently - phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware. - In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space. - - To load PHY data from this partition, run ``make menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. + - To load PHY data from this partition, open the project configuration menu (``idf.py menuconfig``) and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically. - nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`. - NVS is used to store per-device PHY calibration data (different to initialisation data). @@ -138,7 +138,7 @@ Generating Binary Partition Table The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats. -If you configure the partition table CSV name in ``make menuconfig`` and then ``make partition_table``, this conversion is done as part of the build process. +If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process. To convert CSV to Binary manually:: @@ -148,7 +148,7 @@ To convert binary format back to CSV manually:: python gen_esp32part.py binary_partitions.bin input_partitions.csv -To display the contents of a binary partition table on stdout (this is how the summaries displayed when running `make partition_table` are generated:: +To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition_table`` are generated:: python gen_esp32part.py binary_partitions.bin @@ -162,12 +162,12 @@ The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option o Flashing the partition table ---------------------------- -* ``make partition_table-flash``: will flash the partition table with esptool.py. -* ``make flash``: Will flash everything including the partition table. +* ``idf.py partition_table-flash``: will flash the partition table with esptool.py. +* ``idf.py flash``: Will flash everything including the partition table. -A manual flashing command is also printed as part of ``make partition_table``. +A manual flashing command is also printed as part of ``idf.py partition_table`` output. -Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``make erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents. +Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents. Partition Tool (parttool.py) ---------------------------- diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index 88e89d8f2..c7da5f1e0 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -6,11 +6,9 @@ IDF Monitor The IDF monitor tool is mainly a serial terminal program which relays serial data to and from the target device's serial port. It also provides some IDF-specific features. -This tool can be launched by invoking in IDF the following target: - -- **For make**: ``make monitor`` -- **For cmake**: ``idf.py monitor`` +This tool can be launched from an IDF project by running ``idf.py monitor``. +(For the legacy GNU Make system, run ``make monitor``.) Keyboard Shortcuts ================== @@ -32,7 +30,7 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | - Ctrl+R | Reset target board via RTS | Resets the target board and re-starts the application via the RTS line (if connected). | +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the ``make flash`` (``idf.py flash``) target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. | +| - Ctrl+F | Build and flash the project | Pauses idf_monitor to run the project ``flash`` target, then resumes idf_monitor. Any changed source files are recompiled and then re-flashed. | +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | - Ctrl+A (or A) | Build and flash the app only | Pauses idf_monitor to run the ``app-flash`` target, then resumes idf_monitor. Similar to the ``flash`` target, but only the main app is built and re-flashed. | +-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -103,7 +101,7 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware. -To enable GDBStub, run ``make menuconfig`` (for make) or ``idf.py menuconfig`` (for cmake) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. +To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button. @@ -115,7 +113,7 @@ In the background, IDF Monitor runs the following command:: Output Filtering ~~~~~~~~~~~~~~~~ -IDF monitor can be invoked as ``make monitor PRINT_FILTER=""`` (for make) or ``idf.py monitor --print-filter=""`` (for cmake), where ``PRINT_FILTER`` is the parameter for output filtering. The default value is an empty string, which means that everything is printed. +IDF monitor can be invoked as ``idf.py monitor --print-filter="xyz"``, where ``--print-filter`` is the parameter for output filtering. The default value is an empty string, which means that everything is printed. Restrictions on what to print can be specified as a series of ``:`` items where ```` is the tag string and ```` is a character from the set ``{N, E, W, I, D, V, *}`` referring to a level for :doc:`logging <../../api-reference/system/log>`. @@ -188,18 +186,6 @@ The captured output for the filtering options ``PRINT_FILTER="wifi esp_image:E l D (309) light_driver: [light_init, 74]:status: 1, mode: 2 -Simple Monitor -============== - -The earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program. - -.. note:: This target only works in a build system based on GNU Make and cannot work in a CMake-based system. - -This program can still be run with the command ``make simple_monitor``. - -IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts. - - Known Issues with IDF Monitor ============================= diff --git a/docs/en/api-guides/ulp-cmake.rst b/docs/en/api-guides/ulp-legacy.rst similarity index 79% rename from docs/en/api-guides/ulp-cmake.rst rename to docs/en/api-guides/ulp-legacy.rst index 0391ab73d..658ee49e4 100644 --- a/docs/en/api-guides/ulp-cmake.rst +++ b/docs/en/api-guides/ulp-legacy.rst @@ -1,7 +1,5 @@ -ULP coprocessor programming (CMake) -=================================== - -:link_to_translation:`zh_CN:[中文]` +ULP coprocessor (Legacy GNU Make) +================================= .. toctree:: :maxdepth: 1 @@ -9,6 +7,7 @@ ULP coprocessor programming (CMake) Instruction set reference Programming using macros (legacy) +.. include:: ../gnu-make-legacy.rst ULP (Ultra Low Power) coprocessor is a simple FSM which is designed to perform measurements using ADC, temperature sensor, and external I2C sensors, while main processors are in deep sleep mode. ULP coprocessor can access RTC_SLOW_MEM memory region, and registers in RTC_CNTL, RTC_IO, and SARADC peripherals. ULP coprocessor uses fixed-width 32-bit instructions, 32-bit memory addressing, and has 4 general purpose 16-bit registers. @@ -27,35 +26,39 @@ Compiling ULP code To compile ULP code as part of a component, the following steps must be taken: -1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. +1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. -.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. +.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. -2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: +2. Modify the component makefile, adding the following:: - ... - register_component() + ULP_APP_NAME ?= ulp_$(COMPONENT_NAME) + ULP_S_SOURCES = $(COMPONENT_PATH)/ulp/ulp_source_file.S + ULP_EXP_DEP_OBJECTS := main.o + include $(IDF_PATH)/components/ulp/component_ulp_common.mk + + Here is each line explained: - set(ulp_app_name ulp_${COMPONENT_NAME}) - set(ulp_s_sources ulp/ulp_assembly_source_file.S) - set(ulp_exp_dep_srcs "ulp_c_source_file.c") + ULP_APP_NAME + Name of the generated ULP application, without an extension. This name is used for build products of the ULP application: ELF file, map file, binary file, generated header file, and generated linker export file. - ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs}) + ULP_S_SOURCES + List of assembly files to be passed to the ULP assembler. These must be absolute paths, i.e. start with ``$(COMPONENT_PATH)``. Consider using ``$(addprefix)`` function if more than one file needs to be listed. Paths are relative to component build directory, so prefixing them is not necessary. - The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used other generated artifacts - such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. - Finally, the third argument specifies the list of component source files which include the header file to be generated. - This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. - See section below explaining the concept of generated header files for ULP applications. + ULP_EXP_DEP_OBJECTS + List of object files names within the component which include the generated header file. This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. See section below explaining the concept of generated header files for ULP applications. -3. Build the application as usual (e.g. `idf.py app`) + include $(IDF_PATH)/components/ulp/component_ulp_common.mk + Includes common definitions of ULP build steps. Defines build targets for ULP object files, ELF file, binary file, etc. +3. Build the application as usual (e.g. ``idf.py build`` or ``idf.py app``) + Inside, the build system will take the following steps to build ULP program: - 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d). + 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.pS) in the component build directory. This step also generates dependency files (foo.ulp.d). 2. **Run preprocessed assembly sources through assembler.** This produces objects (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of build process. - + 3. **Run linker script template through C preprocessor.** The template is located in components/ulp/ld directory. 4. **Link object files into an output ELF file** (ulp_app_name.elf). Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes. @@ -71,7 +74,7 @@ To compile ULP code as part of a component, the following steps must be taken: Accessing ULP program variables ------------------------------- -Global symbols defined in the ULP program may be used inside the main program. +Global symbols defined in the ULP program may be used inside the main program. For example, ULP program may define a variable ``measurement_count`` which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep:: @@ -82,10 +85,10 @@ For example, ULP program may define a variable ``measurement_count`` which will move r3, measurement_count ld r3, r3, 0 -Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. +Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``$(ULP_APP_NAME).h`` and ``$(ULP_APP_NAME).ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. The header file contains declaration of the symbol:: - + extern uint32_t ulp_measurement_count; Note that all symbols (variables, arrays, functions) are declared as ``uint32_t``. For functions and arrays, take address of the symbol and cast to the appropriate type. @@ -136,7 +139,7 @@ Once the program is loaded into RTC memory, application can start it, passing th .. doxygenfunction:: ulp_run -Declaration of the entry point symbol comes from the above mentioned generated header file, ``${ULP_APP_NAME}.h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: +Declaration of the entry point symbol comes from the above mentioned generated header file, ``$(ULP_APP_NAME).h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: .global entry diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index e59c3cc75..df3b813c7 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -1,5 +1,7 @@ ULP coprocessor programming -=========================== +=================================== + +:link_to_translation:`zh_CN:[中文]` .. toctree:: :maxdepth: 1 @@ -25,39 +27,35 @@ Compiling ULP code To compile ULP code as part of a component, the following steps must be taken: -1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. +1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. -.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. +.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. -2. Modify the component makefile, adding the following:: +2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: - ULP_APP_NAME ?= ulp_$(COMPONENT_NAME) - ULP_S_SOURCES = $(COMPONENT_PATH)/ulp/ulp_source_file.S - ULP_EXP_DEP_OBJECTS := main.o - include $(IDF_PATH)/components/ulp/component_ulp_common.mk - - Here is each line explained: + ... + register_component() - ULP_APP_NAME - Name of the generated ULP application, without an extension. This name is used for build products of the ULP application: ELF file, map file, binary file, generated header file, and generated linker export file. + set(ulp_app_name ulp_${COMPONENT_NAME}) + set(ulp_s_sources ulp/ulp_assembly_source_file.S) + set(ulp_exp_dep_srcs "ulp_c_source_file.c") - ULP_S_SOURCES - List of assembly files to be passed to the ULP assembler. These must be absolute paths, i.e. start with ``$(COMPONENT_PATH)``. Consider using ``$(addprefix)`` function if more than one file needs to be listed. Paths are relative to component build directory, so prefixing them is not necessary. + ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs}) - ULP_EXP_DEP_OBJECTS - List of object files names within the component which include the generated header file. This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. See section below explaining the concept of generated header files for ULP applications. + The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used other generated artifacts + such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. + Finally, the third argument specifies the list of component source files which include the header file to be generated. + This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. + See section below explaining the concept of generated header files for ULP applications. - include $(IDF_PATH)/components/ulp/component_ulp_common.mk - Includes common definitions of ULP build steps. Defines build targets for ULP object files, ELF file, binary file, etc. +3. Build the application as usual (e.g. `idf.py app`) -3. Build the application as usual (e.g. `make app`) - Inside, the build system will take the following steps to build ULP program: - 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.pS) in the component build directory. This step also generates dependency files (foo.ulp.d). + 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d). 2. **Run preprocessed assembly sources through assembler.** This produces objects (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of build process. - + 3. **Run linker script template through C preprocessor.** The template is located in components/ulp/ld directory. 4. **Link object files into an output ELF file** (ulp_app_name.elf). Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes. @@ -73,7 +71,7 @@ To compile ULP code as part of a component, the following steps must be taken: Accessing ULP program variables ------------------------------- -Global symbols defined in the ULP program may be used inside the main program. +Global symbols defined in the ULP program may be used inside the main program. For example, ULP program may define a variable ``measurement_count`` which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep:: @@ -84,10 +82,10 @@ For example, ULP program may define a variable ``measurement_count`` which will move r3, measurement_count ld r3, r3, 0 -Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``$(ULP_APP_NAME).h`` and ``$(ULP_APP_NAME).ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. +Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. The header file contains declaration of the symbol:: - + extern uint32_t ulp_measurement_count; Note that all symbols (variables, arrays, functions) are declared as ``uint32_t``. For functions and arrays, take address of the symbol and cast to the appropriate type. @@ -138,7 +136,7 @@ Once the program is loaded into RTC memory, application can start it, passing th .. doxygenfunction:: ulp_run -Declaration of the entry point symbol comes from the above mentioned generated header file, ``$(ULP_APP_NAME).h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: +Declaration of the entry point symbol comes from the above mentioned generated header file, ``${ULP_APP_NAME}.h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: .global entry diff --git a/docs/en/api-guides/unit-tests-cmake.rst b/docs/en/api-guides/unit-tests-legacy.rst similarity index 76% rename from docs/en/api-guides/unit-tests-cmake.rst rename to docs/en/api-guides/unit-tests-legacy.rst index e08b912f8..60e39bf85 100644 --- a/docs/en/api-guides/unit-tests-cmake.rst +++ b/docs/en/api-guides/unit-tests-legacy.rst @@ -1,8 +1,8 @@ -Unit Testing in ESP32 (CMake) -============================= +Unit Testing (Legacy GNU Make) +============================== :link_to_translation:`zh_CN:[中文]` -.. include:: ../cmake-warning.rst +.. include:: ../gnu-make-legacy.rst ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively. @@ -28,18 +28,9 @@ Identifiers are used to group related test, or tests with specific properties. There is no need to add a main function with ``UNITY_BEGIN()`` and ``​UNITY_END()`` in each test case. ``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``​UNITY_END()``. -The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt `, since they are themselves, -components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components -:ref:`should list their sources manually `; for component tests however, this requirement is relaxed and the -use of ``COMPONENT_SRCDIRS`` is advised. +Each `test` subdirectory needs to include component.mk file with at least the following line of code:: -Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as follows: - -.. code:: cmake - - idf_component_register(SRC_DIRS "." - INCLUDE_DIRS "." - REQUIRES unity) + COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive See http://www.throwtheswitch.org/unity for more information about writing tests in Unity. @@ -87,13 +78,27 @@ As the secnario in the above example, slave should get GPIO level after master s DUT1 (master) console:: Waiting for signal: [output high level]! - Please press "Enter" key to once any board send this signal. + Please press "Enter" key once any board send this signal. DUT2 (slave) console:: Send signal: [output high level]! -Once the signal is set from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. +Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. + +Signals can also be used to pass parameters between multiple devices. For example, DUT1 want to know the MAC address of DUT2, so it can connect to DUT2. +In this case, ``unity_wait_for_signal_param`` and ``unity_send_signal_param`` can be used: + +DUT1 console:: + + Waiting for signal: [dut2 mac address]! + Please input parameter value from any board send this signal and press "Enter" key. + +DUT2 console:: + + Send signal: [dut2 mac address][10:20:30:40:50:60]! + +Once the signal is sent from DUT2, you need to input ``10:20:30:40:50:60`` on DUT1 and press "Enter". Then DUT1 will get the MAC address string of DUT2 and unblocks from ``unity_wait_for_signal_param``, start to connect to DUT2. Add multiple stages test cases @@ -128,15 +133,15 @@ Make sure that IDF_PATH environment variable is set to point to the path of esp- Change into tools/unit-test-app directory to configure and build it: -* `idf.py menuconfig` - configure unit test app. +* `make menuconfig` - configure unit test app. -* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory. -* `idf.py -T xxx build` - build unit test app with tests for specific components. -* `idf.py -T all -E xxx build` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp -E mbedtls build` - build all unit tests exludes ulp and mbedtls components). +* `make TESTS_ALL=1` - build unit test app with tests for each component having tests in the ``test`` subdirectory. +* `make TEST_COMPONENTS='xxx'` - build unit test app with tests for specific components. +* `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'` - build all unit tests exludes ulp and mbedtls components). -When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output. +When the build finishes, it will print instructions for flashing the chip. You can simply run ``make flash`` to flash all build output. -You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. +You can also run ``make flash TESTS_ALL=1`` or ``make TEST_COMPONENTS='xxx'`` to build and flash. Everything needed will be rebuilt automatically before flashing. Use menuconfig to set the serial port for flashing. @@ -177,13 +182,13 @@ Normal case will print the case name and description. Master slave cases will al Test cases can be run by inputting one of the following: -- Test case name in quotation marks to run a single test case +- Test case name in quotation marks (for example, ``"esp_ota_begin() verifies arguments"``) to run a single test case. -- Test case index to run a single test case +- Test case index (for example, ``1``) to run a single test case. -- Module name in square brackets to run all test cases for a specific module +- Module name in square brackets (for example, ``[cxx]``) to run all test cases for a specific module. -- An asterisk to run all test cases +- An asterisk (``*``) to run all test cases ``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages test case. These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros. diff --git a/docs/en/api-guides/unit-tests.rst b/docs/en/api-guides/unit-tests.rst index 43346e4b4..f2b564aa6 100644 --- a/docs/en/api-guides/unit-tests.rst +++ b/docs/en/api-guides/unit-tests.rst @@ -1,5 +1,5 @@ Unit Testing in ESP32 -===================== +============================= :link_to_translation:`zh_CN:[中文]` ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively. @@ -26,9 +26,18 @@ Identifiers are used to group related test, or tests with specific properties. There is no need to add a main function with ``UNITY_BEGIN()`` and ``​UNITY_END()`` in each test case. ``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``​UNITY_END()``. -Each `test` subdirectory needs to include component.mk file with at least the following line of code:: +The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt `, since they are themselves, +components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components +:ref:`should list their sources manually `; for component tests however, this requirement is relaxed and the +use of ``COMPONENT_SRCDIRS`` is advised. - COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive +Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as follows: + +.. code:: cmake + + idf_component_register(SRC_DIRS "." + INCLUDE_DIRS "." + REQUIRES unity) See http://www.throwtheswitch.org/unity for more information about writing tests in Unity. @@ -76,27 +85,13 @@ As the secnario in the above example, slave should get GPIO level after master s DUT1 (master) console:: Waiting for signal: [output high level]! - Please press "Enter" key once any board send this signal. + Please press "Enter" key to once any board send this signal. DUT2 (slave) console:: Send signal: [output high level]! -Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. - -Signals can also be used to pass parameters between multiple devices. For example, DUT1 want to know the MAC address of DUT2, so it can connect to DUT2. -In this case, ``unity_wait_for_signal_param`` and ``unity_send_signal_param`` can be used: - -DUT1 console:: - - Waiting for signal: [dut2 mac address]! - Please input parameter value from any board send this signal and press "Enter" key. - -DUT2 console:: - - Send signal: [dut2 mac address][10:20:30:40:50:60]! - -Once the signal is sent from DUT2, you need to input ``10:20:30:40:50:60`` on DUT1 and press "Enter". Then DUT1 will get the MAC address string of DUT2 and unblocks from ``unity_wait_for_signal_param``, start to connect to DUT2. +Once the signal is set from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. Add multiple stages test cases @@ -131,15 +126,15 @@ Make sure that IDF_PATH environment variable is set to point to the path of esp- Change into tools/unit-test-app directory to configure and build it: -* `make menuconfig` - configure unit test app. +* `idf.py menuconfig` - configure unit test app. -* `make TESTS_ALL=1` - build unit test app with tests for each component having tests in the ``test`` subdirectory. -* `make TEST_COMPONENTS='xxx'` - build unit test app with tests for specific components. -* `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'` - build all unit tests exludes ulp and mbedtls components). +* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory. +* `idf.py -T xxx build` - build unit test app with tests for specific components. +* `idf.py -T all -E xxxbuild` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp mbedtls build` - build all unit tests exludes ulp and mbedtls components). -When the build finishes, it will print instructions for flashing the chip. You can simply run ``make flash`` to flash all build output. +When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output. -You can also run ``make flash TESTS_ALL=1`` or ``make TEST_COMPONENTS='xxx'`` to build and flash. Everything needed will be rebuilt automatically before flashing. +You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. Use menuconfig to set the serial port for flashing. @@ -180,13 +175,13 @@ Normal case will print the case name and description. Master slave cases will al Test cases can be run by inputting one of the following: -- Test case name in quotation marks (for example, ``"esp_ota_begin() verifies arguments"``) to run a single test case. +- Test case name in quotation marks to run a single test case -- Test case index (for example, ``1``) to run a single test case. +- Test case index to run a single test case -- Module name in square brackets (for example, ``[cxx]``) to run all test cases for a specific module. +- Module name in square brackets to run all test cases for a specific module -- An asterisk (``*``) to run all test cases +- An asterisk to run all test cases ``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages test case. These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros. diff --git a/docs/en/api-reference/kconfig.rst b/docs/en/api-reference/kconfig.rst index a98de1e60..4fc49900b 100644 --- a/docs/en/api-reference/kconfig.rst +++ b/docs/en/api-reference/kconfig.rst @@ -1,19 +1,28 @@ -Configuration Options +Project Configuration ********************* Introduction ============ -ESP-IDF uses Kconfig_ system to provide a compile-time configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc. +ESP-IDF uses Kconfig_ system to provide a compile-time project configuration mechanism. Kconfig is based around options of several types: integer, string, boolean. Kconfig files specify dependencies between options, default values of the options, the way the options are grouped together, etc. -Applications developers can use ``make menuconfig`` build target to edit components' configuration. This configuration is saved inside ``sdkconfig`` file in the project root directory. Based on ``sdkconfig``, application build targets will generate ``sdkconfig.h`` file in the build directory, and will make sdkconfig options available to component makefiles. +.. _project-configuration-menu: + +Project Configuration Menu +========================== + +Application developers can open a terminal-based project configuration menu with the ``idf.py menuconfig`` build target. + +After being updated, this configuration is saved inside ``sdkconfig`` file in the project root directory. Based on ``sdkconfig``, application build targets will generate ``sdkconfig.h`` file in the build directory, and will make sdkconfig options available to the project build system and source files. + +(For the legacy GNU Make build system, the project configuration menu is opened with ``make menuconfig``.) Using sdkconfig.defaults ======================== When updating ESP-IDF version, it is not uncommon to find that new Kconfig options are introduced. When this happens, application build targets will offer an interactive prompt to select values for the new options. New values are then written into ``sdkconfig`` file. To supress interactive prompts, applications can either define ``BATCH_BUILD`` environment variable, which will cause all prompts to be suppressed. This is the same effect as that of ``V`` or ``VERBOSE`` variables. Alternatively, ``defconfig`` build target can be used to update configuration for all new variables to the default values. -In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the ``sdkconfig`` file. Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for git). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that when ``make defconfig`` is used, settings in sdkconfig will be overriden by the ones in ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`. +In some cases, such as when ``sdkconfig`` file is under revision control, the fact that ``sdkconfig`` file gets changed by the build system may be inconvenient. The build system offers a way to avoid this, in the form of ``sdkconfig.defaults`` file. This file is never touched by the build system, and must be created manually. It can contain all the options which matter for the given application. The format is the same as that of the ``sdkconfig`` file. Once ``sdkconfig.defaults`` is created, ``sdkconfig`` can be deleted and added to the ignore list of the revision control system (e.g. ``.gitignore`` file for git). Project build targets will automatically create ``sdkconfig`` file, populated with the settings from ``sdkconfig.defaults`` file, and the rest of the settings will be set to their default values. Note that when ``idf.py defconfig`` is used, settings in sdkconfig will be overriden by the ones in ``sdkconfig.defaults``. For more information, see :ref:`custom-sdkconfig-defaults`. Kconfig Formatting Rules ======================== diff --git a/docs/en/api-reference/protocols/mqtt.rst b/docs/en/api-reference/protocols/mqtt.rst index 053159eba..cb956755a 100644 --- a/docs/en/api-reference/protocols/mqtt.rst +++ b/docs/en/api-reference/protocols/mqtt.rst @@ -94,12 +94,12 @@ SSL For more options on ``esp_mqtt_client_config_t``, please refer to API reference below -Change settings in ``menuconfig`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Change settings in Project Configuration Menu +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - make menuconfig - -> Component config -> ESP-MQTT Configuration + idf.py menuconfig + -> Component config -> ESP-MQTT Configuration - :ref:`CONFIG_MQTT_PROTOCOL_311`: Enables 3.1.1 version of MQTT protocol diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index dd8c6bd99..87a9e1624 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -31,8 +31,8 @@ The component has API functions for reading and writing fields. Access to the fi CSV files: -* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command 'make efuse_common_table' or `idf.py efuse_common_table`). Note that changes in this file can lead to incorrect operation. -* custom - (optional and can be enabled by :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file (run command 'make efuse_custom_table' or `idf.py efuse_custom_table`). +* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command ``idf.py efuse_common_table``). Note that changes in this file can lead to incorrect operation. +* custom - (optional and can be enabled by :envvar:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running ``idf.py efuse_custom_table``. Description CSV file @@ -84,7 +84,7 @@ efuse_table_gen.py tool The tool is designed to generate C-source files from CSV file and validate fields. First of all, the check is carried out on the uniqueness of the names and overlaps of the field bits. If an additional `custom` file is used, it will be checked with the existing `common` file (esp_efuse_table.csv). In case of errors, a message will be displayed and the string that caused the error. C-source files contain structures of type `esp_efuse_desc_t`. -To generate a `common` files, use the following command 'make efuse_common_table' or `idf.py efuse_common_table` or: +To generate a `common` files, use the following command ``idf.py efuse_common_table`` or: :: @@ -96,7 +96,7 @@ After generation in the folder `esp32` create: * `esp_efuse_table.c` file. * In `include` folder `esp_efuse_table.c` file. -To generate a `custom` files, use the following command 'make efuse_custom_table' or `idf.py efuse_custom_table` or: +To generate a `custom` files, use the following command ``idf.py efuse_custom_table`` or: :: @@ -170,7 +170,7 @@ For frequently used fields, special functions are made, like this :cpp:func:`esp How add a new field ------------------- -1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``make show_efuse_table`` or ``idf.py show_efuse_table`` or the next command: +1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``idf.py show_efuse_table`` or the next command: :: diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index 337bf3bb2..24c9cb25e 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/docs/en/api-reference/system/freertos_additions.rst @@ -420,7 +420,7 @@ Interrupt respectively. Vanilla FreeRTOS hooks are referred to as **Legacy Hooks** in ESP-IDF FreeRTOS. To enable legacy hooks, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS` should be enabled -in ``make menuconfig``. +in :doc:`project configuration menu `. Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook()`` and ``vApplicationTickHook()`` can only be defined once. However, the ESP32 is dual core diff --git a/docs/en/api-reference/system/heap_debug.rst b/docs/en/api-reference/system/heap_debug.rst index 2f0390706..0c49409bb 100644 --- a/docs/en/api-reference/system/heap_debug.rst +++ b/docs/en/api-reference/system/heap_debug.rst @@ -38,7 +38,7 @@ Heap corruption detection allows you to detect various types of heap memory erro Assertions ^^^^^^^^^^ -The heap implementation (``multi_heap.c``, etc.) includes a lot of assertions which will fail if the heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in ``make menuconfig`` under ``Compiler options``. +The heap implementation (``multi_heap.c``, etc.) includes a lot of assertions which will fail if the heap memory is corrupted. To detect heap corruption most effectively, ensure that assertions are enabled in the project configuration menu under ``Compiler options`` -> :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL`. If a heap integrity assertion fails, a line will be printed like ``CORRUPT HEAP: multi_heap.c:225 detected at 0x3ffbb71c``. The memory address which is printed is the address of the heap structure which has corrupt content. @@ -62,7 +62,7 @@ Configuration Temporarily increasing the heap corruption detection level can give more detailed information about heap corruption errors. -In ``make menuconfig``, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :ref:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels: +In the project configuration menu, under ``Component config`` there is a menu ``Heap memory debugging``. The setting :ref:`CONFIG_HEAP_CORRUPTION_DETECTION` can be set to one of three levels: Basic (no poisoning) ++++++++++++++++++++ @@ -143,7 +143,7 @@ Standalone Mode Once you've identified the code which you think is leaking: -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Standalone`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`). +- In the project configuration menu, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Standalone`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`). - Call the function :cpp:func:`heap_trace_init_standalone` early in the program, to register a buffer which can be used to record the memory trace. - Call the function :cpp:func:`heap_trace_start` to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory. - Call the function :cpp:func:`heap_trace_stop` to stop the trace once the suspect piece of code has finished executing. @@ -205,7 +205,7 @@ In ``HEAP_TRACE_LEAKS`` mode, for each traced memory allocation which has not al - ``caller 0x...`` gives the call stack of the call to malloc()/free(), as a list of PC addresses. These can be decoded to source files and line numbers, as shown above. -The depth of the call stack recorded for each trace entry can be configured in ``make menuconfig``, under ``Heap Memory Debugging`` -> ``Enable heap tracing`` -> ``Heap tracing stack depth``. Up to 10 stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory usage of each ``heap_trace_record_t`` record by eight bytes. +The depth of the call stack recorded for each trace entry can be configured in the project configuration menu, under ``Heap Memory Debugging`` -> ``Enable heap tracing`` -> ``Heap tracing stack depth``. Up to 10 stack frames can be recorded for each allocation (the default is 2). Each additional stack frame increases the memory usage of each ``heap_trace_record_t`` record by eight bytes. Finally, the total number of 'leaked' bytes (bytes allocated but not freed while trace was running) is printed, and the total number of allocations this represents. @@ -217,9 +217,9 @@ Host-Based Mode Once you've identified the code which you think is leaking: -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> ``Heap tracing`` and select ``Host-Based`` option (see :ref:`CONFIG_HEAP_TRACING_DEST`). -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``Data Destination`` and select ``Trace memory``. -- Under ``make menuconfig``, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``FreeRTOS SystemView Tracing`` and check ``SystemView Tracing Enable``. +- In the project configuration menu, navigate to ``Component settings`` -> ``Heap Memory Debugging`` -> :ref:`CONFIG_HEAP_TRACING_DEST` and select ``Host-Based``. +- In the project configuration menu, navigate to ``Component settings`` -> ``Application Level Tracing`` -> :ref:`CONFIG_ESP32_APPTRACE_DESTINATION` and select ``Trace memory``. +- In the project configuration menu, navigate to ``Component settings`` -> ``Application Level Tracing`` -> ``FreeRTOS SystemView Tracing`` and enable :ref:`CONFIG_SYSVIEW_ENABLE`. - Call the function :cpp:func:`heap_trace_init_tohost` early in the program, to initialize JTAG heap tracing module. - Call the function :cpp:func:`heap_trace_start` to begin recording all mallocs/frees in the system. Call this immediately before the piece of code which you suspect is leaking memory. In host-based mode argument to this function is ignored and heap tracing module behaves like ``HEAP_TRACE_ALL`` was passed: all allocations and deallocations are sent to the host. @@ -250,7 +250,7 @@ An example:: To gather and analyse heap trace do the following on the host: -1. Build the program and download it to the target as described in :doc:`Build and Flash `. +1. Build the program and download it to the target as described in :ref:`Getting Started Guide `. 2. Run OpenOCD (see :doc:`JTAG Debugging `). diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 711422540..cf6eb5020 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -41,7 +41,7 @@ DRAM At startup, the DRAM heap contains all data memory which is not statically allocated by the app. Reducing statically allocated buffers will increase the amount of available free heap. -To find the amount of statically allocated memory, use the :ref:`make size ` or :ref:`idf.py size ` (for CMake) command. +To find the amount of statically allocated memory, use the :ref:`idf.py size ` command. .. note:: Due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap. @@ -52,7 +52,7 @@ IRAM At startup, the IRAM heap contains all instruction memory which is not used by the app executable code. -The :ref:`make size ` and :ref:`idf.py size ` commands can be used to find the amount of IRAM used by the app. +The :ref:`idf.py size ` command can be used to find the amount of IRAM used by the app. D/IRAM ^^^^^^ diff --git a/docs/en/api-reference/system/system.rst b/docs/en/api-reference/system/system.rst index 184e38c68..4d72c587f 100644 --- a/docs/en/api-reference/system/system.rst +++ b/docs/en/api-reference/system/system.rst @@ -129,12 +129,13 @@ App version Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars. -To set version in your project manually you need to set ``PROJECT_VER`` variable in your project Makefile/CMakeLists.txt: +To set version in your project manually you need to set ``PROJECT_VER`` variable in your project CMakeLists.txt/Makefile: -* For Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including project.mk -* For Cmake build system: in application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including project.cmake. +* In application CMakeLists.txt put ``set(PROJECT_VER "0.1.0.1")`` before including ``project.cmake``. -If ``PROJECT_VER`` variable is not set in project Makefile/CMakeLists.txt then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. +(For legacy GNU Make build system: in application Makefile put ``PROJECT_VER = "0.1.0.1"`` before including ``project.mk``.) + +If ``PROJECT_VER`` variable is not set in the project then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions. API Reference ------------- diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index 6f2f5cc4e..5ba5b2fd1 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -6,7 +6,7 @@ Overview The ESP-IDF has support for two types of watchdogs: The Interrupt Watchdog Timer and the Task Watchdog Timer (TWDT). The Interrupt Watchdog Timer and the TWDT -can both be enabled using ``make menuconfig``, however the TWDT can also be +can both be enabled using :ref:`project-configuration-menu`, however the TWDT can also be enabled during runtime. The Interrupt Watchdog is responsible for detecting instances where FreeRTOS task switching is blocked for a prolonged period of time. The TWDT is responsible for detecting instances of tasks running without @@ -63,7 +63,7 @@ longer call :cpp:func:`esp_task_wdt_reset`. Once all tasks have unsubscribed form the TWDT, the TWDT can be deinitialized by calling :cpp:func:`esp_task_wdt_deinit()`. -By default :ref:`CONFIG_ESP_TASK_WDT` in ``make menuconfig`` will be enabled causing +By default :ref:`CONFIG_ESP_TASK_WDT` in :ref:`project-configuration-menu` be enabled causing the TWDT to be initialized automatically during startup. Likewise :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing diff --git a/docs/en/api-reference/template.rst b/docs/en/api-reference/template.rst index 3c14c19b2..ed749c056 100644 --- a/docs/en/api-reference/template.rst +++ b/docs/en/api-reference/template.rst @@ -79,7 +79,7 @@ API Reference For example see :idf_file:`docs/en/api-reference/wifi/esp_wifi.rst` - 6. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp-cmake.rst` for example. + 6. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/en/api-guides/ulp.rst` for example. Below is the list of common ``.. doxygen...::`` directives: diff --git a/docs/en/cmake-pending-features.rst b/docs/en/cmake-pending-features.rst deleted file mode 100644 index 2223f5d4b..000000000 --- a/docs/en/cmake-pending-features.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. important:: - The following features are not yet supported with the CMake-based build system: - - - Eclipse IDE Documentation - - Support for these features will be available before CMake becomes the default build system. - diff --git a/docs/en/cmake-warning.rst b/docs/en/cmake-warning.rst deleted file mode 100644 index 3f97614f4..000000000 --- a/docs/en/cmake-warning.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. note:: - This is documentation for the CMake-based build system which is currently in preview release. If you encounter any gaps or bugs, please report them in the `Issues `_ section of the ESP-IDF repository. - - The CMake-based build system will become the default build system in ESP-IDF V4.0. The existing GNU Make based build system will be deprecated in ESP-IDF V5.0. diff --git a/docs/en/get-started-cmake/add-idf_path-to-profile.rst b/docs/en/get-started-cmake/add-idf_path-to-profile.rst deleted file mode 100644 index cdaf9a5b8..000000000 --- a/docs/en/get-started-cmake/add-idf_path-to-profile.rst +++ /dev/null @@ -1,3 +0,0 @@ -:orphan: - -.. Remove this file when the Chinese translation of CMake getting started guide is updated diff --git a/docs/en/get-started-cmake/eclipse-setup.rst b/docs/en/get-started-cmake/eclipse-setup.rst deleted file mode 100644 index 2e2b105bc..000000000 --- a/docs/en/get-started-cmake/eclipse-setup.rst +++ /dev/null @@ -1,12 +0,0 @@ -**************************************** -Build and Flash with Eclipse IDE (CMake) -**************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon. - -.. _eclipse.org: https://www.eclipse.org/ - diff --git a/docs/en/get-started-cmake/index.rst b/docs/en/get-started-cmake/index.rst deleted file mode 100644 index e5f810c09..000000000 --- a/docs/en/get-started-cmake/index.rst +++ /dev/null @@ -1,491 +0,0 @@ -******************* -Get Started (CMake) -******************* - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -.. include:: ../cmake-pending-features.rst - -This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif. - -After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board. - -.. include:: /_build/inc/version-note.inc - -Introduction -============ - -ESP32 is a system on a chip that integrates the following features: - -* Wi-Fi (2.4 GHz band) -* Bluetooth 4.2 -* Dual high performance cores -* Ultra Low Power co-processor -* Several peripherals - -Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. - -Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. - -What You Need -============= - -Hardware: - -* An **ESP32** board -* **USB cable** - USB A / micro USB B -* **Computer** running Windows, Linux, or macOS - -Software: - -* **Toolchain** to compile code for ESP32 -* **Build tools** - CMake and Ninja to build a full **Application** for ESP32 -* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** -* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ - - -.. figure:: ../../_static/what-you-need-cmake.png - :align: center - :alt: Development of applications for ESP32 - :figclass: align-center - - Development of applications for ESP32 - - -Development Board Overviews -=========================== - -If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware. - -.. toctree:: - :maxdepth: 1 - - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> - - -.. _get-started-step-by-step-cmake: - -Installation Step by Step -========================= - -This is a detailed roadmap to walk you through the installation process. - -Setting up Development Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* :ref:`get-started-get-prerequisites-cmake` for :doc:`Windows `, :doc:`Linux ` or :doc:`macOS ` -* :ref:`get-started-get-esp-idf-cmake` -* :ref:`get-started-set-up-tools-cmake` -* :ref:`get-started-set-up-env-cmake` - -Creating Your First Project -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* :ref:`get-started-start-project-cmake` -* :ref:`get-started-connect-cmake` -* :ref:`get-started-configure-cmake` -* :ref:`get-started-build-cmake` -* :ref:`get-started-flash-cmake` -* :ref:`get-started-build-monitor-cmake` - - -.. _get-started-get-prerequisites-cmake: - -Step 1. Install prerequisites -============================= - -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 - Linux - macOS - -* :doc:`windows-setup` -* :doc:`linux-setup` -* :doc:`macos-setup` - -.. _get-started-get-esp-idf-cmake: - -Step 2. Get ESP-IDF -=================== - -To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository `_. - -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``. - -.. 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: - -.. include:: /_build/inc/git-clone-bash.inc - -ESP-IDF will be downloaded into ``~/esp/esp-idf``. - -Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. - -Windows -~~~~~~~ - -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. - -If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions `. - -.. _get-started-set-up-tools-cmake: - -Step 3. Set up the tools -======================== - -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 -~~~~~~~ - -:ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools. - -If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps: - -.. code-block:: batch - - cd %userprofile%\esp\esp-idf - install.bat - -Linux and macOS -~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp/esp-idf - ./install.sh - -Customizing the tools installation path -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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. - -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. - -.. _get-started-set-up-env-cmake: - -Step 4. Set up the environment variables -======================================== - -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: - -Step 5. Start a Project -======================= - -Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. - -Copy :example:`get-started/hello_world` to ``~/esp`` directory: - -Linux and macOS -~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp - cp -r $IDF_PATH/examples/get-started/hello_world . - -Windows -~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp - xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world - -There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. - -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. - -.. _get-started-connect-cmake: - -Step 6. Connect Your Device -=========================== - -Now connect your ESP32 board to the computer and check under what serial port the board is visible. - -Serial ports have the following patterns in their names: - -- **Windows**: names like ``COM1`` -- **Linux**: starting with ``/dev/tty`` -- **macOS**: starting with ``/dev/cu.`` - -If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details. - -.. note:: - - Keep the port name handy as you will need it in the next steps. - - -.. _get-started-configure-cmake: - -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 -~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp/hello_world - idf.py menuconfig - -If your default version of Python is 3.x, you may need to run ``python2 $(which idf.py) menuconfig`` instead. - -Windows -~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp\hello_world - idf.py menuconfig - -If the previous steps have been done correctly, the following menu appears: - -.. figure:: ../../_static/project-configuration.png - :align: center - :alt: Project configuration - Home window - :figclass: align-center - - Project configuration - Home window - -To navigate and use ``menuconfig``, press the following keys: - -* Arrow keys for navigation -* ``Enter`` to go into a submenu -* ``Esc`` to go up one level or exit -* ``?`` to see a help screen. Enter key exits the help screen -* ``Space``, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``" -* ``?`` while highlighting a configuration item to display help about that item -* ``/`` to find configuration items - -.. attention:: - - If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. - -.. _get-started-build-cmake: - -Step 8. Build the Project -========================= - -Build the project by running:: - - idf.py build - -This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. - -.. code-block:: none - - $ idf.py build - Running cmake in directory /path/to/hello_world/build - Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... - Warn about uninitialized values. - -- Found Git: /usr/bin/git (found version "2.17.0") - -- Building empty aws_iot component due to configuration - -- Component names: ... - -- Component paths: ... - - ... (more lines of build system output) - - [527/527] Generating hello-world.bin - esptool.py v2.3.1 - - Project build complete. To flash, run this command: - ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin - or run 'idf.py -p PORT flash' - -If there are no errors, the build will finish by generating the firmware binary .bin file. - - -.. _get-started-flash-cmake: - -Step 9. Flash onto the Device -============================= - -Flash the binaries that you just built onto your ESP32 board by running:: - - idf.py -p PORT [-b BAUD] flash - -Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect-cmake`. - -You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``. - -For more information on idf.py arguments, see :ref:`idf.py`. - -.. note:: - - The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary. - -.. code-block:: none - - Running esptool.py in directory [...]/esp/hello_world - Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"... - esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin - esptool.py v2.3.1 - Connecting.... - Detecting chip type... ESP32 - Chip is ESP32D0WDQ6 (revision 1) - Features: WiFi, BT, Dual Core - Uploading stub... - Running stub... - Stub running... - Changing baud rate to 460800 - Changed. - Configuring flash size... - Auto-detected Flash size: 4MB - Flash params set to 0x0220 - Compressed 22992 bytes to 13019... - Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)... - Hash of data verified. - Compressed 3072 bytes to 82... - Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)... - Hash of data verified. - Compressed 136672 bytes to 67544... - Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... - Hash of data verified. - - Leaving... - Hard resetting via RTS pin... - -If there are no issues by the end of the flash process, the module will be reset and the “hello_world” application will be running. - -.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide `. - - -.. _get-started-build-monitor-cmake: - -Step 10. Monitor -================ - -To check if "hello_world" is indeed running, type ``idf.py -p PORT monitor`` (Do not forget to replace PORT with your serial port name). - -This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application:: - - $ idf.py -p /dev/ttyUSB0 monitor - Running idf_monitor in directory [...]/esp/hello_world/build - Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"... - --- idf_monitor on /dev/ttyUSB0 115200 --- - --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- - ets Jun 8 2016 00:22:57 - - rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) - ets Jun 8 2016 00:22:57 - ... - -After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application. - -.. code-block:: none - - ... - Hello world! - Restarting in 10 seconds... - I (211) cpu_start: Starting scheduler on APP CPU. - Restarting in 9 seconds... - Restarting in 8 seconds... - Restarting in 7 seconds... - -To exit IDF monitor use the shortcut ``Ctrl+]``. - -If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. - -.. code-block:: none - - e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA - ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp - -If you have such a problem, do the following: - -1. Exit the monitor. -2. Go back to :ref:`menuconfig `. -3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. -4. After that, :ref:`build and flash ` the application again. - -.. note:: - - You can combine building, flashing and monitoring into one step by running:: - - idf.py -p PORT flash monitor - -See also: - -- :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. -- :ref:`idf.py` for a full reference of ``idf.py`` commands and options. - -**That's all that you need to get started with ESP32!** - -Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications. - -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`. - -Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `. - -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 - - establish-serial-connection - eclipse-setup - ../api-guides/tools/idf-monitor - toolchain-setup-scratch - -.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ -.. _Releases page: https://github.com/espressif/esp-idf/releases \ No newline at end of file diff --git a/docs/en/get-started-cmake/linux-setup-scratch.rst b/docs/en/get-started-cmake/linux-setup-scratch.rst deleted file mode 100644 index 51abaf6fd..000000000 --- a/docs/en/get-started-cmake/linux-setup-scratch.rst +++ /dev/null @@ -1,77 +0,0 @@ -****************************************** -Setup Linux Toolchain from Scratch (CMake) -****************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`. - -Install Prerequisites -===================== - -To compile with ESP-IDF you need to get the following packages: - -- CentOS 7:: - - sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - -- Ubuntu and Debian:: - - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache - -.. 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". - -Compile the Toolchain from Source -================================= - -- Install dependencies: - - - CentOS 7:: - - sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make - - - Ubuntu pre-16.04:: - - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make - - - Ubuntu 16.04 or newer:: - - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - - Debian 9:: - - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - - Arch:: - - TODO - -Create the working directory and go into it:: - - mkdir -p ~/esp - cd ~/esp - -Download ``crosstool-NG`` and build it: - -.. include:: /_build/inc/scratch-build-code.inc - -Build the toolchain:: - - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf - -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 -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started-cmake/linux-setup.rst b/docs/en/get-started-cmake/linux-setup.rst deleted file mode 100644 index 429755b9b..000000000 --- a/docs/en/get-started-cmake/linux-setup.rst +++ /dev/null @@ -1,68 +0,0 @@ -*********************************************** -Installation of Prerequisites for Linux (CMake) -*********************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Install Prerequisites -===================== - -To compile with ESP-IDF you need to get the following packages: - -- CentOS 7:: - - sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - -- Ubuntu and Debian:: - - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache - -.. 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". - -Additional Tips -=============== - -Permission issues /dev/ttyUSB0 ------------------------------- - -With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group`. - - -Arch Linux Users ----------------- - -To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. - -Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: - -- https://aur.archlinux.org/packages/ncurses5-compat-libs/ -- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ - -Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above. - -Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. - - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. - - -Related Documents -================= - -.. toctree:: - :maxdepth: 1 - - linux-setup-scratch - - -.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/en/get-started-cmake/macos-setup-scratch.rst b/docs/en/get-started-cmake/macos-setup-scratch.rst deleted file mode 100644 index 45fa4238c..000000000 --- a/docs/en/get-started-cmake/macos-setup-scratch.rst +++ /dev/null @@ -1,88 +0,0 @@ -*********************************************** -Setup Toolchain for Mac OS from Scratch (CMake) -*********************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Package Manager -=============== - -To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain`, you will need to install either the MacPorts_ or homebrew_ package manager. - -MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. - - .. _homebrew: https://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php - -See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. - -Install Prerequisites -===================== - -- install pip:: - - sudo easy_install pip - -- install pyserial:: - - pip install --user pyserial - -- install CMake & Ninja build: - - - If you have HomeBrew, you can run:: - - brew install cmake ninja - - - If you have MacPorts, you can run:: - - sudo port install cmake ninja - -Compile the Toolchain from Source -================================= - -- Install dependencies: - - - with MacPorts:: - - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - - - with homebrew:: - - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make - -Create a case-sensitive filesystem image:: - - hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" - -Mount it:: - - hdiutil mount ~/esp/crosstool.dmg - -Create a symlink to your work directory:: - - mkdir -p ~/esp - ln -s /Volumes/ctng ~/esp/ctng-volume - -Go into the newly created directory:: - - cd ~/esp/ctng-volume - -Download ``crosstool-NG`` and build it: - -.. include:: /_build/inc/scratch-build-code.inc - -Build the toolchain:: - - ./ct-ng xtensa-esp32-elf - ./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``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable. - - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started-cmake/macos-setup.rst b/docs/en/get-started-cmake/macos-setup.rst deleted file mode 100644 index 7926ea9d5..000000000 --- a/docs/en/get-started-cmake/macos-setup.rst +++ /dev/null @@ -1,60 +0,0 @@ -*********************************************** -Installation of Prerequisites for macOS (CMake) -*********************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Install Prerequisites -===================== - -ESP-IDF will use the version of Python installed by default on macOS. - -- install pip:: - - sudo easy_install pip - -- install pyserial:: - - pip install --user pyserial - -- install CMake & Ninja build: - - - If you have HomeBrew_, you can run:: - - brew install cmake ninja - - - If you have MacPorts_, you can run:: - - sudo port install cmake ninja - - - 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_. - -.. note:: - If an error like this is shown during any step:: - - 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``. - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. - -Related Documents -================= - -.. toctree:: - :maxdepth: 1 - - macos-setup-scratch - -.. _cmake: https://cmake.org/ -.. _ninja: https://ninja-build.org/ -.. _ccache: https://ccache.samba.org/ -.. _homebrew: https://brew.sh/ -.. _MacPorts: https://www.macports.org/install.php diff --git a/docs/en/get-started-cmake/windows-setup-scratch.rst b/docs/en/get-started-cmake/windows-setup-scratch.rst deleted file mode 100644 index 4fa8168fe..000000000 --- a/docs/en/get-started-cmake/windows-setup-scratch.rst +++ /dev/null @@ -1,122 +0,0 @@ -********************************** -Windows Setup from Scratch (CMake) -********************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer ` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install. - -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 -===== - -cmake -^^^^^ - -Download the latest stable release of CMake_ for Windows and run the installer. - -When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user". - -Ninja build -^^^^^^^^^^^ - -.. note:: - Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented. - -Download the ninja_ latest stable Windows release from the (`download page `_). - -The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path `_ (or you can choose a directory which is already on your Path). - - -Python 2.x -^^^^^^^^^^ - -Download the latest Python_ 2.7 for Windows installer, and run it. - -The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed". - -Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command:: - - pip install --user pyserial - -MConf for IDF -^^^^^^^^^^^^^ - -Download the configuration tool mconf-idf from the `kconfig-frontends releases page `_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF. - -This tool will also need to be unzipped to a directory which is then `added to your Path `_. - -Toolchain Setup -=============== - -.. include:: /_build/inc/download-links.inc - -Download the precompiled Windows toolchain: - -|download_link_win32| - -Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``. - -Next, the ``bin`` subdirectory of this directory must be `added to your Path `_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``. - -.. note:: - If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. - - -.. _add-directory-windows-path-cmake: - -Adding Directory to Path -======================== - -To add any new directory to your Windows Path environment variable: - -Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings). - -Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;``. - - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. - -.. _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/ - diff --git a/docs/en/get-started-cmake/windows-setup.rst b/docs/en/get-started-cmake/windows-setup.rst deleted file mode 100644 index d226c5f0f..000000000 --- a/docs/en/get-started-cmake/windows-setup.rst +++ /dev/null @@ -1,70 +0,0 @@ -************************************************* -Installation of Prerequisites for Windows (CMake) -************************************************* - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -.. note:: - The CMake-based build system is only supported on 64-bit versions of Windows. - -Introduction -============ - -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 the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse ` 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-2.0.exe - -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. - -The installer also offers to download one of the ESP-IDF release versions. - -Using the Command Prompt -======================== - -For the remaining Getting Started steps, we're going to use the Windows Command Prompt. - -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. - -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: - -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. - -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 -========== - -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 -================= - -For advanced users who want to customize the install process: - -.. toctree:: - :maxdepth: 1 - - windows-setup-scratch - windows-setup-update - -.. _MSYS2: https://msys2.github.io/ -.. _cmake: https://cmake.org/download/ -.. _ninja: https://ninja-build.org/ -.. _Python: https://www.python.org/downloads/windows/ -.. _Git for Windows: https://gitforwindows.org/ -.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/ -.. _Github Desktop: https://desktop.github.com/ diff --git a/docs/en/get-started-legacy/add-idf_path-to-profile.rst b/docs/en/get-started-legacy/add-idf_path-to-profile.rst new file mode 100644 index 000000000..2745f7b0e --- /dev/null +++ b/docs/en/get-started-legacy/add-idf_path-to-profile.rst @@ -0,0 +1,67 @@ +Add IDF_PATH to User Profile (Legacy GNU Make) +============================================== +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below. + + +.. _add-idf_path-to-profile-windows-legacy: + +Windows +------- + +The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window. + +#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``. + +#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf`` + +#. Add the ``export`` command to the script file, e.g.:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + + Remember to replace back-slashes with forward-slashes in the original Windows path. + +#. Save the script file. + +#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing:: + + printenv IDF_PATH + + The path previusly entered in the script file should be printed out. + +If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + +If you got here from section :ref:`get-started-setup-path-legacy`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-legacy`. + + +.. _add-idf_path-to-profile-linux-macos-legacy: + +Linux and MacOS +--------------- + +Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file:: + + export IDF_PATH=~/esp/esp-idf + +Log off and log in back to make this change effective. + +.. note:: + + If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. + +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. + +If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout:: + + export IDF_PATH=~/esp/esp-idf + +If you got here from section :ref:`get-started-setup-path-legacy`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-legacy`. diff --git a/docs/en/get-started-legacy/eclipse-setup.rst b/docs/en/get-started-legacy/eclipse-setup.rst new file mode 100644 index 000000000..087ef51e3 --- /dev/null +++ b/docs/en/get-started-legacy/eclipse-setup.rst @@ -0,0 +1,111 @@ +************************************************** +Build and Flash with Eclipse IDE (Legacy GNU Make) +************************************************** +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +.. _eclipse-install-steps-legacy: + +Installing Eclipse IDE +====================== + +The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects. + +* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux). + +* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse. + +* Download the Eclipse Installer for your platform from eclipse.org_. + +* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.) + +Setting up Eclipse +================== + +Once your new Eclipse installation launches, follow these steps: + +Import New Project +------------------ + +* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory. + +* Once Eclipse is running, choose File -> Import... + +* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next. + +* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile). + +* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish. + + +Project Properties +------------------ + +* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu. + +* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``. + +* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. Windows users can copy the ``IDF_PATH`` from windows explorer. + +* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. Windows users will need to prepend ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` to ``PATH`` environment variable (If you installed msys32 to a different directory then you’ll need to change these paths to match). + +* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python. + +**ADDITIONAL NOTE**: If either the IDF_PATH directory or the project directory is located outside ``C:\msys32\home`` directory, you will have to give custom build command in C/C++ Build properties as: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` (Please note that the build time may get significantly increased by this method.) + +Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page: + +* Click the "Providers" tab + +* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``. + +* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` + +Navigate to "C/C++ General" -> "Indexer" property page: + +* Check "Enable project specific settings" to enable the rest of the settings on this page. + +* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories. + +Navigate to "C/C++ Build" -> "Behavior" property page: + +* Check "Enable parallel build" to enable multiple build jobs in parallel. + +.. _eclipse-build-project-legacy: + +Building in Eclipse +------------------- + +Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project. + +* Click OK to close the Properties dialog in Eclipse. + +* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse. + +*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.* + +* Back in Eclipse, choose Project -> Build to build your project. + +**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths. + +Flash from Eclipse +------------------ + +You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI: + +* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.) + +* Select Build Targets -> Create... from the context menu. + +* Type "flash" as the target name. Leave the other options as their defaults. + +* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project. + +Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.) + +Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary. + + +.. _eclipse.org: https://www.eclipse.org/ + diff --git a/docs/en/get-started-cmake/establish-serial-connection.rst b/docs/en/get-started-legacy/establish-serial-connection.rst similarity index 84% rename from docs/en/get-started-cmake/establish-serial-connection.rst rename to docs/en/get-started-legacy/establish-serial-connection.rst index a02e04c88..83a4f933b 100644 --- a/docs/en/get-started-cmake/establish-serial-connection.rst +++ b/docs/en/get-started-legacy/establish-serial-connection.rst @@ -1,8 +1,9 @@ -Establish Serial Connection with ESP32 (CMake) -============================================== - +Establish Serial Connection with ESP32 (Legacy GNU Make) +======================================================== :link_to_translation:`zh_CN:[中文]` +.. include:: ../gnu-make-legacy.rst + This section provides guidance how to establish serial connection between ESP32 and PC. @@ -11,7 +12,7 @@ Connect ESP32 to PC Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. -Below are the links to drivers for ESP32 boards produced by Espressif: +Below are the links to drivers for ESP32 and other boards produced by Espressif: .. csv-table:: @@ -73,12 +74,8 @@ MacOS :: ls /dev/cu.* -.. note:: - MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI. - - -.. _linux-dialout-group-cmake: +.. _linux-dialout-group-legacy: Adding user to ``dialout`` on Linux ----------------------------------- @@ -141,7 +138,7 @@ Then open serial port in terminal and check, if you see any log printed out by E ... -If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. +If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. .. note:: @@ -149,8 +146,9 @@ If you can see readable log output, it means serial connection is working and yo .. note:: - Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal. + Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal. + +If you got here from section :ref:`get-started-connect-legacy` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure-legacy`. -If you got here from :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure-cmake`. .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/en/get-started-legacy/index.rst b/docs/en/get-started-legacy/index.rst new file mode 100644 index 000000000..bd3d000ce --- /dev/null +++ b/docs/en/get-started-legacy/index.rst @@ -0,0 +1,453 @@ +***************************** +Get Started (Legacy GNU Make) +***************************** + +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32. + +After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board. + +.. include:: /_build/inc/version-note.inc + +Introduction +============ + +ESP32 is a system on a chip that integrates the following features: + +* Wi-Fi (2.4 GHz band) +* Bluetooth 4.2 +* Dual high performance cores +* Ultra Low Power co-processor +* Several peripherals + +Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. + +Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. + +What You Need +============= + +Hardware: + +* An **ESP32** board +* **USB cable** - USB A / micro USB B +* **Computer** running Windows, Linux, or macOS + +Software: + +* **Toolchain** to build the **Application** for ESP32 +* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** +* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ + + +.. figure:: ../../_static/what-you-need.png + :align: center + :alt: Development of applications for ESP32 + :figclass: align-center + + Development of applications for ESP32 + + +Development Board Overviews +=========================== + +If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware. + +.. toctree:: + :maxdepth: 1 + + ESP32-DevKitC <../hw-reference/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + +.. _get-started-step-by-step-legacy: + +Installation Step by Step +========================= + +This is a detailed roadmap to walk you through the installation process. + +Setting up Development Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* :ref:`get-started-setup-toolchain-legacy` for :doc:`Windows `, :doc:`Linux ` or :doc:`MacOS ` +* :ref:`get-started-get-esp-idf-legacy` +* :ref:`get-started-setup-path-legacy` +* :ref:`get-started-get-packages-legacy` + +Creating Your First Project +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* :ref:`get-started-start-project-legacy` +* :ref:`get-started-connect-legacy` +* :ref:`get-started-configure-legacy` +* :ref:`get-started-build-and-flash-legacy` +* :ref:`get-started-monitor-legacy` + + +.. _get-started-setup-toolchain-legacy: + +Step 1. Set up the Toolchain +============================ + +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. + +.. toctree:: + :hidden: + + Windows + Linux + MacOS + ++-----------------------------+-------------------------+----------------------------------+ +| |windows-logo| | |linux-logo| | |macos-logo| | ++-----------------------------+-------------------------+----------------------------------+ +| `Windows `_ | `Linux `_ | `Mac OS `_ | ++-----------------------------+-------------------------+----------------------------------+ + +.. |windows-logo| image:: ../../_static/windows-logo.png + :target: ../get-started-legacy/windows-setup.html + +.. |linux-logo| image:: ../../_static/linux-logo.png + :target: ../get-started-legacy/linux-setup.html + +.. |macos-logo| image:: ../../_static/macos-logo.png + :target: ../get-started-legacy/macos-setup.html + +.. _Windows-legacy: ../get-started-legacy/windows-setup.html +.. _Linux-legacy: ../get-started-legacy/linux-setup.html +.. _Mac OS-legacy: ../get-started-legacy/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-legacy`. + + +.. _get-started-get-esp-idf-legacy: + +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 `_. + +To get a local copy of ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``. + +Open Terminal, and run the following commands: + +.. include:: /_build/inc/git-clone-bash.inc + +ESP-IDF will be downloaded into ``~/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 + + +.. _get-started-setup-path-legacy: + +Step 3. Set Environment Variables +================================= + +The toolchain uses the environment variable ``IDF_PATH`` to access the ESP-IDF directory. This variable should be set up on your computer, otherwise projects will not build. + +These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in Section :doc:`add-idf_path-to-profile`. + + +.. _get-started-get-packages-legacy: + +Step 4. Install the Required Python Packages +============================================ + +The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running:: + + python -m pip install --user -r $IDF_PATH/requirements.txt + +.. note:: + + 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.:: + + python2.7 -m pip install --user -r $IDF_PATH/requirements.txt + + +.. _get-started-start-project-legacy: + +Step 5. Start a Project +======================= + +Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. + +Copy :example:`get-started/hello_world` to the ``~/esp`` directory: + +Linux and MacOS +~~~~~~~~~~~~~~~ + +.. code-block:: bash + + cd ~/esp + cp -r $IDF_PATH/examples/get-started/hello_world . + +Windows +~~~~~~~ + +.. code-block:: batch + + cd %userprofile%\esp + xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world + +There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. + +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. + +.. _get-started-connect-legacy: + +Step 6. Connect Your Device +=========================== + +Now connect your ESP32 board to the computer and check under what serial port the board is visible. + +Serial ports have the following patterns in their names: + +- **Windows**: names like ``COM1`` +- **Linux**: starting with ``/dev/tty`` +- **macOS**: starting with ``/dev/cu.`` + +If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details. + +.. note:: + + Keep the port name handy as you will need it in the next steps. + + +.. _get-started-configure-legacy: + +Step 7. Configure +================= + +Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-legacy` and run the project configuration utility ``menuconfig``. + +Linux and MacOS +~~~~~~~~~~~~~~~ + +.. code-block:: bash + + cd ~/esp/hello_world + make menuconfig + +Windows +~~~~~~~ + +.. code-block:: batch + + cd %userprofile%\esp\hello_world + make menuconfig + +If the previous steps have been done correctly, the following menu appears: + +.. figure:: ../../_static/project-configuration.png + :align: center + :alt: Project configuration - Home window + :figclass: align-center + + Project configuration - Home window + +In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit ``menuconfig`` by selecting ``< Exit >``. + +To navigate and use ``menuconfig``, press the following keys: + +* Arrow keys for navigation +* ``Enter`` to go into a submenu +* ``Esc`` to go up one level or exit +* ``?`` to see a help screen. Enter key exits the help screen +* ``Space``, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``" +* ``?`` while highlighting a configuration item to display help about that item +* ``/`` to find configuration items + +.. note:: + + If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``. + +.. attention:: + + If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. + +.. _get-started-build-and-flash-legacy: + +Step 8. Build and Flash +======================= + +Build and flash the project by running:: + + make flash + +This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. After that, these binaries will be flashed onto your ESP32 board. + +If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up. + +.. highlight:: none + +:: + + esptool.py v2.0-beta2 + Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... + esptool.py v2.0-beta2 + Connecting........___ + Uploading stub... + Running stub... + Stub running... + Changing baud rate to 921600 + Changed. + Attaching SPI flash... + Configuring flash size... + Auto-detected Flash size: 4MB + Flash params set to 0x0220 + Compressed 11616 bytes to 6695... + Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... + Hash of data verified. + Compressed 408096 bytes to 171625... + Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... + Hash of data verified. + Compressed 3072 bytes to 82... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... + Hash of data verified. + + Leaving... + Hard resetting... + + +If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. + + +.. _get-started-monitor-legacy: + +Step 9. Monitor +=============== + +To check if "hello_world" is indeed running, type ``make monitor``. + +This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application:: + + $ make monitor + MONITOR + --- idf_monitor on /dev/ttyUSB0 115200 --- + --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- + ets Jun 8 2016 00:22:57 + + rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + ... + +After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application. + +.. code-block:: none + + ... + Hello world! + Restarting in 10 seconds... + I (211) cpu_start: Starting scheduler on APP CPU. + Restarting in 9 seconds... + Restarting in 8 seconds... + Restarting in 7 seconds... + +To exit IDF monitor use the shortcut ``Ctrl+]``. + +If IDF monitor fails shortly after the upload, or if instead of the messages above you see a random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. + +.. code-block:: none + + e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA + ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp + +If you have such a problem, do the following: + +1. Exit the monitor. +2. Go back to :ref:`menuconfig `. +3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. +4. After that, :ref:`build and flash ` the application again. + +.. note:: + + You can combine building, flashing and monitoring into one step by running:: + + make flash monitor + +See also :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. + +**That's all that you need to get started with ESP32!** + +Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications. + + +Environment Variables +===================== + +Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without the need to reconfigure them using** ``make menuconfig``. + ++-----------------+--------------------------------------------------------------+ +| Variables | Description & Usage | ++=================+==============================================================+ +| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. | +| | | +| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, | +| | ``make monitor ESPPORT=COM1`` | ++-----------------+--------------------------------------------------------------+ +| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. | +| | | +| | Example: ``make flash ESPBAUD=9600`` | ++-----------------+--------------------------------------------------------------+ +| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. | +| | | +| | Example: ``make monitor MONITORBAUD=9600`` | ++-----------------+--------------------------------------------------------------+ + +.. note:: + + You can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``). + All subsequent calls of ``make`` within the same terminal session will use + the exported value given that the variable is not simultaneously overridden. + + +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-legacy`. + +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 `. + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + add-idf_path-to-profile + establish-serial-connection + make-project + eclipse-setup + ../api-guides/tools/idf-monitor + toolchain-setup-scratch + +.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ +.. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/en/get-started-legacy/linux-setup-scratch.rst b/docs/en/get-started-legacy/linux-setup-scratch.rst new file mode 100644 index 000000000..476448a42 --- /dev/null +++ b/docs/en/get-started-legacy/linux-setup-scratch.rst @@ -0,0 +1,77 @@ +**************************************************** +Setup Linux Toolchain from Scratch (Legacy GNU Make) +**************************************************** +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +.. note:: + + Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. + +Install Prerequisites +===================== + +To compile with ESP-IDF you need to get the following packages: + +- Ubuntu and Debian:: + + sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + +.. note:: + + Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF. + In this case please install a supported version via ``pip`` as it is described in section + :ref:`get-started-get-packages-legacy`. + +Compile the Toolchain from Source +================================= + +- Install dependencies: + + - CentOS 7:: + + sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool + + - Ubuntu pre-16.04:: + + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool + + - Ubuntu 16.04 or newer:: + + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin + + - Debian 9:: + + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin + + - Arch:: + + TODO + +Create the working directory and go into it:: + + mkdir -p ~/esp + cd ~/esp + +Download ``crosstool-NG`` and build it: + +.. include:: /_build/inc/scratch-build-code.inc + +Build the toolchain:: + + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf + +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`. diff --git a/docs/en/get-started-legacy/linux-setup.rst b/docs/en/get-started-legacy/linux-setup.rst new file mode 100644 index 000000000..6eb9c2057 --- /dev/null +++ b/docs/en/get-started-legacy/linux-setup.rst @@ -0,0 +1,120 @@ +******************************************************* +Standard Setup of Toolchain for Linux (Legacy GNU Make) +******************************************************* +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +Install Prerequisites +===================== + +To compile with ESP-IDF you need to get the following packages: + +- CentOS 7:: + + sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography + +- Ubuntu and Debian:: + + sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + +.. note:: + + Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages-legacy`. + +Toolchain Setup +=============== + +.. 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-legacy: + +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. In CentOS, ``alias`` should set in ``.bashrc``. + +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 +------------------------------ + +With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group`. + + +Arch Linux Users +---------------- + +To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. + +Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: + +- https://aur.archlinux.org/packages/ncurses5-compat-libs/ +- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ + +Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above. + +Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + linux-setup-scratch + + +.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/en/get-started-legacy/macos-setup-scratch.rst b/docs/en/get-started-legacy/macos-setup-scratch.rst new file mode 100644 index 000000000..f96ab3bcd --- /dev/null +++ b/docs/en/get-started-legacy/macos-setup-scratch.rst @@ -0,0 +1,74 @@ +********************************************************* +Setup Toolchain for Mac OS from Scratch (Legacy GNU Make) +********************************************************* +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +.. note:: + + Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. + +Install Prerequisites +===================== + +- install pip:: + + sudo easy_install pip + +.. note:: + + ``pip`` will be used later for installing :ref:`the required Python packages `. + +Compile the Toolchain from Source +================================= + +- Install dependencies: + + - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. + + .. _homebrew: https://brew.sh/ + .. _MacPorts: https://www.macports.org/install.php + + - with MacPorts:: + + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake + + - with homebrew:: + + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake + +Create a case-sensitive filesystem image:: + + hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" + +Mount it:: + + hdiutil mount ~/esp/crosstool.dmg + +Create a symlink to your work directory:: + + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume + +Go into the newly created directory:: + + cd ~/esp/ctng-volume + +Download ``crosstool-NG`` and build it: + +.. include:: /_build/inc/scratch-build-code.inc + +Build the toolchain:: + + ./ct-ng xtensa-esp32-elf + ./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 ` to add the toolchain to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`. diff --git a/docs/en/get-started-legacy/macos-setup.rst b/docs/en/get-started-legacy/macos-setup.rst new file mode 100644 index 000000000..555cdda05 --- /dev/null +++ b/docs/en/get-started-legacy/macos-setup.rst @@ -0,0 +1,59 @@ +******************************************************** +Standard Setup of Toolchain for Mac OS (Legacy GNU Make) +******************************************************** +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +Install Prerequisites +===================== + +- install pip:: + + sudo easy_install pip + +.. note:: + + ``pip`` will be used later for installing :ref:`the required Python packages `. + +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-legacy: + +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``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + macos-setup-scratch diff --git a/docs/en/get-started/make-project.rst b/docs/en/get-started-legacy/make-project.rst similarity index 95% rename from docs/en/get-started/make-project.rst rename to docs/en/get-started-legacy/make-project.rst index 8f27c8927..4a0e69680 100644 --- a/docs/en/get-started/make-project.rst +++ b/docs/en/get-started-legacy/make-project.rst @@ -1,7 +1,9 @@ -Build and Flash with Make -========================= +Build and Flash with Make (Legacy GNU Make) +=========================================== :link_to_translation:`zh_CN:[中文]` +.. include:: ../gnu-make-legacy.rst + Finding a project ----------------- diff --git a/docs/en/get-started-cmake/toolchain-setup-scratch.rst b/docs/en/get-started-legacy/toolchain-setup-scratch.rst similarity index 70% rename from docs/en/get-started-cmake/toolchain-setup-scratch.rst rename to docs/en/get-started-legacy/toolchain-setup-scratch.rst index c7b0ee32d..a19181431 100644 --- a/docs/en/get-started-cmake/toolchain-setup-scratch.rst +++ b/docs/en/get-started-legacy/toolchain-setup-scratch.rst @@ -1,12 +1,12 @@ -.. _get-started-customized-setup-cmake: +.. _get-started-customized-setup-legacy: -************************************* -Customized Setup of Toolchain (CMake) -************************************* +*********************************************** +Customized Setup of Toolchain (Legacy GNU Make) +*********************************************** -:link_to_translation:`zh_CN:[中文]` +Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain-legacy`) 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. +.. include:: ../gnu-make-legacy.rst 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: diff --git a/docs/en/get-started-legacy/windows-setup-scratch.rst b/docs/en/get-started-legacy/windows-setup-scratch.rst new file mode 100644 index 000000000..6f2a291e9 --- /dev/null +++ b/docs/en/get-started-legacy/windows-setup-scratch.rst @@ -0,0 +1,119 @@ +****************************************************** +Setup Windows Toolchain from Scratch (Legacy GNU Make) +****************************************************** + +.. include:: ../gnu-make-legacy.rst + +Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment `, addressed to less experienced users, has been prepared by following these steps. + +To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`. + + +.. _configure-windows-toolchain-from-scratch-legacy: + +Configure Toolchain & Environment from Scratch +============================================== + +This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain. + +* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``. + +* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.** + +* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal. + + *(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)* + +* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer. + +* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does. + +* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain. + + +Troubleshooting +~~~~~~~~~~~~~~~ + +* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following:: + + *** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL. + + If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step. + +* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_. + + +MSYS2 Mirrors in China +~~~~~~~~~~~~~~~~~~~~~~ + +There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China. + +To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``). + +Add these lines at the top of ``mirrorlist.mingw32``:: + + Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/ + Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686 + +Add these lines at the top of ``mirrorlist.msys``:: + + Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch + Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch + + +HTTP Proxy +~~~~~~~~~~ + +You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script:: + + export http_proxy='http://http.proxy.server:PORT' + +Or with credentials:: + + export http_proxy='http://user:password@http.proxy.server:PORT' + +Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS. + + +Alternative Setup: Just download a toolchain +============================================ + +.. include:: /_build/inc/download-links.inc + +If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: + +|download_link_win32| + +.. note:: + + If you followed instructions :ref:`configure-windows-toolchain-from-scratch-legacy`, you already have the toolchain and you won't need this download. + +.. important:: + + Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support). + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`. + +.. _updating-existing-windows-environment-legacy: + +Updating The Environment +======================== + +When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment. + +Rather than setting up a new environment, you can update an existing Windows environment & toolchain: + +- Update IDF to the new version you want to use. +- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version. + +The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_. + +If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default. + +.. _MSYS2: https://msys2.github.io/ +.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/ +.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new diff --git a/docs/en/get-started-legacy/windows-setup.rst b/docs/en/get-started-legacy/windows-setup.rst new file mode 100644 index 000000000..79597ad39 --- /dev/null +++ b/docs/en/get-started-legacy/windows-setup.rst @@ -0,0 +1,72 @@ +********************************************************* +Standard Setup of Toolchain for Windows (Legacy GNU Make) +********************************************************* +:link_to_translation:`zh_CN:[中文]` + +.. include:: ../gnu-make-legacy.rst + +Introduction +============ + +Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse ` or some other front-end), but it runs behind the scenes. + + +Toolchain Setup +=============== + +The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com: + +https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip + +Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment. + + +Check it Out +============ + +Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command:: + + mkdir -p ~/esp + +By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step. + +.. figure:: ../../_static/msys2-terminal-window.png + :align: center + :alt: MSYS2 MINGW32 shell window + :figclass: align-center + + MSYS2 MINGW32 shell window + +Use this window in the following steps setting up development environment for ESP32. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-legacy`. + +Updating The Environment +======================== + +When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one: + +- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``). +- Download the new precompiled environment using the steps above. +- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location). +- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``. +- You can now delete the ``C:\msys32_old`` directory if you no longer need it. + +You can have independent different MSYS2 environments on your system, as long as they are in different directories. + +There are :ref:`also steps to update the existing environment without downloading a new one `, although this is more complex. + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + + +.. _MSYS2: https://msys2.github.io/ diff --git a/docs/en/get-started/add-idf_path-to-profile.rst b/docs/en/get-started/add-idf_path-to-profile.rst index 8ce9a9ae6..9d4fa4ff4 100644 --- a/docs/en/get-started/add-idf_path-to-profile.rst +++ b/docs/en/get-started/add-idf_path-to-profile.rst @@ -1,65 +1,3 @@ -Add IDF_PATH to User Profile -============================ -:link_to_translation:`zh_CN:[中文]` +:orphan: -To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below. - - -.. _add-idf_path-to-profile-windows: - -Windows -------- - -The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window. - -#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``. - -#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf`` - -#. Add the ``export`` command to the script file, e.g.:: - - export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" - - Remember to replace back-slashes with forward-slashes in the original Windows path. - -#. Save the script file. - -#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing:: - - printenv IDF_PATH - - The path previusly entered in the script file should be printed out. - -If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window:: - - export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" - -If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. - - -.. _add-idf_path-to-profile-linux-macos: - -Linux and MacOS ---------------- - -Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file:: - - export IDF_PATH=~/esp/esp-idf - -Log off and log in back to make this change effective. - -.. note:: - - If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. - -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. - -If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout:: - - export IDF_PATH=~/esp/esp-idf - -If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. +.. Remove this file when the Chinese translation of getting started guide is updated diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst index d03494ddd..08b46fcf6 100644 --- a/docs/en/get-started/eclipse-setup.rst +++ b/docs/en/get-started/eclipse-setup.rst @@ -3,107 +3,10 @@ Build and Flash with Eclipse IDE ******************************** :link_to_translation:`zh_CN:[中文]` -.. _eclipse-install-steps: +ESP-IDF V4.0 will be released with a new CMake-based build system as the default build system. -Installing Eclipse IDE -====================== +Eclipse CDT IDE support for CMake-based build system will be available before the ESP-IDF V4.0 release but +is not available yet. We apologise for the inconvenience. -The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects. - -* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux). - -* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse. - -* Download the Eclipse Installer for your platform from eclipse.org_. - -* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.) - -Setting up Eclipse -================== - -Once your new Eclipse installation launches, follow these steps: - -Import New Project ------------------- - -* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory. - -* Once Eclipse is running, choose File -> Import... - -* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next. - -* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile). - -* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish. - - -Project Properties ------------------- - -* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu. - -* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``. - -* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. Windows users can copy the ``IDF_PATH`` from windows explorer. - -* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. Windows users will need to prepend ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` to ``PATH`` environment variable (If you installed msys32 to a different directory then you’ll need to change these paths to match). - -* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python. - -**ADDITIONAL NOTE**: If either the IDF_PATH directory or the project directory is located outside ``C:\msys32\home`` directory, you will have to give custom build command in C/C++ Build properties as: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` (Please note that the build time may get significantly increased by this method.) - -Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page: - -* Click the "Providers" tab - -* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``. - -* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` - -Navigate to "C/C++ General" -> "Indexer" property page: - -* Check "Enable project specific settings" to enable the rest of the settings on this page. - -* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories. - -Navigate to "C/C++ Build" -> "Behavior" property page: - -* Check "Enable parallel build" to enable multiple build jobs in parallel. - -.. _eclipse-build-project: - -Building in Eclipse -------------------- - -Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project. - -* Click OK to close the Properties dialog in Eclipse. - -* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse. - -*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.* - -* Back in Eclipse, choose Project -> Build to build your project. - -**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths. - -Flash from Eclipse ------------------- - -You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI: - -* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.) - -* Select Build Targets -> Create... from the context menu. - -* Type "flash" as the target name. Leave the other options as their defaults. - -* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project. - -Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.) - -Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary. - - -.. _eclipse.org: https://www.eclipse.org/ +If you require Eclipse IDE support for this pre-release version of ESP-IDF, you can follow the :doc:`legacy GNU Make build system Getting Started guide ` which has steps for :doc:`Building and Flashing with Eclipse IDE `. diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst index 7e0e3a91e..2b1568264 100644 --- a/docs/en/get-started/establish-serial-connection.rst +++ b/docs/en/get-started/establish-serial-connection.rst @@ -1,5 +1,6 @@ Establish Serial Connection with ESP32 -====================================== +============================================== + :link_to_translation:`zh_CN:[中文]` This section provides guidance how to establish serial connection between ESP32 and PC. @@ -10,7 +11,7 @@ Connect ESP32 to PC Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. -Below are the links to drivers for ESP32 and other boards produced by Espressif: +Below are the links to drivers for ESP32 boards produced by Espressif: .. csv-table:: @@ -72,6 +73,10 @@ MacOS :: ls /dev/cu.* +.. note:: + + MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI. + .. _linux-dialout-group: @@ -136,7 +141,7 @@ Then open serial port in terminal and check, if you see any log printed out by E ... -If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. +If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. .. note:: @@ -144,9 +149,8 @@ If you see some legible log, it means serial connection is working and you are r .. note:: - Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal. - -If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`. + Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal. +If you got here from :ref:`get-started-connect` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure`. .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index ffcc6f079..51b87fa32 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -1,12 +1,12 @@ -*********** +*********** Get Started *********** :link_to_translation:`zh_CN:[中文]` -This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32. +This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif. -After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board. +After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board. .. include:: /_build/inc/version-note.inc @@ -36,7 +36,8 @@ Hardware: Software: -* **Toolchain** to build the **Application** for ESP32 +* **Toolchain** to compile code for ESP32 +* **Build tools** - CMake and Ninja to build a full **Application** for ESP32 * **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** * **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ @@ -61,7 +62,7 @@ If you have one of ESP32 development boards listed below, you can click on the l ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> - + .. _get-started-step-by-step: @@ -73,10 +74,10 @@ This is a detailed roadmap to walk you through the installation process. Setting up Development Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* :ref:`get-started-setup-toolchain` for :doc:`Windows `, :doc:`Linux ` or :doc:`MacOS ` +* :ref:`get-started-get-prerequisites` for :doc:`Windows `, :doc:`Linux ` or :doc:`macOS ` * :ref:`get-started-get-esp-idf` -* :ref:`get-started-setup-path` -* :ref:`get-started-get-packages` +* :ref:`get-started-set-up-tools` +* :ref:`get-started-set-up-env` Creating Your First Project ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -84,25 +85,24 @@ Creating Your First Project * :ref:`get-started-start-project` * :ref:`get-started-connect` * :ref:`get-started-configure` -* :ref:`get-started-build-and-flash` -* :ref:`get-started-monitor` +* :ref:`get-started-build` +* :ref:`get-started-flash` +* :ref:`get-started-build-monitor` -.. _get-started-setup-toolchain: +.. _get-started-get-prerequisites: -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 - Linux - MacOS + Linux + macOS +-------------------+-------------------+-------------------+ | |windows-logo| | |linux-logo| | |macos-logo| | @@ -123,21 +123,21 @@ The quickest way to start development with ESP32 is by installing a prebuilt too .. _Linux: ../get-started/linux-setup.html .. _Mac OS: ../get-started/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`. - - .. _get-started-get-esp-idf: 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 `_. +To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository `_. -To get a local copy of ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``. +To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``, following instructions below specific to your operating system. + +.. 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: @@ -147,43 +147,79 @@ ESP-IDF will be downloaded into ``~/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 +Windows +~~~~~~~ -.. note:: +In addition to installing the tools, :ref:`get-started-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF. - Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: +Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. - cd esp-idf - git submodule update --init +If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions `. +.. _get-started-set-up-tools: -.. _get-started-setup-path: +Step 3. Set up the tools +======================== -Step 3. Set Environment Variables -================================= +Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc. -The toolchain uses the environment variable ``IDF_PATH`` to access the ESP-IDF directory. This variable should be set up on your computer, otherwise projects will not build. +Windows +~~~~~~~ -These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in Section :doc:`add-idf_path-to-profile`. +:ref:`get-started-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools. +If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps: -.. _get-started-get-packages: +.. code-block:: batch -Step 4. Install the Required Python Packages -============================================ + cd %userprofile%\esp\esp-idf + install.bat -The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running:: +Linux and macOS +~~~~~~~~~~~~~~~ - python -m pip install --user -r $IDF_PATH/requirements.txt +.. code-block:: bash -.. note:: + cd ~/esp/esp-idf + ./install.sh - 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.:: +Customizing the tools installation path +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - python2.7 -m pip install --user -r $IDF_PATH/requirements.txt +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. +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. + +.. _get-started-set-up-env: + +Step 4. Set up the environment variables +======================================== + +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-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: @@ -192,9 +228,9 @@ Step 5. Start a Project Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. -Copy :example:`get-started/hello_world` to the ``~/esp`` directory: +Copy :example:`get-started/hello_world` to ``~/esp`` directory: -Linux and MacOS +Linux and macOS ~~~~~~~~~~~~~~~ .. code-block:: bash @@ -216,7 +252,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: @@ -245,13 +281,15 @@ Step 7. Configure Navigate to your ``hello_world`` directory from :ref:`get-started-start-project` and run the project configuration utility ``menuconfig``. -Linux and MacOS +Linux and macOS ~~~~~~~~~~~~~~~ .. code-block:: bash cd ~/esp/hello_world - make menuconfig + idf.py menuconfig + +If your default version of Python is 3.x, you may need to run ``python2 $(which idf.py) menuconfig`` instead. Windows ~~~~~~~ @@ -259,7 +297,7 @@ Windows .. code-block:: batch cd %userprofile%\esp\hello_world - make menuconfig + idf.py menuconfig If the previous steps have been done correctly, the following menu appears: @@ -270,8 +308,6 @@ If the previous steps have been done correctly, the following menu appears: Project configuration - Home window -In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit ``menuconfig`` by selecting ``< Exit >``. - To navigate and use ``menuconfig``, press the following keys: * Arrow keys for navigation @@ -282,72 +318,111 @@ To navigate and use ``menuconfig``, press the following keys: * ``?`` while highlighting a configuration item to display help about that item * ``/`` to find configuration items -.. note:: - - If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``. - .. attention:: If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. -.. _get-started-build-and-flash: +.. _get-started-build: -Step 8. Build and Flash -======================= +Step 8. Build the Project +========================= -Build and flash the project by running:: +Build the project by running:: - make flash + idf.py build -This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. After that, these binaries will be flashed onto your ESP32 board. +This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. -If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up. +.. code-block:: none -.. highlight:: none + $ idf.py build + Running cmake in directory /path/to/hello_world/build + Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... + Warn about uninitialized values. + -- Found Git: /usr/bin/git (found version "2.17.0") + -- Building empty aws_iot component due to configuration + -- Component names: ... + -- Component paths: ... + + ... (more lines of build system output) + + [527/527] Generating hello-world.bin + esptool.py v2.3.1 + + Project build complete. To flash, run this command: + ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin + or run 'idf.py -p PORT flash' -:: +If there are no errors, the build will finish by generating the firmware binary .bin file. - esptool.py v2.0-beta2 - Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... - esptool.py v2.0-beta2 - Connecting........___ + +.. _get-started-flash: + +Step 9. Flash onto the Device +============================= + +Flash the binaries that you just built onto your ESP32 board by running:: + + idf.py -p PORT [-b BAUD] flash + +Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect`. + +You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``. + +For more information on idf.py arguments, see :ref:`idf.py`. + +.. note:: + + The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary. + +.. code-block:: none + + Running esptool.py in directory [...]/esp/hello_world + Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"... + esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin + esptool.py v2.3.1 + Connecting.... + Detecting chip type... ESP32 + Chip is ESP32D0WDQ6 (revision 1) + Features: WiFi, BT, Dual Core Uploading stub... Running stub... Stub running... - Changing baud rate to 921600 + Changing baud rate to 460800 Changed. - Attaching SPI flash... Configuring flash size... Auto-detected Flash size: 4MB Flash params set to 0x0220 - Compressed 11616 bytes to 6695... - Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... - Hash of data verified. - Compressed 408096 bytes to 171625... - Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... + Compressed 22992 bytes to 13019... + Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)... Hash of data verified. Compressed 3072 bytes to 82... - Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)... Hash of data verified. - + Compressed 136672 bytes to 67544... + Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... + Hash of data verified. + Leaving... - Hard resetting... + Hard resetting via RTS pin... + +If there are no issues by the end of the flash process, the module will be reset and the “hello_world” application will be running. + +.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide `. -If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. +.. _get-started-build-monitor: +Step 10. Monitor +================ -.. _get-started-monitor: - -Step 9. Monitor -=============== - -To check if "hello_world" is indeed running, type ``make monitor``. +To check if "hello_world" is indeed running, type ``idf.py -p PORT monitor`` (Do not forget to replace PORT with your serial port name). This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application:: - $ make monitor - MONITOR + $ idf.py -p /dev/ttyUSB0 monitor + Running idf_monitor in directory [...]/esp/hello_world/build + Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"... --- idf_monitor on /dev/ttyUSB0 115200 --- --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- ets Jun 8 2016 00:22:57 @@ -370,7 +445,7 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print To exit IDF monitor use the shortcut ``Ctrl+]``. -If IDF monitor fails shortly after the upload, or if instead of the messages above you see a random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. +If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. .. code-block:: none @@ -382,71 +457,45 @@ If you have such a problem, do the following: 1. Exit the monitor. 2. Go back to :ref:`menuconfig `. 3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. -4. After that, :ref:`build and flash ` the application again. +4. After that, :ref:`build and flash ` the application again. .. note:: You can combine building, flashing and monitoring into one step by running:: - make flash monitor + idf.py -p PORT flash monitor -See also :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. +See also: + +- :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. +- :ref:`idf.py` for a full reference of ``idf.py`` commands and options. **That's all that you need to get started with ESP32!** Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications. - -Environment Variables -===================== - -Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without the need to reconfigure them using** ``make menuconfig``. - -+-----------------+--------------------------------------------------------------+ -| Variables | Description & Usage | -+=================+==============================================================+ -| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. | -| | | -| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, | -| | ``make monitor ESPPORT=COM1`` | -+-----------------+--------------------------------------------------------------+ -| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. | -| | | -| | Example: ``make flash ESPBAUD=9600`` | -+-----------------+--------------------------------------------------------------+ -| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. | -| | | -| | Example: ``make monitor MONITORBAUD=9600`` | -+-----------------+--------------------------------------------------------------+ - -.. note:: - - You can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``). - All subsequent calls of ``make`` within the same terminal session will use - the exported value given that the variable is not simultaneously overridden. - - 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`. -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 `. +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`. + +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`. + Related Documents ================= .. toctree:: :maxdepth: 1 - add-idf_path-to-profile establish-serial-connection - make-project eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch + ../get-started-legacy/index .. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ .. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst index 395458153..a96992c06 100644 --- a/docs/en/get-started/linux-setup-scratch.rst +++ b/docs/en/get-started/linux-setup-scratch.rst @@ -1,30 +1,30 @@ -********************************** +****************************************** Setup Linux Toolchain from Scratch -********************************** +****************************************** + :link_to_translation:`zh_CN:[中文]` -.. note:: - - Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. +The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`. Install Prerequisites ===================== To compile with ESP-IDF you need to get the following packages: +- CentOS 7:: + + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache + - Ubuntu and Debian:: - sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache .. note:: - - Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF. - In this case please install a supported version via ``pip`` as it is described in section - :ref:`get-started-get-packages`. + 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". Compile the Toolchain from Source ================================= @@ -33,19 +33,19 @@ Compile the Toolchain from Source - CentOS 7:: - sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool + sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make - Ubuntu pre-16.04:: - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make - Ubuntu 16.04 or newer:: - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make - Debian 9:: - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make - Arch:: @@ -66,10 +66,10 @@ 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 :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow `instructions for standard setup `_ to add the toolchain to your ``PATH``. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`. diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst index 7484b4c62..a9afdfc20 100644 --- a/docs/en/get-started/linux-setup.rst +++ b/docs/en/get-started/linux-setup.rst @@ -1,6 +1,7 @@ -************************************* +********************************************* Standard Setup of Toolchain for Linux -************************************* +********************************************* + :link_to_translation:`zh_CN:[中文]` Install Prerequisites @@ -10,75 +11,22 @@ To compile with ESP-IDF you need to get the following packages: - CentOS 7:: - sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - Ubuntu and Debian:: - sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache .. 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". - Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`. - -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: - -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. In CentOS, ``alias`` should set in ``.bashrc``. - -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 ------------------------------ @@ -88,7 +36,7 @@ With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0 Arch Linux Users ---------------- -To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. +To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: @@ -103,7 +51,7 @@ Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`. Related Documents diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index a4dfe9d7f..faaeda54d 100644 --- a/docs/en/get-started/macos-setup-scratch.rst +++ b/docs/en/get-started/macos-setup-scratch.rst @@ -1,11 +1,20 @@ -*************************************** +*********************************************** Setup Toolchain for Mac OS from Scratch -*************************************** +*********************************************** + :link_to_translation:`zh_CN:[中文]` -.. note:: - - Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. +Package Manager +=============== + +To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain`, you will need to install either the MacPorts_ or homebrew_ package manager. + +MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. + + .. _homebrew: https://brew.sh/ + .. _MacPorts: https://www.macports.org/install.php + +See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. Install Prerequisites ===================== @@ -14,27 +23,32 @@ Install Prerequisites sudo easy_install pip -.. note:: +- install pyserial:: - ``pip`` will be used later for installing :ref:`the required Python packages `. + pip install --user pyserial + +- install CMake & Ninja build: + + - If you have HomeBrew, you can run:: + + brew install cmake ninja + + - If you have MacPorts, you can run:: + + sudo port install cmake ninja Compile the Toolchain from Source ================================= - Install dependencies: - - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. - - .. _homebrew: https://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php - - with MacPorts:: - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - with homebrew:: - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make Create a case-sensitive filesystem image:: @@ -63,10 +77,10 @@ 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 ` 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 ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`. diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst index 7e1921a6c..caede42ec 100644 --- a/docs/en/get-started/macos-setup.rst +++ b/docs/en/get-started/macos-setup.rst @@ -1,52 +1,47 @@ -************************************** +********************************************** Standard Setup of Toolchain for Mac OS -************************************** +********************************************** + :link_to_translation:`zh_CN:[中文]` Install Prerequisites ===================== +ESP-IDF will use the version of Python installed by default on macOS. + - install pip:: sudo easy_install pip +- install pyserial:: + + pip install --user pyserial + +- install CMake & Ninja build: + + - If you have HomeBrew_, you can run:: + + brew install cmake ninja + + - If you have MacPorts_, you can run:: + + sudo port install cmake ninja + + - 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_. + .. note:: + If an error like this is shown during any step:: - ``pip`` will be used later for installing :ref:`the required Python packages `. - -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: - -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``. + 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``. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. - +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`. Related Documents ================= @@ -55,3 +50,9 @@ Related Documents :maxdepth: 1 macos-setup-scratch + +.. _cmake: https://cmake.org/ +.. _ninja: https://ninja-build.org/ +.. _ccache: https://ccache.samba.org/ +.. _homebrew: https://brew.sh/ +.. _MacPorts: https://www.macports.org/install.php diff --git a/docs/en/get-started/toolchain-setup-scratch.rst b/docs/en/get-started/toolchain-setup-scratch.rst index c5f2b5ae4..e65233f68 100644 --- a/docs/en/get-started/toolchain-setup-scratch.rst +++ b/docs/en/get-started/toolchain-setup-scratch.rst @@ -1,10 +1,12 @@ .. _get-started-customized-setup: -***************************** +************************************* Customized Setup of Toolchain -***************************** +************************************* -Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain`) you may build the toolchain yourself. +:link_to_translation:`zh_CN:[中文]` + +Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-set-up-tools`) 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: diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst index fc64e2a23..d0bef754d 100644 --- a/docs/en/get-started/windows-setup-scratch.rst +++ b/docs/en/get-started/windows-setup-scratch.rst @@ -1,117 +1,120 @@ -************************************ +******************************************** Setup Windows Toolchain from Scratch -************************************ +******************************************** -Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment `, addressed to less experienced users, has been prepared by following these steps. +:link_to_translation:`zh_CN:[中文]` -To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`. +This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer ` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install. +To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`. -.. _configure-windows-toolchain-from-scratch: +.. 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. -Configure Toolchain & Environment from Scratch -============================================== +.. _get-esp-idf-windows-command-line: -This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain. - -* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``. - -* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.** - -* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal. - - *(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)* - -* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer. - -* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does. - -* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain. - - -Troubleshooting -~~~~~~~~~~~~~~~ - -* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following:: - - *** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL. - - If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step. - -* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_. - - -MSYS2 Mirrors in China -~~~~~~~~~~~~~~~~~~~~~~ - -There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China. - -To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``). - -Add these lines at the top of ``mirrorlist.mingw32``:: - - Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/ - Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686 - -Add these lines at the top of ``mirrorlist.msys``:: - - Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch - Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch - - -HTTP Proxy -~~~~~~~~~~ - -You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script:: - - export http_proxy='http://http.proxy.server:PORT' - -Or with credentials:: - - export http_proxy='http://user:password@http.proxy.server:PORT' - -Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS. - - -Alternative Setup: Just download a toolchain -============================================ - -.. include:: /_build/inc/download-links.inc - -If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: - -|download_link_win32| +Get ESP-IDF +=========== .. note:: - If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download. + 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. -.. important:: + If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below. - Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support). +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 +===== + +cmake +^^^^^ + +Download the latest stable release of CMake_ for Windows and run the installer. + +When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user". + +Ninja build +^^^^^^^^^^^ + +.. note:: + Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented. + +Download the ninja_ latest stable Windows release from the (`download page `_). + +The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path `_ (or you can choose a directory which is already on your Path). + + +Python 2.x +^^^^^^^^^^ + +Download the latest Python_ 2.7 for Windows installer, and run it. + +The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed". + +Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command:: + + pip install --user pyserial + +MConf for IDF +^^^^^^^^^^^^^ + +Download the configuration tool mconf-idf from the `kconfig-frontends releases page `_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF. + +This tool will also need to be unzipped to a directory which is then `added to your Path `_. + +Toolchain Setup +=============== + +.. include:: /_build/inc/download-links.inc + +Download the precompiled Windows toolchain: + +|download_link_win32| + +Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``. + +Next, the ``bin`` subdirectory of this directory must be `added to your Path `_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``. + +.. note:: + If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. + + +.. _add-directory-windows-path: + +Adding Directory to Path +======================== + +To add any new directory to your Windows Path environment variable: + +Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings). + +Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;``. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. - -.. _updating-existing-windows-environment: - -Updating The Environment -======================== - -When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment. - -Rather than setting up a new environment, you can update an existing Windows environment & toolchain: - -- Update IDF to the new version you want to use. -- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version. - -The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_. - -If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`. +.. _ninja: https://ninja-build.org/ +.. _Python: https://www.python.org/downloads/windows/ .. _MSYS2: https://msys2.github.io/ -.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/ -.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new +.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ + diff --git a/docs/en/get-started-cmake/windows-setup-update.rst b/docs/en/get-started/windows-setup-update.rst similarity index 94% rename from docs/en/get-started-cmake/windows-setup-update.rst rename to docs/en/get-started/windows-setup-update.rst index 1a8e4fb54..a1206354d 100644 --- a/docs/en/get-started-cmake/windows-setup-update.rst +++ b/docs/en/get-started/windows-setup-update.rst @@ -2,7 +2,7 @@ Updating ESP-IDF tools on Windows ********************************* -.. _get-started-cmake-install_bat-windows: +.. _get-started-install_bat-windows: Install ESP-IDF tools using ``install.bat`` =========================================== @@ -14,7 +14,7 @@ From the Windows Command Prompt, change to the directory where ESP-IDF is instal 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: +.. _get-started-export_bat-windows: Add ESP-IDF tools to PATH using ``export.bat`` ============================================== diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index d2a267828..9dccad8dc 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -1,70 +1,68 @@ -*************************************** +*********************************************** Standard Setup of Toolchain for Windows -*************************************** +*********************************************** + :link_to_translation:`zh_CN:[中文]` +.. 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>`. + Introduction ============ -Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse ` or some other front-end), but it runs behind the scenes. +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 the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse ` or another graphical IDE with CMake support instead. -Toolchain Setup -=============== +.. 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. -The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com: +.. _get-started-windows-tools-installer: -https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip +ESP-IDF Tools Installer +======================= -Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment. +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-2.0.exe -Check it Out -============ +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. -Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command:: +The installer also offers to download one of the ESP-IDF release versions. - mkdir -p ~/esp +Using the Command Prompt +======================== -By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step. +For the remaining Getting Started steps, we're going to use the Windows Command Prompt. -.. figure:: ../../_static/msys2-terminal-window.png - :align: center - :alt: MSYS2 MINGW32 shell window - :figclass: align-center +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. - MSYS2 MINGW32 shell window +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: -Use this window in the following steps setting up development environment for ESP32. +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. +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 section :ref:`get-started-get-esp-idf`. - -Updating The Environment -======================== - -When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one: - -- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``). -- Download the new precompiled environment using the steps above. -- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location). -- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``. -- You can now delete the ``C:\msys32_old`` directory if you no longer need it. - -You can have independent different MSYS2 environments on your system, as long as they are in different directories. - -There are :ref:`also steps to update the existing environment without downloading a new one `, although this is more complex. +If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project`. Related Documents ================= +For advanced users who want to customize the install process: + .. toctree:: :maxdepth: 1 windows-setup-scratch - + windows-setup-update .. _MSYS2: https://msys2.github.io/ +.. _cmake: https://cmake.org/download/ +.. _ninja: https://ninja-build.org/ +.. _Python: https://www.python.org/downloads/windows/ +.. _Git for Windows: https://gitforwindows.org/ +.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/ +.. _Github Desktop: https://desktop.github.com/ diff --git a/docs/en/gnu-make-legacy.rst b/docs/en/gnu-make-legacy.rst new file mode 100644 index 000000000..5257c87b8 --- /dev/null +++ b/docs/en/gnu-make-legacy.rst @@ -0,0 +1 @@ +.. note:: Since ESP-IDF V4.0, the default build system is based on CMake. This documentation is for the legacy build system based on GNU Make. Support for this build system may be removed in future major releases. diff --git a/docs/en/hw-reference/get-started-devkitc-v2.rst b/docs/en/hw-reference/get-started-devkitc-v2.rst index 2b558f6e9..bef33a278 100644 --- a/docs/en/hw-reference/get-started-devkitc-v2.rst +++ b/docs/en/hw-reference/get-started-devkitc-v2.rst @@ -9,7 +9,7 @@ This guide shows how to start using the ESP32-DevKitC V2 development board. What You Need ------------- -* :ref:`ESP32-DevKitC V2 board ` +* ESP32-DevKitC V2 board * USB A / micro USB B cable * Computer running Windows, Linux, or macOS @@ -27,7 +27,7 @@ Functional Description The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitC V2 board. -.. _get-started-esp32-devkitc-v2-board-front-cmake: +.. _get-started-esp32-devkitc-v2-board-front-make: .. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png :align: center @@ -71,9 +71,7 @@ Start Application Development Before powering up your ESP32-DevKitC V2, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents diff --git a/docs/en/hw-reference/get-started-devkitc.rst b/docs/en/hw-reference/get-started-devkitc.rst index d15807dbc..3d1064025 100644 --- a/docs/en/hw-reference/get-started-devkitc.rst +++ b/docs/en/hw-reference/get-started-devkitc.rst @@ -1,5 +1,5 @@ ESP32-DevKitC V4 Getting Started Guide -============================================== +====================================== :link_to_translation:`zh_CN:[中文]` @@ -9,19 +9,19 @@ This guide shows how to start using the ESP32-DevKitC V4 development board. For What You Need ------------- -* :ref:`ESP32-DevKitC V4 board ` +* ESP32-DevKitC V4 board * USB A / micro USB B cable * Computer running Windows, Linux, or macOS You can skip the introduction sections and go directly to Section `Start Application Development`_. -.. _DevKitC-Overview-cmake: +.. _DevKitC-Overview: Overview -------- -ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif `_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard. +ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif `_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard. To cover a wide range of user requirements, the following versions of ESP32-DevKitC V4 are available: @@ -46,7 +46,7 @@ Functional Description The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitC V4 board. -.. _get-started-esp32-devkitc-board-front-cmake: +.. _get-started-esp32-devkitc-board-front: .. figure:: ../../_static/esp32-devkitc-functional-overview.jpg :align: center @@ -107,6 +107,7 @@ The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boa In case these issues occur, please remove the component. The figure below shows C15 highlighted in yellow. + .. figure:: ../../_static/esp32-devkitc-c15-location.png :align: center :alt: Location of C15 (colored yellow) on ESP32-DevKitC V4 board @@ -121,9 +122,7 @@ Start Application Development Before powering up your ESP32-DevKitC V4, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Board Dimensions diff --git a/docs/en/hw-reference/get-started-ethernet-kit.rst b/docs/en/hw-reference/get-started-ethernet-kit.rst index 7a315c1aa..13f1d7848 100644 --- a/docs/en/hw-reference/get-started-ethernet-kit.rst +++ b/docs/en/hw-reference/get-started-ethernet-kit.rst @@ -348,9 +348,7 @@ Initial Setup Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +Proceed to :doc:`../get-started/index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Move on to the next section only if you have successfully completed all the above steps. diff --git a/docs/en/hw-reference/get-started-pico-kit-v3.rst b/docs/en/hw-reference/get-started-pico-kit-v3.rst index a124582a5..b8b2366f6 100644 --- a/docs/en/hw-reference/get-started-pico-kit-v3.rst +++ b/docs/en/hw-reference/get-started-pico-kit-v3.rst @@ -1,5 +1,5 @@ ESP32-PICO-KIT V3 Getting Started Guide -=============================================== +======================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For the description of other ESP32-PICO-KIT versions, please check :doc:`../hw-reference/index`. @@ -65,9 +65,7 @@ Start Application Development Before powering up your ESP32-PICO-KIT V3, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents diff --git a/docs/en/hw-reference/get-started-pico-kit.rst b/docs/en/hw-reference/get-started-pico-kit.rst index 7c7ff7304..73c4b5ef6 100644 --- a/docs/en/hw-reference/get-started-pico-kit.rst +++ b/docs/en/hw-reference/get-started-pico-kit.rst @@ -10,7 +10,7 @@ This particular description covers ESP32-PICO-KIT V4 and V4.1. The difference is What You Need ------------- -* :ref:`ESP32-PICO-KIT mini development board ` +* :ref:`ESP32-PICO-KIT mini development board ` * USB 2.0 A to Micro B cable * Computer running Windows, Linux, or macOS @@ -58,7 +58,7 @@ Functional Description The following figure and the table below describe the key components, interfaces, and controls of the ESP32-PICO-KIT board. -.. _get-started-pico-kit-v4-board-front-cmake: +.. _get-started-pico-kit-v4-board-front: .. figure:: ../../_static/esp32-pico-kit-v4.1-f-layout.jpeg :align: center @@ -107,7 +107,7 @@ There are three mutually exclusive ways to provide power to the board: Pin Descriptions ---------------- -The two tables below provide the **Name** and **Function** of I/O header pins on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front-cmake`. The pin numbering and header names are the same as in the schematic given in `Related Documents`_. +The two tables below provide the **Name** and **Function** of I/O header pins on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front`. The pin numbering and header names are the same as in the schematic given in `Related Documents`_. Header J2 @@ -116,9 +116,9 @@ Header J2 ====== ================= ====== ====================================================== No. Name Type Function ====== ================= ====== ====================================================== -1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(See 1) ` , U2CTS -2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(See 1) ` , U2RTS -3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) ` , U1CTS +1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(See 1) ` , U2CTS +2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(See 1) ` , U2RTS +3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) ` , U1CTS 4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN 5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1 6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0 @@ -127,8 +127,8 @@ No. Name Type Function 9 IO5 I/O | GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK 10 IO10 I/O | GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD 11 IO9 I/O | GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD -12 RXD0 I/O | GPIO3, U0RXD :ref:`(See 3) ` , CLK_OUT2 -13 TXD0 I/O | GPIO1, U0TXD :ref:`(See 3) ` , CLK_OUT3, EMAC_RXD2 +12 RXD0 I/O | GPIO3, U0RXD :ref:`(See 3) ` , CLK_OUT2 +13 TXD0 I/O | GPIO1, U0TXD :ref:`(See 3) ` , CLK_OUT3, EMAC_RXD2 14 IO35 I | ADC1_CH7, RTC_GPIO5 15 IO34 I | ADC1_CH6, RTC_GPIO4 16 IO38 I | GPIO38, ADC1_CH2, RTC_GPIO2 @@ -145,20 +145,20 @@ Header J3 ====== ================= ====== ====================================================== No. Name Type Function ====== ================= ====== ====================================================== -1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(See 1) ` , U2RXD, EMAC_CLK_OUT -2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(See 1) ` , U2TXD, EMAC_CLK_OUT_180 -3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(See 1) ` , U1RTS +1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(See 1) ` , U2RXD, EMAC_CLK_OUT +2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(See 1) ` , U2TXD, EMAC_CLK_OUT_180 +3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(See 1) ` , U1RTS 4 SENSOR_VP (FSVP) I | GPIO36, ADC1_CH0, RTC_GPIO0 5 SENSOR_VN (FSVN) I | GPIO39, ADC1_CH3, RTC_GPIO3 6 IO25 I/O | GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0 7 IO26 I/O | GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1 -8 IO32 I/O | 32K_XP :ref:`(See 2a) ` , ADC1_CH4, TOUCH9, RTC_GPIO9 -9 IO33 I/O | 32K_XN :ref:`(See 2b) ` , ADC1_CH5, TOUCH8, RTC_GPIO8 +8 IO32 I/O | 32K_XP :ref:`(See 2a) ` , ADC1_CH4, TOUCH9, RTC_GPIO9 +9 IO33 I/O | 32K_XN :ref:`(See 2b) ` , ADC1_CH5, TOUCH8, RTC_GPIO8 10 IO27 I/O | GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17 | EMAC_RX_DV 11 IO14 I/O | ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK, | HS2_CLK, SD_CLK, EMAC_TXD2 -12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(See 4) ` , HSPIQ, +12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(See 4) ` , HSPIQ, | HS2_DATA2, SD_DATA2, EMAC_TXD3 13 IO13 I/O | ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID, | HS2_DATA3, SD_DATA3, EMAC_RX_ER @@ -176,7 +176,7 @@ No. Name Type Function ====== ================= ====== ====================================================== -.. _get-started-pico-kit-v4-pin-notes-cmake: +.. _get-started-pico-kit-v4-pin-notes: The following notes give more information about the items in the tables above. @@ -193,9 +193,7 @@ Start Application Development Before powering up your ESP32-PICO-KIT, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Board Dimensions diff --git a/docs/en/hw-reference/get-started-wrover-kit-v2.rst b/docs/en/hw-reference/get-started-wrover-kit-v2.rst index 08da1d59f..1aa0c6b59 100644 --- a/docs/en/hw-reference/get-started-wrover-kit-v2.rst +++ b/docs/en/hw-reference/get-started-wrover-kit-v2.rst @@ -1,5 +1,5 @@ ESP-WROVER-KIT V2 Getting Started Guide -=============================================== +======================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP-WROVER-KIT V2 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. @@ -52,7 +52,7 @@ Functional Description The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board. -.. _get-started-esp-wrover-kit-v2-board-front-cmake: +.. _get-started-esp-wrover-kit-v2-board-front: .. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png :align: center @@ -61,7 +61,7 @@ The following two figures and the table below describe the key components, inter ESP-WROVER-KIT board layout - front -.. _get-started-esp-wrover-kit-v2-board-back-cmake: +.. _get-started-esp-wrover-kit-v2-board-back: .. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png :align: center @@ -116,11 +116,11 @@ I/O All the pins on the ESP32 module are broken out to pin heade MicroSD Card MicroSD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the MicroSD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in Section `Setup Options`_. -LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v2-board-back-cmake`. +LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v2-board-back`. ================== ================================================================================================================================= -.. _get-started-esp-wrover-kit-v2-setup-options-cmake: +.. _get-started-esp-wrover-kit-v2-setup-options: Setup Options ------------- @@ -140,7 +140,7 @@ JP14 |jp14| Enable RTS/CTS flow control for serial communication ======= ================ ========================================================= -.. _get-started-esp-wrover-kit-v2-start-development-cmake: +.. _get-started-esp-wrover-kit-v2-start-development: Start Application Development ----------------------------- @@ -170,9 +170,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -194,4 +192,4 @@ Related Documents .. |jp11-tx-rx| image:: ../../_static/wrover-jp11-tx-rx.png .. |jp14| image:: ../../_static/wrover-jp14.png -.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf \ No newline at end of file +.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf diff --git a/docs/en/hw-reference/get-started-wrover-kit-v3.rst b/docs/en/hw-reference/get-started-wrover-kit-v3.rst index e64e50d7d..276c6877b 100644 --- a/docs/en/hw-reference/get-started-wrover-kit-v3.rst +++ b/docs/en/hw-reference/get-started-wrover-kit-v3.rst @@ -1,5 +1,6 @@ + ESP-WROVER-KIT V3 Getting Started Guide -=============================================== +======================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP-WROVER-KIT V3 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. @@ -8,7 +9,7 @@ This guide shows how to get started with the ESP-WROVER-KIT V3 development board What You Need ------------- -* :ref:`ESP-WROVER-KIT V3 board ` +* :ref:`ESP-WROVER-KIT V3 board ` * USB 2.0 cable（A to Micro-B） * Computer running Windows, Linux, or macOS @@ -52,7 +53,7 @@ Functional Description The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board. -.. _get-started-esp-wrover-kit-v3-board-front-cmake: +.. _get-started-esp-wrover-kit-v3-board-front: .. figure:: ../../_static/esp-wrover-kit-v3-layout-front.jpg :align: center @@ -61,7 +62,7 @@ The following two figures and the table below describe the key components, inter ESP-WROVER-KIT board layout - front -.. _get-started-esp-wrover-kit-v3-board-back-cmake: +.. _get-started-esp-wrover-kit-v3-board-back: .. figure:: ../../_static/esp-wrover-kit-v3-layout-back.jpg :align: center @@ -118,11 +119,11 @@ I/O All the pins on the ESP32 module are broken out to pin heade MicroSD Card Slot Useful for developing applications that access MicroSD card for data storage and retrieval. -LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v3-board-back-cmake`. +LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v3-board-back`. ================== ================================================================================================================================= -.. _get-started-esp-wrover-kit-v3-setup-options-cmake: +.. _get-started-esp-wrover-kit-v3-setup-options: Setup Options ------------- @@ -178,17 +179,17 @@ JTAG, MicroSD IO15 5V Legend: -* NC/XTAL - :ref:`32.768 kHz Oscillator ` -* JTAG - :ref:`JTAG / JP8 ` +* NC/XTAL - :ref:`32.768 kHz Oscillator ` +* JTAG - :ref:`JTAG / JP8 ` * Boot - Boot button / SW2 -* Camera - :ref:`Camera / JP4 ` -* LED - :ref:`RGB LED ` -* MicroSD - :ref:`MicroSD Card / J4 ` -* LCD - :ref:`LCD / U5 ` +* Camera - :ref:`Camera / JP4 ` +* LED - :ref:`RGB LED ` +* MicroSD - :ref:`MicroSD Card / J4 ` +* LCD - :ref:`LCD / U5 ` * PSRAM - only in case ESP32-WROVER is installed -.. _get-started-esp-wrover-kit-v3-xtal-cmake: +.. _get-started-esp-wrover-kit-v3-xtal: 32.768 kHz Oscillator ^^^^^^^^^^^^^^^^^^^^^ @@ -205,7 +206,7 @@ Legend: Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24. -.. _get-started-esp-wrover-kit-v3-spi-flash-header-cmake: +.. _get-started-esp-wrover-kit-v3-spi-flash-header: SPI Flash / JP13 ^^^^^^^^^^^^^^^^ @@ -223,10 +224,10 @@ SPI Flash / JP13 .. important:: - The module's flash bus is connected to the jumper block JP13 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can disolder these resistors to disconnect the module's flash bus from the pin header JP13. + The module's flash bus is connected to the jumper block JP13 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can desolder these resistors to disconnect the module's flash bus from the pin header JP13. -.. _get-started-esp-wrover-kit-v3-jtag-header-cmake: +.. _get-started-esp-wrover-kit-v3-jtag-header: JTAG / JP8 ^^^^^^^^^^ @@ -242,7 +243,7 @@ JTAG / JP8 ==== ============== ============= -.. _get-started-esp-wrover-kit-v3-camera-header-cmake: +.. _get-started-esp-wrover-kit-v3-camera-header: Camera / JP4 ^^^^^^^^^^^^ @@ -273,7 +274,7 @@ Camera / JP4 * Signals D0 .. D7 denote camera data bus -.. _get-started-esp-wrover-kit-v3-rgb-led-connections-cmake: +.. _get-started-esp-wrover-kit-v3-rgb-led-connections: RGB LED ^^^^^^^ @@ -287,7 +288,7 @@ RGB LED ==== ========== ========= -.. _get-started-esp-wrover-kit-v3-microsd-card-slot-cmake: +.. _get-started-esp-wrover-kit-v3-microsd-card-slot: MicroSD Card ^^^^^^^^^^^^ @@ -305,7 +306,7 @@ MicroSD Card ==== ============== =============== -.. _get-started-esp-wrover-kit-v3-lcd-connector-cmake: +.. _get-started-esp-wrover-kit-v3-lcd-connector: LCD / U5 ^^^^^^^^ @@ -323,7 +324,7 @@ LCD / U5 ==== ============== =============== -.. _get-started-esp-wrover-kit-v3-start-development-cmake: +.. _get-started-esp-wrover-kit-v3-start-development: Start Application Development ----------------------------- @@ -353,9 +354,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -379,4 +378,4 @@ Related Documents .. toctree:: :hidden: - get-started-wrover-kit-v2.rst \ No newline at end of file + get-started-wrover-kit-v2.rst diff --git a/docs/en/hw-reference/get-started-wrover-kit.rst b/docs/en/hw-reference/get-started-wrover-kit.rst index 5a40efeb5..0be440976 100644 --- a/docs/en/hw-reference/get-started-wrover-kit.rst +++ b/docs/en/hw-reference/get-started-wrover-kit.rst @@ -1,5 +1,5 @@ ESP-WROVER-KIT V4.1 Getting Started Guide -================================================= +========================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. @@ -8,7 +8,7 @@ This guide shows how to get started with the ESP-WROVER-KIT V4.1 development boa What You Need ------------- -* :ref:`ESP-WROVER-KIT V4.1 board ` +* :ref:`ESP-WROVER-KIT V4.1 board ` * USB 2.0 cable（A to Micro-B） * Computer running Windows, Linux, or macOS @@ -51,9 +51,9 @@ The block diagram below shows the main components of ESP-WROVER-KIT and their in Functional Description ---------------------- -The following two figures and the table below describe the key components, interfaces and controls of the ESP-WROVER-KIT board. +The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board. -.. _get-started-esp-wrover-kit-v4.1-board-front-cmake: +.. _get-started-esp-wrover-kit-v4.1-board-front: .. figure:: ../../_static/esp-wrover-kit-v4.1-layout-front.png :align: center @@ -62,7 +62,7 @@ The following two figures and the table below describe the key components, inter ESP-WROVER-KIT board layout - front -.. _get-started-esp-wrover-kit-v4.1-board-back-cmake: +.. _get-started-esp-wrover-kit-v4.1-board-back: .. figure:: ../../_static/esp-wrover-kit-v4.1-layout-back.png :align: center @@ -123,11 +123,11 @@ I/O Connector All the pins on the ESP32 module are broken out to pin heade MicroSD Card Slot Useful for developing applications that access MicroSD card for data storage and retrieval. -LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v4.1-board-back-cmake`. +LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v4.1-board-back`. ================== ================================================================================================================================= -.. _get-started-esp-wrover-kit-v4.1-setup-options-cmake: +.. _get-started-esp-wrover-kit-v4.1-setup-options: Setup Options ------------- @@ -183,17 +183,17 @@ JTAG, MicroSD IO15 5V Legend: -* NC/XTAL - :ref:`32.768 kHz Oscillator ` -* JTAG - :ref:`JTAG / JP8 ` +* NC/XTAL - :ref:`32.768 kHz Oscillator ` +* JTAG - :ref:`JTAG / JP8 ` * Boot - Boot button / SW2 -* Camera - :ref:`Camera / JP4 ` -* LED - :ref:`RGB LED ` -* MicroSD - :ref:`MicroSD Card / J4 ` -* LCD - :ref:`LCD / U5 ` +* Camera - :ref:`Camera / JP4 ` +* LED - :ref:`RGB LED ` +* MicroSD - :ref:`MicroSD Card / J4 ` +* LCD - :ref:`LCD / U5 ` * PSRAM - ESP32-WROVER-B's PSRAM -.. _get-started-esp-wrover-kit-v4.1-xtal-cmake: +.. _get-started-esp-wrover-kit-v4.1-xtal: 32.768 kHz Oscillator ^^^^^^^^^^^^^^^^^^^^^ @@ -210,7 +210,7 @@ Legend: Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24. -.. _get-started-esp-wrover-kit-v4.1-spi-flash-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-spi-flash-header: SPI Flash / JP2 ^^^^^^^^^^^^^^^ @@ -231,7 +231,7 @@ SPI Flash / JP2 The module's flash bus is connected to the jumper block JP2 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can desolder these resistors to disconnect the module's flash bus from the pin header JP2. -.. _get-started-esp-wrover-kit-v4.1-jtag-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-jtag-header: JTAG / JP2 ^^^^^^^^^^ @@ -247,7 +247,7 @@ JTAG / JP2 ==== ============== ============= -.. _get-started-esp-wrover-kit-v4.1-camera-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-camera-header: Camera / JP4 ^^^^^^^^^^^^ @@ -278,7 +278,7 @@ Camera / JP4 * Signals D0 .. D7 denote camera data bus -.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections-cmake: +.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections: RGB LED ^^^^^^^ @@ -292,7 +292,7 @@ RGB LED ==== ========== ========= -.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot-cmake: +.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot: MicroSD Card ^^^^^^^^^^^^ @@ -310,7 +310,7 @@ MicroSD Card ==== ============== =============== -.. _get-started-esp-wrover-kit-v4.1-lcd-connector-cmake: +.. _get-started-esp-wrover-kit-v4.1-lcd-connector: LCD / U5 ^^^^^^^^ @@ -328,7 +328,7 @@ LCD / U5 ==== ============== =============== -.. _get-started-esp-wrover-kit-start-development-cmake: +.. _get-started-esp-wrover-kit-start-development: Start Application Development ----------------------------- @@ -358,9 +358,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -384,4 +382,4 @@ Related Documents :hidden: get-started-wrover-kit-v3.rst - get-started-wrover-kit-v2.rst \ No newline at end of file + get-started-wrover-kit-v2.rst diff --git a/docs/en/index.rst b/docs/en/index.rst index 5eb949327..d8a10c1d4 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -39,7 +39,6 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf - Get Started (CMake Preview) API Reference H/W Reference API Guides diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 17db90e27..f13a27aa1 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -72,7 +72,7 @@ The flash encryption operation is controlled by various eFuses available on ESP3 encrypt flash at boot time Odd number of bits set (1, 3, 5, 7): do not encrypt flash at boot time - + Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about ESP32 eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`. @@ -116,9 +116,9 @@ As mentioned above :ref:`flash_enc_development_mode` allows user to download as - Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value. -- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”. +- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". -- Select “Enable flash encryption on boot”. +- Select :ref:`Enable flash encryption on boot `. - By default the mode is set for **Development**. @@ -132,7 +132,7 @@ Build and flash the complete image including: bootloader, partition table and ap :: - make -j4 flash monitor + idf.py flash monitor Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when ESP32 boots after flash encryption is enabled for the first time. @@ -281,7 +281,7 @@ At this stage if user wants to update modified plaintext application image to fl :: - make -j4 encrypted-app-flash monitor + idf.py encrypted-app-flash monitor .. _encrypt_partitions: @@ -292,7 +292,7 @@ If all partitions needs to be updated in encrypted format, it can be done as :: - make -j4 encrypted-flash monitor + idf.py encrypted-flash monitor .. _pregenerated-flash-encryption-key: @@ -310,9 +310,9 @@ It is possible to pregenerate the flash encryption key on the host computer and espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin -- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”. +- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". -- Select “Enable flash encryption on boot”. +- Select :ref:`Enable flash encryption on boot `. - By default the mode is set for **Development**. @@ -327,7 +327,7 @@ Build and flash the complete image including: bootloader, partition table and ap :: - make -j4 flash monitor + idf.py flash monitor On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. @@ -335,7 +335,7 @@ At this stage if user wants to update new plaintext application image to flash t :: - make -j4 encrypted-app-flash monitor + idf.py encrypted-app-flash monitor For reprogramming all partitions in encrypted format follow :ref:`encrypt_partitions`. @@ -348,10 +348,10 @@ Release Mode In Release mode UART bootloader can not perform flash encryption operations and new plaintext images can be downloaded ONLY using OTA scheme which will encrypt the plaintext image before writing to flash. - Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. - -- Enable flash encryption support in second stage bootloader. In make menuconfig, navigate to “Security Features”. -- Select “Enable flash encryption on boot”. +- Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". + +- Select :ref:`Enable flash encryption on boot `. - Select **Release Mode**, by default the mode is set for **Development**. Please note **once the Release mode is selected the ``download_dis_encrypt`` and ``download_dis_decrypt`` eFuse bits will be programmed to disable UART bootloader access to flash contents**. @@ -365,7 +365,7 @@ Build and flash the complete image including: bootloader, partition table and ap :: - make -j4 flash monitor + idf.py flash monitor On next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application should execute correctly. @@ -549,12 +549,11 @@ If you've accidentally enabled flash encryption for some reason, the next flash You can disable flash encryption again by writing ``FLASH_CRYPT_CNT`` eFuse (only in Development mode): -- First, run ``make menuconfig`` and uncheck "Enable flash encryption boot" under "Security Features". +- First, open :ref:`project-configuration-menu` and disable :ref:`Enable flash encryption boot ` under "Security Features". - Exit menuconfig and save the new configuration. -- Run ``make menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*. -- Run ``make flash`` to build and flash a new bootloader and app, without flash encryption enabled. +- Run ``idf.py menuconfig`` again and double-check you really disabled this option! *If this option is left enabled, the bootloader will immediately re-enable encryption when it boots*. +- Run ``idf.py flash`` to build and flash a new bootloader and app, without flash encryption enabled. - Run ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the FLASH_CRYPT_CNT:: - espefuse.py burn_efuse FLASH_CRYPT_CNT Reset the ESP32 and flash encryption should be disabled, the bootloader will boot as normal. @@ -584,7 +583,7 @@ Flash Encryption and Secure Boot It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device: - :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key). -- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot ` docs.). In this configuration, ``make bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. +- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot ` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. - :ref:`Reflashing via Pregenerated Flash Encryption Key ` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable ` option to be enabled in the Secure Boot config. .. _flash-encryption-without-secure-boot: diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index 9a6f8a933..3cd24d803 100644 --- a/docs/en/security/secure-boot.rst +++ b/docs/en/security/secure-boot.rst @@ -25,7 +25,7 @@ Secure Boot Process Overview This is a high level overview of the secure boot process. Step by step instructions are supplied under :ref:`secure-boot-howto`. Further in-depth details are supplied under :ref:`secure-boot-technical-details`: -1. The options to enable secure boot are provided in the ``make menuconfig`` hierarchy, under "Secure Boot Configuration". +1. The options to enable secure boot are provided in the :ref:`project-configuration-menu`, under "Secure Boot Configuration". 2. Secure Boot defaults to signing images and partition table data during the build process. The "Secure boot private signing key" config item is a file path to a ECDSA public/private key pair in a PEM format file. @@ -76,7 +76,7 @@ Options to work around this are: How To Enable Secure Boot ------------------------- -1. Run ``make menuconfig``, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.) +1. Open the :ref:`project-configuration-menu`, navigate to "Secure Boot Configuration" and select the option "One-time Flash". (To understand the alternative "Reflashable" choice, see :ref:`secure-boot-reflashable`.) 2. Select a name for the secure boot signing key. This option will appear after secure boot is enabled. The file can be anywhere on your system. A relative path will be evaluated from the project directory. The file does not need to exist yet. @@ -90,15 +90,15 @@ How To Enable Secure Boot .. important:: For production environments, we recommend generating the keypair using openssl or another industry standard encryption program. See :ref:`secure-boot-generate-key` for more details. -5. Run ``make bootloader`` to build a secure boot enabled bootloader. The output of ``make`` will include a prompt for a flashing command, using ``esptool.py write_flash``. +5. Run ``idf.py bootloader`` to build a secure boot enabled bootloader. The build output will include a prompt for a flashing command, using ``esptool.py write_flash``. .. _secure-boot-resume-normal-flashing: 6. When you're ready to flash the bootloader, run the specified command (you have to enter it yourself, this step is not performed by make) and then wait for flashing to complete. **Remember this is a one time flash, you can't change the bootloader after this!**. -7. Run ``make flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4. +7. Run ``idf.py flash`` to build and flash the partition table and the just-built app image. The app image will be signed using the signing key you generated in step 4. -.. note:: ``make flash`` doesn't flash the bootloader if secure boot is enabled. +.. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled. 8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration. @@ -123,13 +123,13 @@ In the esp-idf build process, this 256-bit key file is derived from the app sign To enable a reflashable bootloader: -1. In the ``make menuconfig`` step, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable. +1. In the :ref:`project-configuration-menu`, select "Bootloader Config" -> :ref:`CONFIG_SECURE_BOOT_ENABLED` -> :ref:`CONFIG_SECURE_BOOTLOADER_MODE` -> Reflashable. 2. If necessary, set the :ref:`CONFIG_SECURE_BOOTLOADER_KEY_ENCODING` based on the coding scheme used by the device. The coding scheme is shown in the ``Features`` line when ``esptool.py`` connects to the chip, or in the ``espefuse.py summary`` output. 2. Follow the steps shown above to choose a signing key file, and generate the key file. -3. Run ``make bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process). +3. Run ``idf.py bootloader``. A binary key file will be created, derived from the private key that is used for signing. Two sets of flashing steps will be printed - the first set of steps includes an ``espefuse.py burn_key`` command which is used to write the bootloader key to efuse. (Flashing this key is a one-time-only process.) The second set of steps can be used to reflash the bootloader with a pre-calculated digest (generated during the build process). 4. Resume from :ref:`Step 6 of the one-time flashing process `, to flash the bootloader and enable secure boot. Watch the console log output closely to ensure there were no errors in the secure boot configuration. @@ -244,7 +244,7 @@ Deterministic ECDSA as specified by `RFC 6979 Security features -> Enable "Require signed app images" +1. Open :ref:`project-configuration-menu` -> Security features -> Enable :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT` 2. "Bootloader verifies app signatures" can be enabled, which verifies app on boot. diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt new file mode 100644 index 000000000..fc1cee798 --- /dev/null +++ b/docs/page_redirects.txt @@ -0,0 +1,52 @@ +# Redirects from "old URL" "new URL" +# +# Space delimited +# +# New URL should be relative to document root, only) +# +# Empty lines and lines starting with # are ignored + +api-reference/ethernet/index api-reference/network/index +api-reference/ethernet/esp_eth api-reference/network/esp_eth +api-reference/mesh/index api-reference/network/index +api-reference/mesh/esp_mesh api-reference/network/esp_mesh +api-reference/wifi/index api-reference/network/index +api-reference/wifi/esp_now api-reference/network/esp_now +api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig +api-reference/wifi/esp_wifi api-reference/network/esp_wifi +api-reference/system/tcpip_adapter api-reference/network/tcpip_adapter +get-started/idf-monitor api-guides/tools/idf-monitor +get-started-cmake/idf-monitor api-guides/tools/idf-monitor +get-started/get-started-devkitc hw-reference/get-started-devkitc +get-started/get-started-devkitc-v2 hw-reference/get-started-devkitc-v2 +get-started/get-started-wrover-kit hw-reference/get-started-wrover-kit +get-started/get-started-wrover-kit-v2 hw-reference/get-started-wrover-kit-v2 +get-started/get-started-wrover-kit-v3 hw-reference/get-started-wrover-kit-v3 +get-started/get-started-pico-kit hw-reference/get-started-pico-kit +get-started/get-started-pico-kit-v3 hw-reference/get-started-pico-kit-v3 + +# The preview 'get-started-cmake' guides are now 'get-started' +get-started-cmake get-started +get-started-cmake/add-idf_path-to-profile get-started/add-idf_path-to-profile +get-started-cmake/eclipse-setup get-started/eclipse-setup +get-started-cmake/establish-serial-connection get-started/establish-serial-connection +get-started-cmake/index get-started/index +get-started-cmake/linux-setup get-started/linux-setup +get-started-cmake/linux-setup-scratch get-started/linux-setup-scratch +get-started-cmake/macos-setup get-started/macos-setup +get-started-cmake/macos-setup-scratch get-started/macos-setup-scratch +get-started-cmake/toolchain-setup-scratch get-started/toolchain-setup-scratch +get-started-cmake/windows-setup get-started/windows-setup +get-started-cmake/windows-setup-scratch get-started/windows-setup-scratch +get-started-cmake/get-started-devkitc hw-reference/get-started-devkitc +get-started-cmake/get-started-devkitc-v2 hw-reference/get-started-devkitc-v2 +get-started-cmake/get-started-wrover-kit hw-reference/get-started-wrover-kit +get-started-cmake/get-started-wrover-kit-v2 hw-reference/get-started-wrover-kit-v2 +get-started-cmake/get-started-wrover-kit-v3 hw-reference/get-started-wrover-kit-v3 +get-started-cmake/get-started-pico-kit hw-reference/get-started-pico-kit +get-started-cmake/get-started-pico-kit-v3 hw-reference/get-started-pico-kit-v3 + +api-guide/build-system-cmake api-guide/build-system +api-guide/ulp-cmake api-guide/ulp +api-guide/unit-tests-cmake api-guide/unit-tests + diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index fe496b067..55e456423 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -33,9 +33,12 @@ esp_bt_defs.inc:line: WARNING: Invalid definition: Expected identifier in nested # sphinx==1.8.4 # breathe==4.11.1 # -ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) -ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) -ulp-cmake.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) +ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) +ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) +ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) +ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size) +ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) +ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us) README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point) # # Issue present only when building on msys2 / mingw32 START >>> diff --git a/docs/zh_CN/api-guides/app_trace.rst b/docs/zh_CN/api-guides/app_trace.rst index 69d408f73..da295ade4 100644 --- a/docs/zh_CN/api-guides/app_trace.rst +++ b/docs/zh_CN/api-guides/app_trace.rst @@ -151,7 +151,7 @@ return res; } -2. 下一步是编译应用程序的镜像并将其下载到目标板上，这一步可以参考文档 :doc:`构建并烧写 <../get-started/make-project>`。 +2. 下一步是编译应用程序的镜像并将其下载到目标板上，这一步可以参考文档 :ref:`构建并烧写 `。 3. 运行 OpenOCD（参见 :doc:`JTAG 调试 <../api-guides/jtag-debugging/index>`）。 4. 连接到 OpenOCD 的 telnet 服务器，在终端执行如下命令 ``telnet 4444``。如果在运行 OpenOCD 的同一台机器上打开 telnet 会话，您可以使用 ``localhost`` 替换上面命令中的 ````。 diff --git a/docs/zh_CN/api-guides/build-system-cmake.rst b/docs/zh_CN/api-guides/build-system-cmake.rst deleted file mode 100644 index 6f9a9970f..000000000 --- a/docs/zh_CN/api-guides/build-system-cmake.rst +++ /dev/null @@ -1,1083 +0,0 @@ -构建系统（CMake 版） -******************** -:link_to_translation:`en:[English]` - -.. include:: ../cmake-warning.rst - -.. include:: ../cmake-pending-features.rst - -本文档将介绍基于 CMake 的 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念，此外 ESP-IDF 还支持 :doc:`基于 GNU Make 的构建系统 `。 - -如需您想了解如何使用 CMake 构建系统来组织和构建新的 ESP-IDF 项目或组件，请阅读本文档。 - -概述 -==== - -一个 ESP-IDF 项目可以看作是多个不同组件的集合，例如一个显示当前湿度的网页服务器会包含以下组件： - -- ESP32 基础库，包括 libc、ROM bindings 等 -- Wi-Fi 驱动 -- TCP/IP 协议栈 -- FreeRTOS 操作系统 -- 网页服务器 -- 湿度传感器的驱动 -- 负责将上述组件整合到一起的主程序 - -ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，构建系统会前往 ESP-IDF 目录、项目目录和用户自定义目录（可选）中查找所有组件，允许用户通过文本菜单系统配置 ESP-IDF 项目中用到的每个组件。在所有组件配置结束后，构建系统开始编译整个项目。 - -概念 ----- - -- ``项目`` 特指一个目录，其中包含了构建可执行应用程序所需的全部文件和配置，以及其他支持型文件，例如分区表、数据/文件系统分区和引导程序。 -- ``项目配置`` 保存在项目根目录下名为 ``sdkconfig`` 的文件中，可以通过 ``idf.py menuconfig`` 进行修改，且一个项目只能包含一个项目配置。 -- ``应用程序`` 是由 ESP-IDF 构建得到的可执行文件。一个项目通常会构建两个应用程序：项目应用程序（可执行的主文件，即用户自定义的固件）和引导程序（启动并初始化项目应用程序）。 -- ``组件`` 是模块化且独立的代码，会被编译成静态库（.a 文件）并链接到应用程序。部分组件由 ESP-IDF 官方提供，其他组件则来源于其它开源项目。 -- ``目标`` 特指运行构建后应用程序的硬件设备。ESP-IDF 当前仅支持 ``ESP32`` 这一个硬件目标。 - -请注意，以下内容并不属于项目的组成部分： - -- ``ESP-IDF`` 并不是项目的一部分，它独立于项目，通过 ``IDF_PATH`` 环境变量（保存 ``esp-idf`` 目录的路径）链接到项目，从而将 IDF 框架与项目分离。 -- 交叉编译工具链并不是项目的组成部分，它应该被安装在系统 PATH 环境变量中。 - -使用构建系统 -============ - -.. _idf.py: - -idf.py ------- - -``idf.py`` 命令行工具提供了一个前端，可以帮助您轻松管理项目的构建过程，它管理了以下工具： - -- CMake_，配置待构建的系统 -- 命令行构建工具（Ninja_ 或 `GNU Make`） -- `esptool.py`_，烧录 ESP32 - -:ref:`入门指南 ` 简要介绍了如何设置 ``idf.py`` 用于配置、构建并烧录项目。 - -``idf.py`` 应运行在 ESP-IDF 的 ``项目`` 目录下，即包含 ``CMakeLists.txt`` 文件的目录。仅包含 Makefile 的老式项目并不支持 ``idf.py``。 - -运行 ``idf.py --help`` 查看完整的命令列表。下面总结了最常用的命令： - -- ``idf.py menuconfig`` 会运行 ``menuconfig`` 工具来配置项目。 -- ``idf.py build`` 会构建在当前目录下找到的项目，它包括以下步骤： - - - 根据需要创建 ``build`` 构建目录，它用于保存构建过程的输出文件，可以使用 ``-B`` 选项修改默认的构建目录。 - - 根据需要运行 CMake_ 配置命令，为主构建工具生成构建文件。 - - 运行主构建工具（Ninja_ 或 `GNU Make`）。默认情况下，构建工具会被自动检测，可以使用 ``-G`` 选项显式地指定构建工具。 - - 构建过程是增量式的，如果自上次构建以来源文件或项目配置没有发生改变，则不会执行任何操作。 - -- ``idf.py clean`` 会把构建输出的文件从构建目录中删除，从而清理整个项目。下次构建时会强制“重新完整构建”这个项目。清理时，不会删除 CMake 配置输出及其他文件。 -- ``idf.py fullclean`` 会将整个 ``build`` 目录下的内容全部删除，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的 *所有文件*，请谨慎使用。项目配置文件不会被删除。 -- ``idf.py flash`` 会在必要时自动构建项目，并将生成的二进制程序烧录进 ESP32 设备中。``-p`` 和 ``-b`` 选项可分别设置串口的设备名和烧录时的波特率。 -- ``idf.py monitor`` 用于显示 ESP32 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`tools/idf-monitor`。 - -多个 ``idf.py`` 命令可合并成一个，例如，``idf.py -p COM4 clean flash monitor`` 会依次清理源码树，构建项目，烧录进 ESP32 设备，最后运行串口监视器。 - -.. Note:: 环境变量 ``ESPPORT`` 和 ``ESPBAUD`` 可分别用作 ``-p`` 和 ``-b`` 选项的默认值。在命令行中，重新为这两个选项赋值，会覆盖其默认值。 - -.. _idf.py-size: - -高级命令 -^^^^^^^^ - -- ``idf.py app``，``idf.py bootloader``，``idf.py partition_table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。 -- ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 ESP32。 -- ``idf.py -p PORT erase_flash`` 会使用 esptool.py 擦除 ESP32 的整个 Flash。 -- ``idf.py size`` 会打印应用程序相关的大小信息，``idf.py size-components`` 和 ``idf.py size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。 -- ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。 - -同时调用多个 ``idf.py`` 命令时，命令的输入顺序并不重要，它们会按照正确的顺序依次执行，并保证每一条命令都生效（即先构建后烧录，先擦除后烧录等）。 - -直接使用 CMake --------------- - -为了方便，:ref:`idf.py` 已经封装了 CMake_ 命令，但是您愿意，也可以直接调用 CMake。 - -.. highlight:: bash - -当 ``idf.py`` 在执行某些操作时，它会打印出其运行的每条命令以便参考。例如运行 ``idf.py build`` 命令与在 bash shell（或者 Windows Command Prompt）中运行以下命令是相同的:: - - mkdir -p build - cd build - cmake .. -G Ninja # 或者 'Unix Makefiles' - ninja - -在上面的命令列表中，``cmake`` 命令对项目进行配置，并生成用于最终构建工具的构建文件。在这个例子中，最终构建工具是 Ninja_: 运行 ``ninja`` 来构建项目。 - -没有必要多次运行 ``cmake``。第一次构建后，往后每次只需运行 ``ninja`` 即可。如果项目需要重新配置，``ninja`` 会自动重新调用 ``cmake``。 - -若在 CMake 中使用 ``ninja`` 或 ``make``，则多数 ``idf.py`` 子命令也会有其对应的目标，例如在构建目录下运行 ``make menuconfig`` 或 ``ninja menuconfig`` 与运行 ``idf.py menuconfig`` 是相同的。 - -.. Note:: - 如果您已经熟悉了 CMake_，那么可能会发现 ESP-IDF 的 CMake 构建系统不同寻常，为了减少样板文件，该系统封装了 CMake 的许多功能。请参考 :ref:`write-pure-cmake-component` 以编写更多 ``CMake 风格`` 的组件。 - -.. _flash-with-ninja-or-make: - -使用 Ninja/Make 来烧录 -^^^^^^^^^^^^^^^^^^^^^^ - -您可以直接使用 ninja 或 make 运行如下命令来构建项目并烧录:: - - ninja flash - -或:: - - make app-flash - -可用的目标还包括：``flash``、``app-flash`` （仅用于 app）、``bootloader-flash`` （仅用于 bootloader）。 - -以这种方式烧录时，可以通过设置 ``ESPPORT`` 和 ``ESPBAUD`` 环境变量来指定串口设备和波特率。您可以在操作系统或 IDE 项目中设置该环境变量，或者直接在命令行中进行设置:: - - ESPPORT=/dev/ttyUSB0 ninja flash - -.. Note:: 在命令的开头为环境变量赋值属于 Bash shell 的语法，可在 Linux 、macOS 和 Windows 的类 Bash shell 中运行，但在 Windows Command Prompt 中无法运行。 - -或:: - - make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000 - -.. Note:: 在命令末尾为变量赋值属于 ``make`` 的语法，适用于所有平台的 ``make``。 - -在 IDE 中使用 CMake -------------------- - -您还可以使用集成了 CMake 的 IDE，仅需将项目 ``CMakeLists.txt`` 文件的路径告诉 IDE 即可。集成 CMake 的 IDE 通常会有自己的构建工具（CMake 称之为“生成器”），它是组成 IDE 的一部分，用来构建源文件。 - -向 IDE 中添加除 ``build`` 目标以外的自定义目标（如添加 “Flash” 目标到 IDE）时，建议调用 ``idf.py`` 命令来执行这些“特殊”的操作。 - -有关将ESP-IDF 同 CMake 集成到 IDE 中的详细信息，请参阅 :ref:`build_system_metadata`。 - -.. _setting-python-interpreter: - -设置 Python 解释器 ------------------- - -目前，ESP-IDF 仅适用于 Python 2.7，如果系统中默认的 ``python`` 解释器是 Python 3.x，可能会出现问题。 - -如果使用了 ``idf.py``，并以 ``python2 $IDF_PATH/tools/idf.py ...`` 的方式运行 ``idf.py`` 则会解决这个问题（``idf.py`` 会通知其余 Python 进程使用相同的 Python 解释器）。你可以通过设置 shell 别名或其他脚本来简化该命令。 - -如果直接使用 CMake，运行 ``cmake -D PYTHON=python2 ...``，CMake 会使用传入的值覆盖默认的 Python 解释器。 - -如果使用集成 CMake 的 IDE，可以在 IDE 的图形用户界面中给名为 ``PYTHON`` 的 CMake cache 变量设置新的值来覆盖默认的 Python 解释器。 - -如果想在命令行中更优雅地管理 Python 的各个版本，请查看 pyenv_ 或 virtualenv_ 工具，它们会帮助您更改默认的 python 版本。 - -.. _example-project-structure: - -示例项目 -======== - -.. highlight:: none - -示例项目的目录树结构可能如下所示:: - - - myProject/ - - CMakeLists.txt - - sdkconfig - - components/ - component1/ - CMakeLists.txt - - Kconfig - - src1.c - - component2/ - CMakeLists.txt - - Kconfig - - src1.c - - include/ - component2.h - - main/ - src1.c - - src2.c - - build/ - -该示例项目 ``myproject`` 包含以下组成部分： - -- 顶层项目 CMakeLists.txt 文件，这是 CMake 用于学习如何构建项目的主要文件，可以在这个文件中设置项目全局的 CMake 变量。顶层项目 CMakeLists.txt 文件会导入 :idf_file:`/tools/cmake/project.cmake` 文件，由它负责实现构建系统的其余部分。该文件最后会设置项目的名称，并定义该项目。 -- ``sdkconfig`` 项目配置文件，执行 ``idf.py menuconfig`` 时会创建或更新此文件，文件中保存了项目中所有组件（包括 ESP-IDF 本身）的配置信息。 ``sdkconfig`` 文件可能会也可能不会被添加到项目的源码管理系统中。 -- 可选的 ``component`` 目录中包含了项目的部分自定义组件，并不是每个项目都需要这种自定义组件，但它组件有助于构建可复用的代码或者导入第三方（不属于 ESP-IDF）的组件。 -- ``main`` 目录是一个特殊的 ``伪组件``，包含项目本身的源代码。``main`` 是默认名称，CMake 变量 ``COMPONENT_DIRS`` 默认包含此组件，但您可以修改此变量。或者，您也可以在顶层 CMakeLists.txt 中设置 ``EXTRA_COMPONENT_DIRS`` 变量以查找其他指定位置处的组件。有关详细信息，请参阅 :ref:`重命名 main 组件 `。如果项目中源文件较多，建议将其归于组件中，而不是全部放在 ``main`` 中。 -- ``build`` 目录是存放构建输出的地方，如果没有此目录，``idf.py`` 会自动创建。CMake 会配置项目，并在此目录下生成临时的构建文件。随后，在主构建进程的运行期间，该目录还会保存临时目标文件、库文件以及最终输出的二进制文件。此目录通常不会添加到项目的源码管理系统中，也不会随项目源码一同发布。 - -每个组件目录都包含一个 ``CMakeLists.txt`` 文件，里面会定义一些变量以控制该组件的构建过程，以及其与整个项目的集成。更多详细信息请参阅 :ref:`component-directories-cmake`。 - -每个组件还可以包含一个 ``Kconfig`` 文件，它用于定义 ``menuconfig`` 时展示的 :ref:`component-configuration-cmake` 选项。某些组件可能还会包含 ``Kconfig.projbuild`` 和 ``project_include.cmake`` 特殊文件，它们用于 :ref:`override_project_config`。 - -项目 CMakeLists 文件 -==================== - -每个项目都有一个顶层 ``CMakeLists.txt`` 文件，包含整个项目的构建设置。默认情况下，项目 CMakeLists 文件会非常小。 - -最小 CMakeLists 文件示例 ------------------------- - -.. highlight:: cmake - -最小项目:: - - cmake_minimum_required(VERSION 3.5) - include($ENV{IDF_PATH}/tools/cmake/project.cmake) - project(myProject) - - -.. _project-mandatory-parts: - -必要部分 --------- - -每个项目都要按照上面显示的顺序添加上述三行代码： - -- ``cmake_minimum_required(VERSION 3.5)`` 必须放在 CMakeLists.txt 文件的第一行，它会告诉 CMake 构建该项目所需要的最小版本号。ESP-IDF 支持 CMake 3.5 或更高的版本。 -- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` 会导入 CMake 的其余功能来完成配置项目、检索组件等任务。 -- ``project(myProject)`` 会创建项目本身，并指定项目名称。该名称会作为最终输出的二进制文件的名字，即 ``myProject.elf`` 和 ``myProject.bin``。每个 CMakeLists 文件只能定义一个项目。 - -.. _optional_project_variable: - -可选的项目变量 --------------- - -以下这些变量都有默认值，用户可以覆盖这些变量值以自定义构建行为。更多实现细节，请参阅 :idf_file:`/tools/cmake/project.cmake` 文件。 - -- ``COMPONENT_DIRS``：组件的搜索目录，默认为 ``${IDF_PATH}/components``、``${PROJECT_PATH}/components`` 和 ``EXTRA_COMPONENT_DIRS``。如果您不想在这些位置搜索组件，请覆盖此变量。 -- ``EXTRA_COMPONENT_DIRS``：用于搜索组件的其它可选目录列表。路径可以是相对于项目目录的相对路径，也可以是绝对路径。 -- ``COMPONENTS``：要构建进项目中的组件名称列表，默认为 ``COMPONENT_DIRS`` 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过 ``COMPONENT_REQUIRES`` 指定了它依赖的另一个组件，则会自动将其添加到 ``COMPONENTS`` 中，所以 ``COMPONENTS`` 列表可能会非常短。 -- ``COMPONENT_REQUIRES_COMMON``：每个组件都需要的通用组件列表，这些通用组件会自动添加到每个组件的 ``COMPONENT_PRIV_REQUIRES`` 列表中以及项目的 ``COMPONENTS`` 列表中。默认情况下，此变量设置为 ESP-IDF 项目所需的最小核心“系统”组件集。通常您无需在项目中更改此变量。 - -以上变量中的路径可以是绝对路径，或者是相对于项目目录的相对路径。 - -请使用 `cmake 中的 set 命令 `_ 来设置这些变量，即 ``set(VARIABLE "VALUE")``。请注意，``set()`` 命令需放在 ``include(...)`` 之前，``cmake_minimum(...)`` 之后。 - -.. _rename-main-cmake: - -重命名 ``main`` 组件 --------------------- - -构建系统会对 ``main`` 组件进行特殊处理。假如 ``main`` 组件位于预期的位置（即 `${PROJECT_PATH}/main`），那么它会被自动添加到构建系统中。其他组件也会作为其依赖项被添加到构建系统中，这使用户免于处理依赖关系，并提供即时可用的构建功能。重命名 ``main`` 组件会减轻上述这些幕后工作量，但要求用户指定重命名后的组件位置，并手动为其添加依赖项。重命名 ``main`` 组件的步骤如下： - -1. 重命名 ``main`` 目录。 -2. 在项目 CMakeLists.txt 文件中设置 ``EXTRA_COMPONENT_DIRS``，并添加重命名后的 ``main`` 目录。 -3. 在组件的 CMakeLists.txt 文件中设置 ``COMPONENT_REQUIRES`` 或 ``COMPONENT_PRIV_REQUIRES`` 以指定依赖项。 - - -.. _component-directories-cmake: - -组件 CMakeLists 文件 -==================== - -每个项目都包含一个或多个组件，这些组件可以是 ESP-IDF 的一部分，可以是项目自身组件目录的一部分，也可以从自定义组件目录添加（ :ref:`见上文 `）。 - -组件是 ``COMPONENT_DIRS`` 列表中包含 ``CMakeLists.txt`` 文件的任何目录。 - -搜索组件 --------- - -搜索 ``COMPONENT_DIRS`` 中的目录列表以查找项目的组件，此列表中的目录可以是组件自身（即包含 `CMakeLists.txt` 文件的目录），也可以是子目录为组件的顶级目录。 - -当 CMake 运行项目配置时，它会记录本次构建包含的组件列表，它可用于调试某些组件的添加/排除。 - -同名组件 --------- - -ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进行，这意味着在默认情况下，首先搜索 ESP-IDF 内部组件，然后是项目组件，最后是 ``EXTRA_COMPONENT_DIRS`` 中的组件。如果这些目录中的两个或者多个包含具有相同名字的组件，则使用搜索到的最后一个位置的组件。这就允许将组件复制到项目目录中再修改以覆盖 ESP-IDF 组件，如果使用这种方式，ESP-IDF 目录本身可以保持不变。 - -.. _minimum_cmakelists: - -最小的组件 CMakeLists 文件 --------------------------- - -.. highlight:: cmake - -最小组件 ``CMakeLists.txt`` 文件内容如下:: - - set(COMPONENT_SRCS "foo.c") - set(COMPONENT_ADD_INCLUDEDIRS "include") - register_component() - -- ``COMPONENT_SRCS`` 是用空格分隔的源文件列表（``*.c``，``*.cpp``，``*.cc``，``*.S``），里面所有的源文件都将会编译进组件库中。 -- ``COMPONENT_ADD_INCLUDEDIRS`` 是用空格分隔的目录列表，里面的路径会被添加到所有需要该组件的组件（包括 main 组件）全局 include 搜索路径中。 -- ``register_component()`` 使用上述设置的变量将组件添加到构建系统中，构建生成与组件同名的库，并最终被链接到应用程序中。如果因为使用了 `CMake 中的 if 命令 `_ 或类似命令而跳过了这一步，那么该组件将不会被添加到构建系统中。 - -上述目录通常设置为相对于 ``CMakeLists.txt`` 文件的相对路径，当然也可以设置为绝对路径。 - -有关更完整的 ``CMakeLists.txt`` 示例，请参阅 :ref:`component_cmakelists_example`。 - -.. _preset_component_variables: - -预设的组件变量 --------------- - -以下专用于组件的变量可以在组件 CMakeLists 中使用，但不建议修改： - -- ``COMPONENT_PATH``：组件目录，即包含 ``CMakeLists.txt`` 文件的绝对路径，它与 ``CMAKE_CURRENT_SOURCE_DIR`` 变量一样，路径中不能包含空格。 -- ``COMPONENT_NAME``：组件名，与组件目录名相同。 -- ``COMPONENT_TARGET``：库目标名，它由构建系统在内部为组件创建。 - -以下变量在项目级别中被设置，但可在组件 CMakeLists 中使用： - -- ``PROJECT_NAME``：项目名，在项目 CMakeLists.txt 文件中设置。 -- ``PROJECT_PATH``：项目目录（包含项目 CMakeLists 文件）的绝对路径，与 ``CMAKE_SOURCE_DIR`` 变量相同。 -- ``COMPONENTS``：此次构建中包含的所有组件的名称，具体格式为用分号隔开的 CMake 列表。 -- ``CONFIG_*``：项目配置中的每个值在 cmake 中都对应一个以 ``CONFIG_`` 开头的变量。更多详细信息请参阅 :doc:`Kconfig `。 -- ``IDF_VER``：ESP-IDF 的 git 版本号，由 ``git describe`` 命令生成。 -- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: ESP-IDF 的组件版本，可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量，版本号 ``v4.0-dev-*``， ``v4.0-beta1``， ``v4.0-rc1`` 和 ``v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的，但是 ``IDF_VER`` 的值是不同的。 -- ``IDF_TARGET``：项目的硬件目标名称。 -- ``PROJECT_VER``：项目版本号。 - - * 如果在项目 CMakeLists.txt 文件中设置了 ``PROJECT_VER`` 变量，则该变量值可以使用。 - * 或者，如果 ``${PROJECT_PATH}/version.txt`` 文件存在，其内容会用作 ``PROJECT_VER`` 的值。 - * 或者，如果项目位于某个 Git 仓库中，则使用 ``git describe`` 命令的输出作为 ``PROJECT_VER`` 的值。 - * 否则，``PROJECT_VER`` 的值为空。 - -如果您在组件的 ``CMakeLists.txt`` 中修改以上变量，并不会影响其他组件的构建，但可能会使该组件变得难以构建或调试。 - -- ``COMPONENT_ADD_INCLUDEDIRS``：相对于组件目录的相对路径，为被添加到所有需要该组件的其他组件的全局 include 搜索路径中。如果某个 include 路径仅仅在编译当前组件时需要，请将其添加到 ``COMPONENT_PRIV_INCLUDEDIRS`` 中。 -- ``COMPONENT_REQUIRES`` 是一个用空格分隔的组件列表，列出了当前组件依赖的其他组件。如果当前组件有一个头文件位于 ``COMPONENT_ADD_INCLUDEDIRS`` 目录下，且该头文件包含了另一个组件的头文件，那么这个被依赖的组件需要在 ``COMPONENT_REQUIRES`` 中指出。这种依赖关系可以是递归的。 - - ``COMPONENT_REQUIRES`` 可以为空，因为所有的组件都需要一些常用的组件（如 newlib 组件提供的 libc 库、freertos 组件提供的 RTOS 功能），这些通用组件已经在项目级变量 ``COMPONENT_REQUIRES_COMMON`` 中被设置。 - - 如果一个组件仅需要额外组件的头文件来编译其源文件（而不是全局引入它们的头文件），则这些被依赖的组件需要在 ``COMPONENT_PRIV_REQUIRES`` 中指出。 - - 请参阅 :ref:`component_dependency`，查看详细信息。 - -可选的组件特定变量 ------------------- - -以下变量可在 ``CMakeLists.txt`` 中进行设置，用以控制该组件的构建行为： - -- ``COMPONENT_PRIV_INCLUDEDIRS``：相对于组件目录的相对路径，仅会被添加到该组件的 include 搜索路径中。 -- ``COMPONENT_PRIV_REQUIRES``：以空格分隔的组件列表，用于编译或链接当前组件的源文件。这些组件的头文件路径不会传递给其余需要它的组件，仅用于编译当前组件的源代码。更多详细信息请参阅 :ref:`component_dependency`。 -- ``COMPONENT_SRCS``：要编译进当前组件的源文件的路径，推荐使用此方法向构建系统中添加源文件。 -- ``COMPONENT_SRCDIRS``：相对于组件目录的源文件目录路径，用于搜索源文件（``*.cpp``，``*.c``，``*.S``）。匹配成功的源文件会替代 ``COMPONENT_SRCS`` 中指定的源文件，进而被编译进组件。即设置 ``COMPONENT_SRCDIRS`` 会导致 ``COMPONENT_SRCS`` 会被忽略。此方法可以很容易地将源文件整体导入到组件中，但并不推荐使用（详情请参阅 :ref:`cmake-file-globbing`）。 -- ``COMPONENT_SRCEXCLUDE``：需要从组件中剔除的源文件路径。当某个目录中有大量的源文件需要被导入组件中，但同时又有个别文件不需要导入时，可以配合 ``COMPONENT_SRCDIRS`` 变量一起设置。路径可以是相对于组件目录的相对路径，也可以是绝对路径。 -- ``COMPONENT_ADD_LDFRAGMENTS``：组件使用的链接片段文件的路径，用于自动生成链接器脚本文件。详细信息请参阅 :doc:`链接脚本生成机制 `。 - -.. Note:: - - 如果没有设置 ``COMPONENT_SRCDIRS`` 或 ``COMPONENT_SRCS``，组件不会被编译成库文件，但仍可以被添加到 include 路径中，以便在编译其他组件时使用。 - -.. _component_build_control: - -组件编译控制 ------------- - -.. highlight:: cmake - -在编译特定组件的源文件时，可以使用 ``target_compile_options`` 命令来传递编译器选项:: - - target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable) - -这条命令封装了 CMake 的 `target_compile_options`_ 命令。 - -如果给单个源文件指定编译器标志，可以使用 CMake 的 `set_source_files_properties`_ 命令:: - - set_source_files_properties(mysrc.c - PROPERTIES COMPILE_FLAGS - -Wno-unused-variable - ) - -如果上游代码在编译的时候发出了警告，那这么做可能会很有效。 - -请注意，上述两条命令只能在组件 CMakeLists 文件的 ``register_component()`` 命令之后调用。 - -.. _component-configuration-cmake: - -组件配置 -======== - -每个组件都可以包含一个 ``Kconfig`` 文件，和 ``CMakeLists.txt`` 放在同一目录下。``Kconfig`` 文件中包含要添加到该组件配置菜单中的一些配置设置信息。 - -运行 menuconfig 时，可以在 ``Component Settings`` 菜单栏下找到这些设置。 - -创建一个组件的 Kconfig 文件，最简单的方法就是使用 ESP-IDF 中现有的 Kconfig 文件作为模板，在这基础上进行修改。 - -有关示例请参阅 :ref:`add_conditional_config`。 - -预处理器定义 -============ - -ESP-IDF 构建系统会在命令行中添加以下 C 预处理器定义： - -- ``ESP_PLATFORM``：可以用来检测在 ESP-IDF 内发生了构建行为。 -- ``IDF_VER``：定义 git 版本字符串，例如：``v2.0`` 用于标记已发布的版本，``v1.0-275-g0efaa4f`` 则用于标记任意某次的提交记录。 -- ``PROJECT_VER``：项目版本号，详细信息请参阅 :ref:`preset_component_variables`。 -- ``PROJECT_NAME``：项目名称，定义在项目 CMakeLists.txt 文件中。 - -.. _component_dependency: - -组件依赖 -======== - -编译各个组件时，ESP-IDF 系统会递归评估其组件。 - -每个组件的源文件都会使用以下路径中的头文件进行编译: - -- 当前组件的 ``COMPONENT_ADD_INCLUDEDIRS`` 和 ``COMPONENT_PRIV_INCLUDEDIRS``。 -- 当前组件的 ``COMPONENT_REQUIRES`` 和 ``COMPONENT_PRIV_REQUIRES`` 变量指定的其他组件（即当前组件的所有公共和私有依赖项）所设置的 ``COMPONENT_ADD_INCLUDEDIRS``。 -- 所有组件的 ``COMPONENT_REQUIRES`` 做递归操作，即该组件递归运算后的所有公共依赖项。 - -编写组件 --------- - -- ``COMPONENT_REQUIRES`` 需要包含所有被当前组件的公共头文件 `#include` 的头文件所在的组件。 -- ``COMPONENT_PRIV_REQUIRES`` 需要包含被当前组件的源文件 `#include` 的头文件所在的组件（除非已经被设置在了 ``COMPONENT_PRIV_REQUIRES`` 中）。或者是当前组件正常工作必须要链接的组件。 -- ``COMPONENT_REQUIRES``、``COMPONENT_PRIV_REQUIRES`` 需要在调用 ``register_component()`` 之前设置。 -- ``COMPONENT_REQUIRES`` 和 ``COMPONENT_PRIV_REQUIRES`` 的值不能依赖于任何配置选项（``CONFIG_xxx``），这是因为在配置加载之前，依赖关系就已经被展开。其它组件变量（比如 ``COMPONENT_SRCS`` 和 ``COMPONENT_ADD_INCLUDEDIRS``）可以依赖配置选择。 -- 如果当前组件除了 ``COMPONENT_REQUIRES_COMMON`` 中设置的通用组件（比如 RTOS、libc 等）外，并不依赖其它组件，那么上述两个 ``REQUIRES`` 变量可以为空。 - -如果组件仅支持某些硬件目标（即依赖于特定的 ``IDF_TARGET``），则可以调用 ``require_idf_targets(NAMES...)`` CMake 函数来声明这个需求。在这种情况下，如果构建系统导入了不支持当前硬件目标的组件时就会报错。 - -创建项目 --------- - -- 默认情况下，每个组件都会包含在构建系统中。 -- 如果将 ``COMPONENTS`` 变量设置为项目直接使用的最小组件列表，那么构建系统会导入： - - * ``COMPONENTS`` 中明确提及的组件。 - * 这些组件的依赖项（以及递归运算后的组件）。 - * 每个组件都依赖的通用组件。 - -- 将 ``COMPONENTS`` 设置为所需组件的最小列表，可以显著减少项目的构建时间。 - -.. _component-requirements-implementation: - -构建系统中依赖处理的实现细节 ----------------------------- - -- 在 CMake 配置进程的早期阶段会运行 ``expand_requirements.cmake`` 脚本。该脚本会对所有组件的 CMakeLists.txt 文件进行局部的运算，得到一张组件依赖关系图（此图可能会有闭环）。此图用于在构建目录中生成 ``component_depends.cmake`` 文件。 -- CMake 主进程会导入该文件，并以此来确定要包含到构建系统中的组件列表（内部使用的 ``BUILD_COMPONENTS`` 变量）。``BUILD_COMPONENTS`` 变量已排好序，依赖组件会排在前面。由于组件依赖关系图中可能存在闭环，因此不能保证每个组件都满足该排序规则。如果给定相同的组件集和依赖关系，那么最终的排序结果应该是确定的。 -- CMake 会将 ``BUILD_COMPONENTS`` 的值以 “Component names:” 的形式打印出来。 -- 然后执行构建系统中包含的每个组件的配置。 -- 每个组件都被正常包含在构建系统中，然后再次执行 CMakeLists.txt 文件，将组件库加入构建系统。 - -组件依赖顺序 -^^^^^^^^^^^^ - -``BUILD_COMPONENTS`` 变量中组件的顺序决定了构建过程中的其它顺序，包括： - -- 项目导入 :ref:`project_include.cmake` 文件的顺序。 -- 生成用于编译（通过 ``-I`` 参数）的头文件路径列表的顺序。请注意，对于给定组件的源文件，仅需将该组件的依赖组件的头文件路径告知编译器。 - -构建的内部过程 -============== - -关于 CMake_ 以及 CMake 命令的详细信息，请参阅 `CMake v3.5 官方文档`_ 。 - -project.cmake 的内容 --------------------- - -当项目 CMakeLists 文件导入 ``project.cmake`` 文件时，``project.cmake`` 会定义一些实用的模块和全局变量。如果系统环境中没有设置 ``IDF_PATH``，那么它还会自动设置 ``IDF_PATH`` 变量。 - -``project.cmake`` 文件还重写了 CMake_ 内置的 ``project`` 函数，以添加所有 ESP-IDF 项目特有的功能。 - -project 函数 ------------- - -自定义的 ``project()`` 函数会执行以下步骤： - -- 确定硬件目标（由 ``IDF_TARGET`` 环境变量设置），并将其保存在 CMake cache 中。如果环境变量中设置的硬件目标与 CMake cache 中的不匹配，则会报错并退出。 -- 计算组件依赖，并构造 ``BUILD_COMPONENTS`` 变量，它是包含所有需要导入到构建系统中的组件列表（:ref:`详情请见上文`）。 -- 查找项目中所有的组件（搜索 ``COMPONENT_DIRS``，并按 ``COMPONENTS`` 进行过滤（前提是设置了该变量）。 -- 从 ``sdkconfig`` 文件中加载项目配置信息，生成 ``sdkconfig.cmake`` 和 ``sdkconfig.h`` 文件，分别用在 CMake 和 C/C++ 中定义配置项。如果项目配置发生了更改，CMake 会自动重新运行，重新生成上述两个文件，接着重新配置项目。 -- 根据硬件目标（``IDF_TARGET``）的值，将 `CMAKE_TOOLCHAIN_FILE`_ 变量设置为相应的工具链文件。 -- 调用 `CMake 的 project 函数 `_ 声明实际的 CMake-level 项目。 -- 加载 git 版本号。如果在 git 中检出了新的版本，就会使用一些技巧重新运行 CMake。详情请参考 :ref:`cmake-file-globbing`。 -- 从包含有 :ref:`project_include.cmake` 文件的组件中导入该文件。 -- 将每个组件都添加到构建系统中。每个组件的 CMakeLists 文件都会调用 ``register_component`` 函数，它会调用 CMake 的 `add_library `_ 函数来添加一个库，然后添加源文件、编译选项等。 -- 将最终的应用程序可执行文件添加到构建系统中。 -- 返回并为组件之间指定依赖关系（将每个组件的公共头文件目录添加到其他组件中）。 - -更多详细信息请参阅 :idf_file:`/tools/cmake/project.cmake` 文件和 :idf_file:`/tools/cmake/idf_functions.cmake` 文件。 - -CMake 调试 ----------- - -调试 ESP-IDF CMake 构建系统的一些技巧： - -- CMake 运行时，会打印大量诊断信息，包括组件列表和组件路径。 -- 运行 ``cmake -DDEBUG=1``，IDF 构建系统会生成更详细的诊断输出。 -- 运行 ``cmake`` 时指定 ``--trace`` 或 ``--trace-expand`` 选项会提供大量有关控制流信息。详情请参考 `CMake 命令行文档`_。 - -.. _warn-undefined-variables-cmake: - -警告未定义的变量 -^^^^^^^^^^^^^^^^ - -默认情况下，``idf.py`` 在调用 CMake_ 时会给它传递 ``--warn-uninitialized`` 标志，如果在构建的过程中引用了未定义的变量，CMake_ 会打印警告。这对查找有错误的 CMake 文件非常有用。 - -如果您不想启用此功能，可以给 ``idf.py`` 传递 ``--no-warnings`` 标志。 - -.. _override_project_config: - -覆盖项目的部分设置 ------------------- - -.. _project_include.cmake: - -project_include.cmake -^^^^^^^^^^^^^^^^^^^^^ - -如果组件的某些构建行为需要在组件 CMakeLists 文件之前被执行，您可以在组件目录下创建名为 ``project_include.cmake`` 的文件，``project.cmake`` 在运行过程中会导入此 CMake 文件。 - -``project_include.cmake`` 文件在 ESP-IDF 内部使用，以定义项目范围内的构建功能，比如 ``esptool.py`` 的命令行参数和 ``bootloader`` 这个特殊的应用程序。 - -与组件 ``CMakeLists.txt`` 文件有所不同，在导入``project_include.cmake`` 文件的时候，当前源文件目录（即 ``CMAKE_CURRENT_SOURCE_DIR``）和工作目录为项目目录。如果想获得当前组件的绝对路径，可以使用 ``COMPONENT_PATH`` 变量。 - -请注意，``project_include.cmake`` 对于大多数常见的组件并不是必需的。例如给项目添加 include 搜索目录，给最终的链接步骤添加 ``LDFLAGS`` 选项等等都可以通过 ``CMakeLists.txt`` 文件来自定义。详细信息请参考 :ref:`optional_project_variable`。 - -``project_include.cmake`` 文件会按照 ``BUILD_COMPONENTS`` 变量中组件的顺序（由 CMake 记录）依次导入。即只有在当前组件所有依赖组件的 ``project_include.cmake`` 文件都被导入后，当前组件的 ``project_include.cmake`` 文件才会被导入，除非两个组件在同一个依赖闭环中。如果某个 ``project_include.cmake`` 文件依赖于另一组件设置的变量，则要特别注意上述情况。更多详情请参阅 :ref:`component-requirements-implementation`。 - -在 ``project_include.cmake`` 文件中设置变量或目标时要格外小心，这些值被包含在项目的顶层 CMake 文件中，因此他们会影响或破坏所有组件的功能。 - -KConfig.projbuild -^^^^^^^^^^^^^^^^^ - -与 ``project_include.cmake`` 类似，也可以为组件定义一个 KConfig 文件以实现全局的 :ref:`component-configuration-cmake`。如果要在 menuconfig 的顶层添加配置选项，而不是在 “Component Configuration” 子菜单中，则可以在 ``CMakeLists.txt`` 文件所在目录的 KConfig.projbuild 文件中定义这些选项。 - -在此文件中添加配置时要小心，因为这些配置会包含在整个项目配置中。在可能的情况下，请为 :ref:`component-configuration-cmake` 创建 KConfig 文件。 - -.. _config_only_component: - -仅配置组件 -^^^^^^^^^^ - -仅配置组件是一类不包含源文件的特殊组件，仅包含 ``Kconfig.projbuild``、``KConfig`` 和 ``CMakeLists.txt`` 文件，该 ``CMakeLists.txt`` 文件仅有一行代码，调用了 ``register_config_only_component()`` 函数。此函数会将组件导入到项目构建中，但不会构建任何库，也不会将头文件添加到任何 include 搜索路径中。 - -如果 CMakeLists.txt 文件没有调用 ``register_component()`` 或 ``register_config_only_component()``，那么该文件将会被排除在项目构建之外。根据项目的配置，有时可能需要这么做。 - -.. _component_cmakelists_example: - -组件 CMakeLists 示例 -==================== - -因为构建环境试图设置大多数情况都能工作的合理默认值，所以组件 ``CMakeLists.txt`` 文件可能非常小，甚至是空的，请参考 :ref:`minimum_cmakelists`。但有些功能往往需要覆盖 :ref:`preset_component_variables` 才能实现。 - -以下是组件 CMakeLists 文件的更高级的示例。 - -.. _add_conditional_config: - -添加条件配置 ------------- - -配置系统可用于根据项目配置中选择的选项有条件地编译某些文件。 - -.. highlight:: none - -``Kconfig``:: - - config FOO_ENABLE_BAR - bool "Enable the BAR feature." - help - This enables the BAR feature of the FOO component. - -``CMakeLists.txt``:: - - set(COMPONENT_SRCS "foo.c" "more_foo.c") - - if(CONFIG_FOO_ENABLE_BAR) - list(APPEND COMPONENT_SRCS "bar.c") - endif() - -上述示例使用了 CMake 的 `if `_ 函数和 `list APPEND `_ 函数。 - -也可用于选择或删除某一实现，如下所示： - -``Kconfig``:: - - config ENABLE_LCD_OUTPUT - bool "Enable LCD output." - help - Select this if your board has a LCD. - - config ENABLE_LCD_CONSOLE - bool "Output console text to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output debugging output to the lcd - - config ENABLE_LCD_PLOT - bool "Output temperature plots to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output temperature plots - -.. highlight:: cmake - -``CMakeLists.txt``:: - - if(CONFIG_ENABLE_LCD_OUTPUT) - set(COMPONENT_SRCS lcd-real.c lcd-spi.c) - else() - set(COMPONENT_SRCS lcd-dummy.c) - endif() - - # 如果启用了控制台或绘图功能，则需要加入字体 - if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT) - list(APPEND COMPONENT_SRCS "font.c") - endif() - - -硬件目标的的条件判断 --------------------- - -CMake 文件可以使用 ``IDF_TARGET`` 变量来获取当前的硬件目标。 - -此外，如果当前的硬件目标是 ``xyz``（即 ``IDF_TARGET=xyz``），那么 Kconfig 变量 ``CONFIG_IDF_TARGET_XYZ`` 同样也会被设置。 - -请注意，组件可以依赖 ``IDF_TARGET`` 变量，但不能依赖这个 Kconfig 变量。同样也不可在 CMake 文件的 ``include`` 语句中使用 Kconfig 变量，在这种上下文中可以使用 ``IDF_TARGET``。 - - -生成源代码 ----------- - -有些组件的源文件可能并不是由组件本身提供，而必须从另外的文件生成。假设组件需要一个头文件，该文件由 BMP 文件转换后（使用 bmp2h 工具）的二进制数据组成，然后将头文件包含在名为 graphics_lib.c 的文件中:: - - add_custom_command(OUTPUT logo.h - COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h - DEPENDS ${COMPONENT_DIR}/logo.bmp - VERBATIM) - - add_custom_target(logo DEPENDS logo.h) - add_dependencies(${COMPONENT_LIB} logo) - - set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY - ADDITIONAL_MAKE_CLEAN_FILES logo.h) - -这个示例改编自 `CMake 的一则 FAQ `_，其中还包含了一些同样适用于 ESP-IDF 构建系统的示例。 - -这个示例会在当前目录（构建目录）中生成 logo.h 文件，而 logo.bmp 会随组件一起提供在组件目录中。因为 logo.h 是一个新生成的文件，一旦项目需要清理，该文件也应该要被清除。因此，要将该文件添加到 `ADDITIONAL_MAKE_CLEAN_FILES`_ 属性中。 - -.. Note:: - - 如果需要生成文件作为项目 CMakeLists.txt 的一部分，而不是作为组件 CMakeLists.txt 的一部分，此时需要使用 ``${PROJECT_PATH}`` 替代 ``${COMPONENT_DIR}``，使用 ``${PROJECT_NAME}.elf`` 替代 ``${COMPONENT_LIB}``。 - -如果某个源文件是从其他组件中生成，且包含 ``logo.h`` 文件，则需要调用 ``add_dependencies``， 在这两个组件之间添加一个依赖项，以确保组件源文件按照正确顺序进行编译。 - -嵌入二进制数据 ---------------------- - -有时您的组件希望使用一个二进制文件或者文本文件，但是您又不希望将它们重新格式化为 C 源文件，这时，您可以在组件 CMakeLists 中添加 ``COMPONENT_EMBED_FILES`` 变量，指定要嵌入的文件名称（以空格分隔）:: - - set(COMPONENT_EMBED_FILES server_root_cert.der) - -或者，如果文件是字符串，则可以设置 ``COMPONENT_EMBED_TXTFILES`` 变量，把文件的内容转成以 null 结尾的字符串嵌入:: - - set(COMPONENT_EMBED_TXTFILES server_root_cert.pem) - -.. highlight:: c - -文件的内容会被添加到 Flash 的 .rodata 段，用户可以通过符号名来访问，如下所示:: - - extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); - extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); - -符号名会根据文件全名生成，如 ``COMPONENT_EMBED_FILES`` 中所示，字符 ``/``、``.`` 等都会被下划线替代。符号名称中的 _binary 前缀由 objcopy 命令添加，对文本文件和二进制文件都是如此。 - -.. highlight:: cmake - -如果要将文件嵌入到项目中，而非组件中，可以调用 ``target_add_binary_data`` 函数:: - - target_add_binary_data(myproject.elf "main/data.bin" TEXT) - -并这行代码放在项目 CMakeLists.txt 的 ``project()`` 命令之后，修改 ``myproject.elf`` 为你自己的项目名。如果最后一个参数是 ``TEXT``，那么构建系统会嵌入以 null 结尾的字符串，如果最后一个参数被设置为 ``BINARY``，则将文件内容按照原样嵌入。 - -有关使用此技术的示例，请参考 :example:`protocols/https_request`，证书文件的内容会在编译时从 .pem 文件中加载。 - -代码和数据的存放 ----------------- - -ESP-IDF 还支持自动生成链接脚本，它允许组件通过链接片段文件定义其代码和数据在内存中的存放位置。构建系统会处理这些链接片段文件，并将处理后的结果扩充进链接脚本，从而指导应用程序二进制文件的链接过程。更多详细信息与快速上手指南，请参阅 :doc:`链接脚本生成机制 `。 - -.. _component-build-full-override: - -完全覆盖组件的构建过程 ----------------------- - -.. highlight:: cmake - -当然，在有些情况下，上面提到的方法不一定够用。如果组件封装了另一个第三方组件，而这个第三方组件并不能直接在 ESP-IDF 的构建系统中工作，在这种情况下，就需要放弃 ESP-IDF 的构建系统，改为使用 CMake 的 ExternalProject_ 功能。组件 CMakeLists 示例如下:: - - # 用于 quirc 的外部构建过程，在源目录中运行并生成 libquirc.a - externalproject_add(quirc_build - PREFIX ${COMPONENT_DIR} - SOURCE_DIR ${COMPONENT_DIR}/quirc - CONFIGURE_COMMAND "" - BUILD_IN_SOURCE 1 - BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a - INSTALL_COMMAND "" - ) - - # 将 libquirc.a 添加到构建系统中 - add_library(quirc STATIC IMPORTED GLOBAL) - add_dependencies(quirc quirc_build) - - set_target_properties(quirc PROPERTIES IMPORTED_LOCATION - ${COMPONENT_DIR}/quirc/libquirc.a) - set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES - ${COMPONENT_DIR}/quirc/lib) - - set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES - "${COMPONENT_DIR}/quirc/libquirc.a") - -（上述 CMakeLists.txt 可用于创建名为 ``quirc`` 的组件，该组件使用自己的 Makefile 构建 quirc_ 项目。） - -- ``externalproject_add`` 定义了一个外部构建系统。 - - - 设置 ``SOURCE_DIR``、``CONFIGURE_COMMAND``、``BUILD_COMMAND`` 和 ``INSTALL_COMMAND``。如果外部构建系统没有配置这一步骤，可以将 ``CONFIGURE_COMMAND`` 设置为空字符串。在 ESP-IDF 的构建系统中，一般会将 ``INSTALL_COMMAND`` 变量设置为空。 - - 设置 ``BUILD_IN_SOURCE``，即构建目录与源目录相同。否则，您也可以设置 ``BUILD_DIR`` 变量。 - - 有关 ``externalproject_add()`` 命令的详细信息，请参阅 ExternalProject_。 - -- 第二组命令添加了一个目标库，指向外部构建系统生成的库文件。为了添加 include 目录，并告知 CMake 该文件的位置，需要再设置一些属性。 -- 最后，生成的库被添加到 `ADDITIONAL_MAKE_CLEAN_FILES`_ 中。即执行 ``make clean`` 后会删除该库。请注意，构建系统中的其他目标文件不会被删除。 - -.. note:: 当外部构建系统使用 PSRAM 时，请记得将 ``-mfix-esp32-psram-cache-issue`` 添加到 C 编译器的参数中。关于该标志的更多详细信息，请参考 :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`。 - -.. _ADDITIONAL_MAKE_CLEAN_FILES_note: - -ExternalProject 的依赖与构建清理 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -对于外部项目的构建，CMake 会有一些不同寻常的行为： - -- `ADDITIONAL_MAKE_CLEAN_FILES`_ 仅在使用 Make 构建系统时有效。如果使用 Ninja_ 或 IDE 自带的构建系统，执行项目清理时，这些文件不会被删除。 -- ExternalProject_ 会在 clean 运行后自动重新运行配置和构建命令。 -- 可以采用以下两种方法来配置外部构建命令： - - 1. 将外部 ``BUILD_COMMAND`` 命令设置为对所有源代码完整的重新编译。如果传递给 ``externalproject_add`` 命令的 ``DEPENDS`` 的依赖项发生了改变，或者当前执行的是项目清理操作（即运行了 ``idf.py clean``、``ninja clean`` 或者 ``make clean``），那么就会执行该命令。 - 2. 将外部 ``BUILD_COMMAND`` 命令设置为增量式构建命令，并给 ``externalproject_add`` 传递 ``BUILD_ALWAYS 1`` 参数。即不管实际的依赖情况，每次构建时，都会构建外部项目。这种方式仅当外部构建系统具备增量式构建的能力，且运行时间不会很长时才推荐。 - -构建外部项目的最佳方法取决于项目本身、其构建系统，以及是否需要频繁重新编译项目。 - -.. _custom-sdkconfig-defaults-cmake: - -自定义 sdkconfig 的默认值 -========================= - -对于示例工程或者其他您不想指定完整 sdkconfig 配置的项目，但是您确实希望覆盖 ESP-IDF 默认值中的某些键值，则可以在项目中创建 ``sdkconfig.defaults`` 文件。重新创建新配置时将会用到此文件，另外在 ``sdkconfig`` 没有设置新配置值时，上述文件也会被用到。 - -如若需要覆盖此文件的名称，请设置 ``SDKCONFIG_DEFAULTS`` 环境变量。 - -依赖于硬件目标的 sdkconfig 默认值 ---------------------------------- - -除了 ``sdkconfig.defaults`` 之外，构建系统还将从 ``sdkconfig.defaults.TARGET_NAME`` 文件加载默认值，其中 ``IDF_TARGET`` 的值为 ``TARGET_NAME``。例如，对于 ``ESP32`` 这个硬件目标，sdkconfig 的默认值会首先从 ``sdkconfig.defaults`` 获取，然后再从 ``sdkconfig.defaults.esp32`` 获取。 - -如果使用 ``SDKCONFIG_DEFAULTS`` 覆盖了 sdkconfig 默认文件的名称，则硬件目标的 sdkconfig 默认文件名也会从 ``SDKCONFIG_DEFAULTS`` 值中派生。 - -.. _flash_parameters: - -Flash 参数 -========== - -有些情况下，我们希望在没有 IDF 时也能烧写目标板卡，为此，我们希望可以保存已构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以通过编写一段简单的脚本来保存二进制文件和 esptool.py。 - -运行项目构建之后，构建目录将包含项目二进制输出文件（``.bin`` 文件），同时也包含以下烧录数据文件： - -- ``flash_project_args`` 包含烧录整个项目的参数，包括应用程序 (app)、引导程序 (bootloader)、分区表，如果设置了 PHY 数据，也会包含此数据。 -- ``flash_app_args`` 只包含烧录应用程序的参数。 -- ``flash_bootloader_args`` 只包含烧录引导程序的参数。 - -.. highlight:: bash - -您可以参照如下命令将任意烧录参数文件传递给 ``esptool.py``:: - - python esptool.py --chip esp32 write_flash @build/flash_project_args - -也可以手动复制参数文件中的数据到命令行中执行。 - -构建目录中还包含生成的 ``flasher_args.json`` 文件，此文件包含 JSON 格式的项目烧录信息，可用于 ``idf.py`` 和其它需要项目构建信息的工具。 - -构建 Bootloader -=============== - -引导程序默认作为 ``idf.py build`` 的一部分被构建，也可以通过 ``idf.py bootloader`` 来单独构建。 - -引导程序是 :idf:`/components/bootloader/subproject` 内部独特的“子项目”，它有自己的项目 CMakeLists.txt 文件，能够构建独立于主项目的 ``.ELF`` 和 ``.BIN`` 文件，同时它又与主项目共享配置和构建目录。 - -子项目通过 :idf_file:`/components/bootloader/project_include.cmake` 文件作为外部项目插入到项目的顶层，主构建进程会运行子项目的 CMake，包括查找组件（主项目使用的组件的子集），生成引导程序专用的配置文件（从主 ``sdkconfig`` 文件中派生）。 - -选择硬件目标 -============ - -当前 ESP-IDF 仅支持一个硬件目标，即 ``esp32``，这也是构建系统默认的硬件目标。开发人员可以按照如下方法来添加对新硬件目标的支持:: - - rm sdkconfig - idf.py -DIDF_TARGET=new_target reconfigure - -.. _write-pure-cmake-component: - -编写纯 CMake 组件 -================= - -ESP-IDF 构建系统用“组件”的概念“封装”了 CMake，并提供了很多帮助函数来自动将这些组件集成到项目构建当中。 - -然而，“组件”概念的背后是一个完整的 CMake 构建系统，因此可以制作纯 CMake 组件。 - -.. highlight:: cmake - -下面是使用纯 CMake 语法为 ``json`` 组件编写的最小 CMakeLists 文件的示例:: - - add_library(json STATIC - cJSON/cJSON.c - cJSON/cJSON_Utils.c) - - target_include_directories(json PUBLIC cJSON) - -- 这实际上与 IDF 中的 :idf_file:`json 组件 ` 是等效的。 -- 因为组件中的源文件不多，所以这个 CMakeLists 文件非常简单。对于具有大量源文件的组件而言，ESP-IDF 支持的组件通配符，可以简化组件 CMakeLists 的样式。 -- 每当组件中新增一个与组件同名的库目标时，ESP-IDF 构建系统会自动将其添加到构建中，并公开公共的 include 目录。如果组件想要添加一个与组件不同名的库目标，就需要使用 CMake 命令手动添加依赖关系。 - -组件中使用第三方 CMake 项目 -=========================== - -CMake 在许多开源的 C/C++ 项目中广泛使用，用户可以在自己的应用程序中使用开源代码。CMake 构建系统的一大好处就是可以导入这些第三方的项目，有时候甚至不用做任何改动。这就允许用户使用当前 ESP-IDF 组件尚未提供的功能，或者使用其它库来实现相同的功能。 - -.. highlight:: cmake - -假设 ``main`` 组件需要导入一个假想库 ``foo``，相应的组件 CMakeLists 文件如下所示:: - - # 注册组件 - register_component() - - # 设置 `foo` 项目中的一些 CMake 变量，以控制 `foo` 的构建过程 - set(FOO_BUILD_STATIC OFF) - set(FOO_BUILD_TESTS OFF) - - # 创建并导入第三方库目标 - add_subdirectory(foo) - - # 将 IDF 全局的编译器设置、宏定义及其它选项传递给 `foo` 目标 - target_include_directories(foo ${IDF_INCLUDE_DIRECTORIES}) - target_compile_options(foo ${IDF_COMPILE_OPTIONS}) - target_compile_definitions(foo ${IDF_COMPILE_DEFINITIONS}) - - # 将 `foo` 目标链接至 `main` 组件 - target_link_libraries(main foo) - -实际的案例请参考 :example:`build_system/cmake/import_lib`。请注意，导入第三方库所需要做的工作可能会因库的不同而有所差异。建议仔细阅读第三方库的文档，了解如何将其导入到其它项目中。阅读第三方库的 CMakeLists.txt 文件以及构建结构也会有所帮助。 - -用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 `_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 `。 - -每当使用 ESP-IDF 构建系统时，CMake 变量 ``ESP_PLATFORM`` 都会被设置为 1。如果要在通用的 CMake 代码加入 IDF 特定的代码时，可以采用 ``if (ESP_PLATFORM)`` 的形式加以分隔。 - -在自定义 CMake 项目中使用 ESP-IDF -================================= - -ESP-IDF 提供了一个模板 CMake 项目，可以基于此轻松创建应用程序。然而在有些情况下，用户可能已有一个现成的 CMake 项目，或者想自己创建一个 CMake 项目，此时就希望将 IDF 中的组件以库的形式链接到用户目标（库/可执行文件）。 - -.. highlight:: cmake - -使用 :idf_file:`tools/cmake/idf_functions.cmake` 中提供的 ``idf_import_components`` 和 ``idf_link_components`` 函数可以实现上述功能，例如:: - - cmake_minimum_required(VERSION 3.5) - project(my_custom_app C) - - # 源文件 main.c 包含有 app_main() 函数的定义 - add_executable(${CMAKE_PROJECT_NAME}.elf main.c) - - # 提供 idf_import_components 及 idf_link_components 函数 - include($ENV{IDF_PATH}/tools/cmake/idf_functions.cmake) - - # 为 idf_import_components 做一些配置 - # 使能创建构件（不是每个项目都必须） - set(IDF_BUILD_ARTIFACTS ON) - set(IDF_PROJECT_EXECUTABLE ${CMAKE_PROJECT_NAME}.elf) - set(IDF_BUILD_ARTIFACTS_DIR ${CMAKE_BINARY_DIR}) - - # idf_import_components 封装了 add_subdirectory()，为组件创建库目标，然后使用给定的变量接收“返回”的库目标。 - # 在本例中，返回的库目标被保存在“component”变量中。 - idf_import_components(components $ENV{IDF_PATH} esp-idf) - - # idf_link_components 封装了 target_link_libraries()，将被 idf_import_components 处理过的组件链接到目标 - idf_link_components(${CMAKE_PROJECT_NAME}.elf "${components}") - -上述代码片段导入了 ESP-IDF 目录下的所有组件，并使用了 KConfig 中的默认值，同时还允许创建其它一些构件（比如分区表、包含项目信息的 json 文件、引导程序等）。除此以外，用户还可以设置其它的构建参数，其完整列表如下： - -- ``IDF_BUILD_ARTIFACTS``：构建工件，例如引导加载程序、分区表二进制文件、分区二进制数据、将二进制文件烧录到目标芯片时所需的包含项目信息的 json 文件等。同时需要设置 ``IDF_PROJECT_EXECUTABLE`` 和 ``IDF_BUILD_ARTIFACTS_DIR`` 变量。 -- ``IDF_PROJECT_EXECUTABLE``：最终可执行文件的名称。某些工件在创建的时候需要此参数。 -- ``IDF_BUILD_ARTIFACTS_DIR``：创建的构件被存放的位置。 -- ``IDF_EXTRA_COMPONENTS_DIR``：在 :idf:`默认组件目录 ` 之外的组件搜索路径。 -- ``IDF_COMPONENTS``：要导入的组件列表，设置此变量可以精简导入的组件，仅导入需要的组件，加快构建的速度。如果没有设置该变量，将会导入默认组件目录以及 ``IDF_EXTRA_COMPONENTS_DIR`` （如果设置了该变量）中找到的所有组件。请注意，该列表中组件的依赖组件（除了 ``IDF_COMPONENT_REQUIRES_COMMON`` 之外）也会被加入到构建之中。 -- ``IDF_COMPONENT_REQUIRES_COMMON``：通用组件依赖列表。无论 ``IDF_COMPONENTS`` 的值是什么，此列表中的组件及其依赖组件都会被导入到构建中。默认情况下，此变量被设置为核心“系统”组件的最小集合。 -- ``IDF_SDKCONFIG_DEFAULTS``：配置文件的覆盖路径，如果未设置，组件将会使用默认的配置选项来构建。 -- ``IDF_BUILD_TESTS``：在构建中包含组件的测试。默认情况下，所有的组件测试都会被包含。组件测试可通过 ``IDF_TEST_COMPONENTS`` 和 ``IDF_TEST_EXCLUDE_COMPONENTS`` 进行过滤。 -- ``IDF_TEST_COMPONENTS``：如果设置了 ``IDF_BUILD_TESTS``，构建中只会包含此列表中的组件测试。如果没有设置 ``IDF_BUILD_TESTS``，请忽略此项。 -- ``IDF_TEST_EXCLUDE_COMPONENTS``：如果设置了 ``IDF_BUILD_TESTS``，此列表中的组件测试将不会包含在构建中。如果没有设置 ``IDF_BUILD_TESTS``，请忽略此项。该变量的优先级高于 ``IDF_TEST_COMPONENTS``，这意味着，即使 ``IDF_TEST_COMPONENTS`` 中也存在此列表中的组件测试，它也不会被包含到构建之中。 - -:example:`build_system/cmake/idf_as_lib` 中的示例演示了如何在自定义的 CMake 项目创建一个类似于 :example:`Hello World ` 的应用程序。 - -.. _cmake-file-globbing: - -文件通配符 & 增量构建 -===================== - -.. highlight:: cmake - -在 ESP-IDF 组件中添加源文件的首选方法是在 ``COMPONENT_SRCS`` 中手动列出它们:: - - set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c) - -这是在 CMake 中手动列出源文件的 `最佳实践 `_。然而，当有许多源文件都需要添加到构建中时，这种方法就会很不方便。ESP-IDF 构建系统因此提供了另一种替代方法，即使用 ``COMPONENT_SRCDIRS`` 来指定源文件:: - - set(COMPONENT_SRCDIRS library platform) - -后台会使用通配符在指定的目录中查找源文件。但是请注意，在使用这种方法的时候，如果组件中添加了一个新的源文件，CMake 并不知道重新运行配置，最终该文件也没有被加入构建中。 - -如果是自己添加的源文件，这种折衷还是可以接受的，因为用户可以触发一次干净的构建，或者运行 ``idf.py reconfigure`` 来手动重启 CMake_。但是，如果你需要与其他使用 Git 等版本控制工具的开发人员共享项目时，问题就会变得更加困难，因为开发人员有可能会拉取新的版本。 - -ESP-IDF 中的组件使用了第三方的 Git CMake 集成模块（:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`），任何时候源码仓库的提交记录发生了改变，该模块就会自动重新运行 CMake。即只要 拉取了新的 ESP-IDF 版本，CMake 就会重新运行。 - -对于不属于 ESP-IDF 的项目组件，有以下几个选项供参考： - -- 如果项目文件保存在 Git 中，ESP-IDF 会自动跟踪 Git 修订版本，并在它发生变化时重新运行 CMake。 -- 如果一些组件保存在第三方 Git 仓库中（不在项目仓库或 ESP-IDF 仓库），则可以在组件 CMakeLists 文件中调用 ``git_describe`` 函数，以便在 Git 修订版本发生变化时自动重启 CMake。 -- 如果没有使用 Git，请记住在源文件发生变化时手动运行 ``idf.py reconfigure``。 -- 使用 ``COMPONENT_SRCS`` 在项目组件中列出所有源文件，可以完全避免这一问题。 - -具体选择哪一方式，就要取决于项目本身，以及项目用户。 - -.. _build_system_metadata: - -构建系统的元数据 -================ - -为了将 ESP-IDF 集成到 IDE 或者其它构建系统中，CMake 在构建的过程中会在 ``build/`` 目录下生成大量元数据文件。运行 ``cmake`` 或 ``idf.py reconfigure`` （或任何其它 ``idf.py`` 构建命令），可以重新生成这些元数据文件。 - -- ``compile_commands.json`` 是标准格式的 JSON 文件，它描述了在项目中参与编译的每个源文件。CMake 其中的一个功能就是生成此文件，许多 IDE 都知道如何解析此文件。 -- ``project_description.json`` 包含有关 ESP-IDF 项目、已配置路径等的一些常规信息。 -- ``flasher_args.json`` 包含 esptool.py 工具用于烧录项目二进制文件的参数，此外还有 ``flash_*_args`` 文件，可直接与 esptool.py 一起使用。更多详细信息请参阅 :ref:`flash_parameters`。 -- ``CMakeCache.txt`` 是 CMake 的缓存文件，包含 CMake 进程、工具链等其它信息。 -- ``config/sdkconfig.json`` 包含 JSON 格式的项目配置结果。 -- ``config/kconfig_menus.json`` 是在 menuconfig 中显示菜单的 JSON 格式版本，用于外部 IDE 的 UI。 - -JSON 配置服务器 ---------------- - -.. highlight :: json - -``confserver.py`` 工具可以帮助 IDE 轻松地与配置系统的逻辑进行集成，它运行在后台，通过使用 stdin 和 stdout 读写 JSON 文件的方式与调用进程交互。 - -您可以通过 ``idf.py confserver`` 或 ``ninja confserver`` 从项目中运行 ``confserver.py``，也可以使用不同的构建生成器来触发类似的目标。 - -配置服务器会向 stderr 输出方便阅读的错误和警告信息，向 stdout 输出 JSON 文件。启动时，配置服务器将以 JSON 字典的形式输出系统中每个配置项的完整值，以及范围受限的值的可用范围。``sdkconfig.json`` 中包含有相同的信息:: - - {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } } - -配置服务器仅发送可见的配置项，其它不可见的或者被禁用的配置项可从 ``kconfig_menus.json`` 静态文件中解析得到，此文件还包含菜单结构和其它元数据（描述、类型、范围等）。 - -然后配置服务器将等待客户端的输入，客户端会发起请求，要求更改一个或多个配置项的值，内容的格式是个 JSON 对象，后面跟一个换行符:: - - {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } } - -配置服务器将解析此请求，更新 ``sdkconfig`` 文件，并返回完整的变更列表:: - - {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}} - -当前不可见或者禁用的配置项会返回 ``null``，任何新的可见配置项则会返回其当前新的可见值。 - -如果配置项的取值范围因另一个值的变化发生了改变，那么配置服务器会发送:: - - {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } } - -如果传递的数据无效，那么 JSON 对象中会有 ``error`` 字段:: - - {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]} - -默认情况下，变更后的配置不会被写进 sdkconfig 文件。更改的内容在发出 “save” 命令之前会先储存在内存中:: - - {"version": 1, "save": null } - -若要从已保存的文件中重新加载配置值，并丢弃内存中的任何更改，可以发送 “load” 命令:: - - {"version": 1, "load": null } - -“load” 和 “save” 的值可以是新的路径名，也可以设置为 "null" 用以加载/保存之前使用的路径名。 - -配置服务器对 “load” 命令的响应始终是完整的配置值和取值范围的集合，这与服务器初始启动阶段的响应相同。 - -“load”、“set” 和 “save” 的任意组合可以在一条单独的命令中发送出去，服务器按照组合中的顺序执行命令。因此，可以使用一条命令实现从文件中加载配置，更新配置值，然后将其保存到文件中。 - -.. Note:: 配置服务器不会自动加载外部对 ``sdkconfig`` 文件的任何更改。如果文件被外部编辑，则需要发送 “load” 命令或重启服务器。 - -.. Note:: ``sdkconfig`` 文件更新后，配置服务器不会重新运行 CMake 来生成其它的构建文件和元数据文件。这些文件会在下一次运行 ``CMake`` 或 ``idf.py`` 时自动生成。 - -.. _gnu-make-to-cmake: - -从 ESP-IDF GNU Make 构建系统迁移到 CMake 构建系统 -================================================= - -ESP-IDF CMake 构建系统与旧版的 GNU Make 构建系统在某些方面非常相似，例如将 ``component.mk`` 文件改写 ``CMakeLists.txt``，像 ``COMPONENT_ADD_INCLUDEDIRS`` 和 ``COMPONENT_SRCDIRS`` 等变量可以保持不变，只需将语法改为 CMake 语法即可。 - -自动转换工具 ------------- - -.. highlight:: bash - -:idf_file:`/tools/cmake/convert_to_cmake.py` 中提供了一个项目自动转换工具。运行此命令时需要加上项目路径，如下所示:: - - $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir - -项目目录必须包含 Makefile 文件，并确保主机已安装 GNU Make (``make``) 工具，并且被添加到了 PATH 环境变量中。 - -该工具会将项目 Makefile 文件和所有组件的 ``component.mk`` 文件转换为对应的 ``CMakeLists.txt`` 文件。 - -转换过程如下：该工具首先运行 ``make`` 来展开 ESP-IDF 构建系统设置的变量，然后创建相应的 CMakelists 文件来设置相同的变量。 - -转换工具并不能处理复杂的 Makefile 逻辑或异常的目标，这些需要手动转换。 - -CMake 中不可用的功能 --------------------- - -有些功能已从 CMake 构建系统中移除，或者已经发生很大改变。GNU Make 构建系统中的以下变量已从 CMake 构建系统中删除： - -- ``COMPONENT_BUILD_DIR``：由 ``CMAKE_CURRENT_BINARY_DIR`` 替代。 -- ``COMPONENT_LIBRARY``：默认为 ``$(COMPONENT_NAME).a`` 但是库名可以被组件覆盖。在 CMake 构建系统中，组件库名称不可再被组件覆盖。 -- ``CC``、``LD``、``AR``、``OBJCOPY``：gcc xtensa 交叉工具链中每个工具的完整路径。CMake 使用 ``CMAKE_C_COMPILER``、``CMAKE_C_LINK_EXECUTABLE`` 和 ``CMAKE_OBJCOPY`` 进行替代。完整列表请参阅 `CMake 语言变量 `_。 -- ``HOSTCC``、``HOSTLD``、``HOSTAR``：宿主机本地工具链中每个工具的全名。CMake 系统不再提供此变量，外部项目需要手动检测所需的宿主机工具链。 -- ``COMPONENT_ADD_LDFLAGS``：用于覆盖链接标志。CMake 中使用 `target_link_libraries`_ 命令替代。 -- ``COMPONENT_ADD_LINKER_DEPS``：链接过程依赖的文件列表。`target_link_libraries`_ 通常会自动推断这些依赖。对于链接脚本，可以使用自定义的 CMake 函数 ``target_linker_scripts``。 -- ``COMPONENT_SUBMODULES``：不再使用。CMake 会自动枚举 ESP-IDF 仓库中所有的子模块。 -- ``COMPONENT_EXTRA_INCLUDES``：曾是 ``COMPONENT_PRIV_INCLUDEDIRS`` 变量的替代版本，仅支持绝对路径。CMake 系统中统一使用 ``COMPONENT_PRIV_INCLUDEDIRS`` （可以是相对路径，也可以是绝对路径）。 -- ``COMPONENT_OBJS``：以前，可以以目标文件列表的方式指定组件源，现在，可以通过 ``COMPONENT_SRCS`` 以源文件列表的形式指定组件源。 -- ``COMPONENT_OBJEXCLUDE``：已被 ``COMPONENT_SRCEXCLUDE`` 替换。用于指定源文件（绝对路径或组件目录的相对路径）。 -- ``COMPONENT_EXTRA_CLEAN``：已被 ``ADDITIONAL_MAKE_CLEAN_FILES`` 属性取代，注意，:ref:`CMake 对此项功能有部分限制 `。 -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 `_ 替代，详细内容请参阅 :ref:`component-build-full-override`。 -- ``COMPONENT_CONFIG_ONLY``：已被 ``register_config_only_component()`` 函数替代，请参阅 :ref:`config_only_component`。 -- ``CFLAGS``、``CPPFLAGS``、``CXXFLAGS``：已被相应的 CMake 命令替代，请参阅 :ref:`component_build_control`。 - -无默认值的变量 --------------- - -以下变量不再具有默认值： - -- ``COMPONENT_SRCDIRS`` -- ``COMPONENT_ADD_INCLUDEDIRS`` - -不再需要的变量 --------------- - -如果设置了 ``COMPONENT_SRCS``，就不需要再设置 ``COMPONENT_SRCDIRS``。实际上，CMake 构建系统中如果设置了 ``COMPONENT_SRCDIRS``，那么 ``COMPONENT_SRCS`` 就会被忽略。 - -从 Make 中烧录 --------------- - -仍然可以使用 ``make flash`` 或者类似的目标来构建和烧录，但是项目 ``sdkconfig`` 不能再用来指定串口和波特率。可以使用环境变量来覆盖串口和波特率的设置，详情请参阅 :ref:`flash-with-ninja-or-make`。 - -.. _esp-idf-template: https://github.com/espressif/esp-idf-template -.. _Cmake: https://cmake.org -.. _ninja: https://ninja-build.org -.. _esptool.py: https://github.com/espressif/esptool/#readme -.. _CMake v3.5 官方文档: https://cmake.org/cmake/help/v3.5/index.html -.. _cmake 命令行文档: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options -.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/add_library.html -.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html -.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html -.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html -.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html -.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html -.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F -.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html -.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html -.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages -.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html -.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html -.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries -.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html -.. _quirc: https://github.com/dlbeer/quirc -.. _pyenv: https://github.com/pyenv/pyenv#README -.. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/zh_CN/api-guides/build-system-legacy.rst b/docs/zh_CN/api-guides/build-system-legacy.rst new file mode 100644 index 000000000..cc7241005 --- /dev/null +++ b/docs/zh_CN/api-guides/build-system-legacy.rst @@ -0,0 +1,542 @@ +构建系统 (传统 GNU Make) +========================== +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +本文将介绍乐鑫物联网开发框架中的 ``构建系统`` 和 ``组件`` 的相关概念。 + +如果您想了解如何构建一个新的 ESP-IDF 项目，请阅读本文档。 + +我们建议您使用 `ESP-IDF 模板工程 `_ 来开始您的新项目。 + +使用构建系统 +------------ + +ESP-IDF 的 :idf_file:`README.md` 文件对如何使用构建系统来构建项目作了简要的说明。 + +概述 +---- + +一个 ESP-IDF 项目可以看作是许多不同组件的集合，例如对于一个展示当前湿度的网站服务器来说，它可能会包含如下一些组件： + +- ESP32 基础库（libc，rom bindings 等） +- WiFi 驱动库 +- TCP/IP 协议栈 +- FreeRTOS 操作系统 +- 网站服务器 +- 湿度传感器的驱动 +- 将上述组件组织在一起的主代码 + +ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，构建系统会查找 ESP-IDF 目录、项目目录和用户自定义目录（可选）中所有的组件，然后使用基于文本的菜单系统让用户配置 ESP-IDF 项目中需要的每个组件。在配置结束后，构建系统开始编译整个项目。 + +概念 +~~~~ + +- ``项目`` 特指一个目录，其中包含了构建可执行文件的所有源文件和配置，还有其他的支持型输出文件，比如分区表、数据/文件系统分区和引导程序。 + +- ``项目配置`` 保存在项目根目录下名为 sdkconfig 的文件中，它可以通过 ``make menuconfig`` 进行修改，且一个项目只能包含一个项目配置。 + +- ``应用程序`` 是由 ESP-IDF 构建得到的可执行文件。一个项目通常会构建两个应用程序：项目应用程序（主可执行文件，即用户自定义的固件）和引导程序（启动并初始化项目应用程序的引导程序）。 + +- ``组件`` 是模块化的、独立的代码，它们被编译成静态库（.a 文件）后再链接成应用程序，有些组件是 ESP-IDF 官方提供的，有些则可能来自其它项目。 + +以下内容并不是项目的组成部分： + +- ``ESP-IDF`` 并不是项目的一部分，相反，它是独立的，并通过 IDF_PATH 环境变量链接到项目中，这样做就可以使 IDF 框架与您的项目分离，其中 IDF_PATH 变量保存了 ESP-IDF 目录的路径。 + +- 交叉编译工具链并不是项目的组成部分，它应该被安装在系统 PATH 环境变量中，或者可以在项目配置中显式指定工具链的前缀为本地的安装路径。 + +示例项目 +~~~~~~~~ + +示例项目的目录树结构可能如下所示： + +.. code:: + + - myProject/ + - Makefile + - sdkconfig + - components/ - component1/ - component.mk + - Kconfig + - src1.c + - component2/ - component.mk + - Kconfig + - src1.c + - include/ - component2.h + - main/ - src1.c + - src2.c + - component.mk + - build/ + +该示例项目 ``myProject`` 包含以下组成部分： + +- 项目顶层 Makefile，该 Makefile 设置了 ``PROJECT_NAME`` 变量，还可以定义作用于整个项目的其它 make 变量（可选）。顶层 Makefile 会导入核心 Makefile 文件 ``$(IDF_PATH)/make/project.mk`` ，由它负责实现 ESP-IDF 构建系统的剩余部分。 + +- 项目配置文件 sdkconfig，执行 ``make menuconfig`` 后会创建或更新此文件，该文件中保存了项目中所有组件的配置信息（包括 ESP-IDF 本身）。``sdkconfig`` 文件可能会也可能不会被添加到项目的源代码管理系统中。 + +- 可选的组件目录中包含了属于项目一部分的自定义组件，不是每一个项目都需要它，但它有助于构建可重用代码或者导入第三方组件。 + +- ``main`` 目录是一个特殊的 ``伪组件``，它包含项目本身的源代码。``main`` 是默认名称，Makefile 变量 ``COMPONENT_DIRS`` 默认会导入此组件，但您也可以修改此变量（或者设置 ``EXTRA_COMPONENT_DIRS`` ）以查找其他位置的组件。 + +- ``build`` 目录在项目构建的时候创建或者更新，里面包含有构建生成的临时目标文件和库以及最终输出的二进制文件。此目录通常不会被添加到项目的源代码管理系统中，也不会随着项目源代码被发布。 + +组件目录中会包含组件自己的 Makefile 文件 ``component.mk`` ，里面会定义一些变量来控制该组件的构建过程，以及它与整个项目的集成。更多详细信息请参考 `组件 Makefiles <#component-makefiles>`_。 + +每个组件还可以包含一个 ``Kconfig`` 文件，它用于定义 ``menuconfig`` 时展示的组件配置信息的选项规则。某些组件还可能还会包含 ``Kconfig.projbuild`` 和 ``Makefile.projbuild`` 特殊文件，他们可以用来覆盖项目的部分配置。 + +项目 Makefiles +~~~~~~~~~~~~~~ + +每个项目都有一个 Makefile ，它包含整个项目的构建设置。默认情况下，项目 Makefile 可以非常小。 + +最小 Makefile 示例 +^^^^^^^^^^^^^^^^^^ + +.. code:: + + PROJECT_NAME := myProject + + include $(IDF_PATH)/make/project.mk + +必须设置的项目变量 +^^^^^^^^^^^^^^^^^^ + +- ``PROJECT_NAME``: 项目名称，最终输出的二进制文件也使用该名称，即 myProject.bin，myProject.elf 。 + +可选的项目变量 +^^^^^^^^^^^^^^ + +以下这些变量都有默认值，用户可以重写这些变量以自定义构建行为。查看 ``make/project.mk`` 文件可以获得所有的实现细节。 + +- ``PROJECT_PATH``： 顶层项目目录，默认是包含 Makefile 文件的目录，许多其他的项目变量都基于此变量。注意，项目路径中不能包含有空格。 +- ``BUILD_DIR_BASE``： 所有对象、库、二进制文件的输出目录，默认为 ``$(PROJECT_PATH)/build``。 +- ``COMPONENT_DIRS``： 组件的搜索目录，默认为 ``$(IDF_PATH)/components``，``$(PROJECT_PATH)/components``，``$(PROJECT_PATH)/main`` 和 ``EXTRA_COMPONENT_DIRS`` 。如果您不希望从这些目录中搜索组件，请重写此变量。 +- ``EXTRA_COMPONENT_DIRS``： 组件额外的搜索路径，可选。 +- ``COMPONENTS``： 要构建进项目中的组件列表，默认为 ``COMPONENT_DIRS`` 指定目录中所有的组件。 +- ``EXCLUDE_COMPONENTS``： 在构建的过程中需要剔除的组件列表，可选。请注意这只会减少构建的时间，并不会减少最终二进制文件的大小。 +- ``TEST_EXCLUDE_COMPONENTS``： 在构建单元测试的过程中需要剔除的组件列表，可选。 + +以上这些 Makefile 变量中的任何路径都要使用绝对路径，您可以使用 ``$(PROJECT_PATH)/xxx``，``$(IDF_PATH)/xxx``，或者使用 Make 内置函数 ``$(abspath xxx)`` 将相对路径转换为绝对路径。 + +以上这些变量要在 Makefile 中 ``include $(IDF_PATH)/make/project.mk`` 的前面进行设置。 + +.. _component-makefiles: + +组件 Makefiles +~~~~~~~~~~~~~~ + +每个项目都包含一个或者多个组件，这些组件可以是 ESP-IDF 的一部分，也可以从其他组件目录添加。 + +组件是包含 ``component.mk`` 文件的任何目录。 + +搜索组件 +~~~~~~~~ + +搜索 ``COMPONENT_DIRS`` 中指定的目录以查找项目会使用的组件，目录可以是组件本身（即他们包含 ``component.mk`` 文件），也可以是包含组件的上层目录。 + +运行 ``make list-components`` 命令可以查询这些变量的值，这有助于调试组件的搜索路径是否正确。 + +同名组件 +^^^^^^^^ + +ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进行，这意味着在默认情况下，首先是 ESP-IDF 组件，然后是项目组件，最后是 ``EXTRA_COMPONENT_DIRS`` 中的组件。如果这些目录中的两个或者多个包含具有相同名字的组件，则使用搜索到的最后一个位置的组件。这就允许将组件复制到项目目录中再修改来覆盖 ESP-IDF 组件，如果使用这种方式，ESP-IDF 目录本身可以保持不变。 + +.. _minimal-component-makefile: + +最小组件 Makefile +^^^^^^^^^^^^^^^^^ + +最简单的 ``component.mk`` 文件可以是一个空文件，如果文件为空，则组件的默认构建行为会被设置为： + +- makefile 所在目录中的所有源文件（``*.c``，``*.cpp``，``*.cc``，``*.S``）将会被编译进组件库中。 +- 子目录 ``include`` 将被添加到其他组件的全局头文件搜索路径中。 +- 组件库将会被链接到项目的应用程序中。 + +更完整的组件 makefile 可以查看 `组件 Makefile 示例 <#example-component-makefile>`_。 + +请注意，空的 ``component.mk`` 文件同没有 ``component.mk`` 文件之间存在本质差异，前者会调用默认的组件构建行为，后者不会发生默认的组件构建行为。一个组件中如果只包含影响项目配置或构建过程的文件，那么它可以没有 ``component.mk`` 文件。 + +.. _preset-component-variables: + +预设的组件变量 +^^^^^^^^^^^^^^ + +以下特定于组件的变量可以在 ``component.mk`` 中使用，但不应该被修改。 + +- ``COMPONENT_PATH``： 组件的目录，即包含 ``component.mk`` 文件的绝对路径，路径中不能包含空格。 +- ``COMPONENT_NAME``： 组件的名字，默认为组件目录的名称。 +- ``COMPONENT_BUILD_DIR``： 组件的构建目录，即存放组件构建输出的绝对路径，它是 `$(BUILD_DIR_BASE)` 的子目录。该变量也是构建组件时的当前工作目录，所以 make 中的相对路径都以此目录为基础。 +- ``COMPONENT_LIBRARY``： 组件构建后的静态库文件（相对于组件的构建目录）的名字，默认为 ``$(COMPONENT_NAME).a``。 + +以下变量在项目顶层中设置，并被导出到组件中构建时使用： + +- ``PROJECT_NAME``： 项目名称，在项目的 Makefile 中设置。 +- ``PROJECT_PATH``： 包含项目 Makefile 的目录的绝对路径。 +- ``COMPONENTS``： 此次构建中包含的所有组件的名字。 +- ``CONFIG_*``： 项目配置中的每个值在 make 中都对应一个以 ``CONFIG_`` 开头的变量。 +- ``CC``，``LD``，``AR``，``OBJCOPY``： gcc xtensa 交叉编译工具链中每个工具的完整路径。 +- ``HOSTCC``，``HOSTLD``，``HOSTAR``： 主机本地工具链中每个工具的全名。 +- ``IDF_VER``： ESP-IDF 的版本号，可以通过检索 ``$(IDF_PATH)/version.txt`` 文件（假如存在的话）或者使用 git 命令 ``git describe`` 来获取。这里推荐的格式是在一行中指定主 IDF 的发布版本号，例如标记为 ``v2.0`` 的发布版本或者是标记任意一次提交记录的 ``v2.0-275-g0efaa4f``。应用程序可以通过调用 :cpp:func:`esp_get_idf_version` 函数来使用该变量。 +- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: ESP-IDF 的组件版本，可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量，版本号 ``v4.0-dev-*``， ``v4.0-beta1``， ``v4.0-rc1`` 和 ``v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的，但是 ``IDF_VER`` 的值是不同的。 + +如果您在 ``component.mk`` 文件中修改这些变量，这并不会影响其它组件的构建，但可能会使您的组件变得难以构建或调试。 + +.. _optional-project-wide-component-variables: + +可选的项目通用组件变量 +^^^^^^^^^^^^^^^^^^^^^^ + +可以在 ``component.mk`` 中设置以下变量来控制整个项目的构建行为： + +- ``COMPONENT_ADD_INCLUDEDIRS``： 相对于组件目录的路径，将被添加到项目中所有组件的头文件搜索路径中。如果该变量未被覆盖，则默认为 ``include`` 目录。如果一个头文件路径仅仅为当前组件所用，那么应该将该路径添加到 ``COMPONENT_PRIV_INCLUDEDIRS`` 中。 +- ``COMPONENT_ADD_LDFLAGS``： 添加链接参数到全局 ``LDFLAGS`` 中用以指导链接最终的可执行文件，默认为 ``-l$(COMPONENT_NAME)``。如果将预编译好的库添加到此目录，请使用它们为绝对路径，即 ``$(COMPONENT_PATH)/libwhatever.a``。 +- ``COMPONENT_DEPENDS``： 需要在当前组件之前构建的组件列表，这对于处理链接时的依赖不是必需的，因为所有组件的头文件目录始终可用。如果一个组件会生成一个头文件，然后另外一个组件需要使用它，此时该变量就有必要进行设置。大多数的组件不需要设置此变量。 +- ``COMPONENT_ADD_LINKER_DEPS``： 保存一些文件的路径，当这些文件发生改变时，会触发 ELF 文件重新链接。该变量通常用于链接脚本文件和二进制文件，大多数的组件不需要设置此变量。 + +以下变量仅适用于属于 ESP-IDF 的组件： + +- ``COMPONENT_SUBMODULES``： 组件使用的 git 子模块的路径列表（相对于 ``COMPONENT_PATH``）。这些路径会在构建的过程中被检查（并在必要的时候初始化）。如果组件位于 ``IDF_PATH`` 目录之外，则忽略此变量。 + + +可选的组件特定变量 +^^^^^^^^^^^^^^^^^^ + +以下变量可以在 ``component.mk`` 中进行设置，用以控制该组件的构建行为： + +- ``COMPONENT_PRIV_INCLUDEDIRS``： 相对于组件目录的目录路径，该目录仅会被添加到该组件源文件的头文件搜索路径中。 +- ``COMPONENT_EXTRA_INCLUDES``： 编译组件的源文件时需要指定的额外的头文件搜索路径，这些路径将以 ``-l`` 为前缀传递给编译器。这和 ``COMPONENT_PRIV_INCLUDEDIRS`` 变量的功能有些类似，但是这些路径不会相对于组件目录进行扩展。 +- ``COMPONENT_SRCDIRS``： 相对于组件目录的目录路径，这些路径用于搜索源文件（``*.cpp``，``*.c``，``*.S``），默认为 ``.``，即组件目录本身。重写该变量可以指定包含源文件的不同目录列表。 +- ``COMPONENT_OBJS``： 要编译生成的目标文件，默认是 ``COMPONENT_SRCDIRS`` 中每个源文件的 .o 文件。重写该变量将允许您剔除 ``COMPONENT_SRCDIRS`` 中的某些源文件，否则他们将会被编译。相关示例请参阅 `指定需要编译的组件源文件 <#specify-source-files>`_。 +- ``COMPONENT_EXTRA_CLEAN``： 相对于组件构建目录的路径，指向 ``component.mk`` 文件中自定义 make 规则生成的任何文件，它们也是 ``make clean`` 命令需要删除的文件。相关示例请参阅 `源代码生成 <#source-code-generation>`_。 +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``： 这些目标允许您完全覆盖组件的默认编译行为。有关详细信息，请参阅 `完全覆盖组件的 Makefile <#fully-overriding-component-makefile-legacy>`_。 +- ``COMPONENT_CONFIG_ONLY``： 如果设置了此标志，则表示组件根本不会产生构建输出（即不会构建得到 ``COMPONENT_LIBRARY``），并且会忽略大多数其它组件变量。此标志用于 IDF 内部组件，其中仅包含 ``KConfig.projbuild`` 和/或 ``Makefile.projbuild`` 文件来配置项目，但是没有源文件。 +- ``CFLAGS``： 传递给 C 编译器的标志。根据项目设置已经定义一组默认的 ``CFLAGS``，可以通过 ``CFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。 +- ``CPPFLAGS``： 传递给 C 预处理器的标志（用于 ``.c``，``.cpp`` 和 ``.S`` 文件）。根据项目设置已经定义一组默认的 ``CPPFLAGS`` ，可以通过 ``CPPFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。 +- ``CXXFLAGS``： 传递给 C++ 编译器的标志。根据项目设置已经定义一组默认的 ``CXXFLAGS`` ，可以通过 ``CXXFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。 + +如果要将编译标志应用于单个源文件，您可以将该源文件的目标规则覆盖，例如： + +.. code:: makefile + + apps/dhcpserver.o: CFLAGS += -Wno-unused-variable + +如果上游代码在编译的时候发出了警告，那这么做可能会很有效。 + +配置组件 +~~~~~~~~ + +每个组件都可以包含一个 Kconfig 文件，和 ``component.mk`` 放在同一个目录下。Kconfig 中包含此组件在 ``make menuconfig`` 时要展示的配置规则的设置。 + +运行 menuconfig 时，可以在 ``Component Settings`` 菜单栏下找到这些设置。 + +创建一个组件的 Kconfig 文件，最简单的方法就是使用 ESP-IDF 中现有的 Kconfig 文件作为模板，在这基础上进行修改。 + +有关示例请参阅 `添加条件配置 <#add-conditional-configuration>`_。 + +预处理器定义 +~~~~~~~~~~~~ + +ESP-IDF 构建系统会在命令行中添加以下 C 预处理定义： + +- ``ESP_PLATFORM`` — 可以用来检测在 ESP-IDF 内发生的构建行为。 +- ``IDF_VER`` — ESP-IDF 的版本，请参阅 `预设的组件变量 <#preset-component-variables>`_。 + +构建的内部过程 +~~~~~~~~~~~~~~ + +顶层：项目 Makefile +^^^^^^^^^^^^^^^^^^^ + +- ``make`` 始终从项目目录处运行，并且项目的 makefile 名字通常为 Makefile 。 +- 项目的 makefile 文件会设置 ``PROJECT_NAME`` ，并且可以自定义其他可选的项目变量。 +- 项目 makefile 文件会导入 ``$(IDF_PATH)/make/project.mk`` ，该文件中会导入项目级的 Make 逻辑。 +- ``project.mk`` 填写默认的项目级 make 变量，并导入项目配置中的 make 变量。如果生成的包含项目配置的 makefile 文件已经过期，那么它将会被重新生成（通过 ``project_config.mk`` 中的目标规则），然后 make 进程从顶层重新开始。 +- ``project.mk`` 根据默认组件目录或者可选项目变量中设置的自定义组件列表来编译组件。 +- 每个组件都可以设置一些 `可选的项目通用组件变量 <#optional-project-wide-component-variables>`_ ，他们会通过 ``component_project_vars.mk`` 被导入 ``project.mk`` 文件中。如果这些文件有缺失或者过期，他们会被重新生成（通过对组件 makefile 的递归调用），然后 make 进程从顶层重新开始。 +- 组件中的 Makefile.projbuild 文件被包含在了 make 的进程中，以添加额外的目标或者配置。 +- 默认情况下，项目 makefile 还为每个组件生成顶层的编译和清理目标，并设置 app 和 clean 目标来调用所有这些子目标。 +- 为了编译每个组件，对组件 makefile 执行递归构建。 + +为了更好地理解项目的构建过程，请通读 ``project.mk`` 文件。 + +第二层：组件 Makefile 文件 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- 每次调用组件 makefile 文件都是通过 ``$(IDF_PATH)/make/component_wrapper.mk`` 这个包装器进行的。 +- 此组件包装器包含了所有组件的 ``Makefile.componentbuild`` 文件，使这些文件中的任何配置，变量都可用于每个组件。 +- 调用 ``component_wrapper.mk`` 时将当前目录设置为组件构建目录，并将 ``COMPONENT_MAKEFILE`` 变量设置为 ``component.mk`` 的绝对路径。 +- ``component_wrapper.mk`` 为所有组件变量设置默认值，然后导入 ``component.mk`` 文件来覆盖或修改这些变量。 +- 如果未定义 ``COMPONENT_OWNBUILDTARGET`` 和 ``COMPONENT_OWNCLEANTARGET`` 文件，则会为组件的源文件和必备组件 ``COMPONENT_LIBRARY`` 静态库文件创建默认构建和清理目标。 +- ``component_project_vars.mk`` 文件在 ``component_wrapper.mk`` 中有自己的目标，如果由于组件的 makefile 或者项目配置的更改而需要重建此文件，则从 ``project.mk`` 文件中进行评估。 + +为了更好地理解组件制作过程，请阅读 ``component_wrapper.mk`` 文件和 ESP-IDF 中的 ``component.mk`` 文件。 + +以非交互的方式运行 Make +~~~~~~~~~~~~~~~~~~~~~~~ + +如果在运行 ``make`` 的时候不希望出现交互式提示（例如：在IDE或自动构建系统中），可以将 ``BATCH_BUILD=1`` 添加到make的参数中（或者将其设置为环境变量）。 + +设置 ``BATCH_BUILD`` 意味着： + +- 详细输出（与 ``V=1`` 相同，见下文），如果不需要详细输出，就设置 ``V=0`` 。 +- 如果项目配置缺少新配置项（来自新组件或者 ESP-IDF 更新），则项目使用默认值，而不是提示用户输入每个项目。 +- 如果构建系统需要调用 ``menuconfig`` ，则会打印错误并且构建失败。 + +.. _make-size: + +构建目标的进阶用法 +~~~~~~~~~~~~~~~~~~ + +- ``make app``，``make bootloader``，``make partition table`` 可以根据需要为项目单独构建生成应用程序文件、启动引导文件和分区表文件。 +- ``make erase_flash`` 和 ``make erase_ota`` 会调用 esptool.py 脚本分别擦除整块闪存芯片或者其中 OTA 分区的内容。 +- ``make size`` 会打印应用程序的大小信息。``make size-components`` 和 ``make size-files`` 两者功能相似，分别打印每个组件或者每个源文件大小的详细信息。 + +调试 Make 的过程 +~~~~~~~~~~~~~~~~ + +调试 ESP-IDF 构建系统的一些技巧： + +- 将 ``V=1`` 添加到 make 的参数中（或将其设置为环境变量）将使 make 回显所有已经执行的命令，以及为子 make 输入的每个目录。 +- 运行 ``make -w`` 将导致 make 在为子 make 输入时回显每个目录——与 ``V=1`` 相同但不回显所有命令。 +- 运行 ``make --trace`` （可能除了上述参数之一）将打印出构建时的每个目标，以及导致它构建的依赖项）。 +- 运行 ``make -p`` 会打印每个 makefile 中每个生成的目标的（非常详细的）摘要。 + +更多调试技巧和通用的构建信息，请参阅 `GNU 构建手册 `_。 + +.. _warn-undefined-variables-legacy: + +警告未定义的变量 +^^^^^^^^^^^^^^^^ + +默认情况下，如果引用了未定义的变量（如 ``$(DOES_NOT_EXIST)`` ，构建过程将会打印警告，这对于查找变量名称中的错误非常有用。 + +如果不想要此行为，可以在 menuconfig 顶层菜单下的 `SDK tool configuration` 中禁用它。 + +请注意，如果在 Makefile 中使用 ``ifdef`` 或者 ``ifndef`` ，则此选项不会出发警告。 + +覆盖项目的部分内容 +~~~~~~~~~~~~~~~~~~ + +Makefile.projbuild +^^^^^^^^^^^^^^^^^^ + +如果一个组件含有必须要在项目构建过程的顶层进行计算的变量，则可以在组件目录下创建名为 ``Makefile.projbuild`` 的文件，项目在执行 ``project.mk`` 的时候会导入此 makefile 。 + +例如，如果您的组件需要为整个项目添加 CFLAGS（不仅仅是为自身的源文件），那么可以在 ``Makefile.projbuild`` 中设置 ``CFLAGS +=`` 。 + +``Makefile.projbuild`` 文件在 ESP-IDF 中大量使用，用于定义项目范围的构建功能，例如 ``esptool.py`` 命令行参数和 ``bootloader`` 这个特殊的程序。 + +请注意， ``Makefile.projbuild`` 对于最常见的组件不是必需的 - 例如向项目中添加 include 目录，或者将 LDFLAGS 添加到最终链接步骤，同样可以通过 ``component.mk`` 文件来自定义这些值。有关详细信息，请参阅 `可选的项目通用组件变量 <#optional-project-wide-component-variables>`_ 。 + +.. warning:: + + 在此文件中设置变量或者目标时要小心，由于这些值包含在项目的顶层 makefile 中，因此他们可以影响或者破坏所有组件的功能！ + +KConfig.projbuild +^^^^^^^^^^^^^^^^^ + +这相当于 ``Makefile.projbuild`` 的组件配置 KConfig 文件，如果要在 menuconfig 的顶层添加配置选项，而不是在 ``组件配置`` 子菜单中，则可以在 ``component.mk`` 文件所在目录中的 KConfig.projbuild 文件中定义这些选项。 + +在此文件中添加配置时要小心，因为他们将包含在整个项目配置中，在可能的情况下，通常最好为组件创建和配置 KConfig 文件。 + +Makefile.componentbuild +^^^^^^^^^^^^^^^^^^^^^^^ + +对于一些特殊的组件，比如它们会使用工具从其余文件中生成源文件，这时就有必要将配置、宏或者变量的定义添加到每个组件的构建过程中。这是通过在组件目录中包含 ``Makefile.componentbuild`` 文件来实现的。此文件在 ``component.mk`` 文件之前被导入 ``component_wrapper.mk`` 中。同 ``Makefile.projbuild`` 文件一样，请留意这些文件，因为他们包含在每个组件的构建中，所有只有在编译完全不同的组件时才会出现 ``Makefile.componentbuild`` 错误。 + +仅配置的组件 +^^^^^^^^^^^^ + +仅配置的组件是一类不包含源文件的特殊组件，只有 ``Kconfig.projbuild`` 和 ``Makefile.projbuild`` 文件，可以在 ``conponent.mk`` 文件中设置标志 ``COMPONENT_CONFIG_ONLY``。如果设置了此标志，则忽略大多数其他组件变量，并且不会为组件执行构建操作。 + +.. _example-component-makefile-legacy: + +组件 Makefile 示例 +~~~~~~~~~~~~~~~~~~ + +因为构建环境试图设置大多数情况都能工作的合理默认值，所以 ``component.mk`` 可能非常小，甚至是空的，请参考 `最小组件 Makefile <#minimal-component-makefile>`_。但是某些功能通常需要覆盖组件的变量。 + +以下是 ``component.mk`` 的一些更高级的示例： + +增加源文件目录 +^^^^^^^^^^^^^^ + +默认情况下，将忽略子目录。如果您的项目在子目录中而不是在组件的根目录中有源文件，那么您可以通过设置 ``COMPONENT_SRCDIRS`` 将其告知构建系统： + +.. code:: + + COMPONENT_SRCDIRS := src1 src2 + +构建系统将会编译 src1/ 和 src2/ 子目录中的所有源文件。 + +.. _specify-source-files-legacy: + +指定源文件 +^^^^^^^^^^ + +标准 ``component.mk`` 逻辑将源目录中的所有 .S 和 .c 文件添加为无条件编译的源。通过将 ``COMPONENT_OBJS`` 变量手动设置为需要生成的对象的名称，可以绕过该逻辑并对要编译的对象进行硬编码。 + +.. code:: + + COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o + COMPONENT_SRCDIRS := . thing anotherthing + +请注意，还需要另外设置 ``COMPONENT_SRCDIRS`` 。 + +.. _add-conditional-configuration-legacy: + +添加条件配置 +^^^^^^^^^^^^ + +配置系统可用于有条件地编译某些文件，具体取决于 ``make menuconfig`` 中选择的选项。为此，ESP-IDF 具有 ``compile_only_if`` 和 ``compile_only_if_not`` 的宏： + +``Kconfig``: + +.. code:: + + config FOO_ENABLE_BAR + bool "Enable the BAR feature." + help + This enables the BAR feature of the FOO component. + +``component.mk``: + +.. code:: + + $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) + +从示例中可以看出， ``compile_only_if`` 宏将条件和目标文件列表作为参数。如果条件为真（在这种情况下：如果在 menuconfig 中启用了 BAR 功能），将始终编译目标文件（在本例中为 bar.o）。相反的情况也是如此，如果条件不成立，bar.o 将永远不会被编译。 ``compile_only_if_not`` 执行相反的操作，如果条件为 false 则编译，如果条件为 true 则不编译。 + +这也可以用于选择或者删除实现，如下所示： + +``Kconfig``: + +.. code:: + + config ENABLE_LCD_OUTPUT + bool "Enable LCD output." + help + Select this if your board has a LCD. + + config ENABLE_LCD_CONSOLE + bool "Output console text to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output debugging output to the lcd + + config ENABLE_LCD_PLOT + bool "Output temperature plots to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output temperature plots + +``component.mk``: + +.. code:: + + # If LCD is enabled, compile interface to it, otherwise compile dummy interface + $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o) + $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o) + + #We need font if either console or plot is enabled + $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) + +请注意使用 Make 或者函数来包含字体文件。其他的替换函数，比如 ``and`` 和 ``if`` 也适用于此处。也可以使用不在 menuconfig 中定义的变量，ESP-IDF 使用默认的 Make 策略，将一个空的或者只包含空格的变量视为 false ，而其中任何非空格的比那辆都为 true 。 + +（注意：本文档的历史版本建议将目标文件添加到 ``COMPONENT_OBJS`` 中，虽然这仍然可行，但是只有当组件中的所有目标文件都明确命名时才会起作用，并且在 ``make clean`` 后并不会清除 make 中取消选择的目标文件）。 + +.. _source-code-generation-legacy: + +源代码生成 +^^^^^^^^^^ + +某些组件会出现源文件未随组件本身提供，而必须从另外一个文件生成的情况。假设我们的组件有一个头文件，该文件由 BMP 文件转换后的二进制数据组成，假设使用 bmp2h 的工具进行转换，然后将头文件包含在名为 graphics_lib.c 的文件中： + +.. code:: + + COMPONENT_EXTRA_CLEAN := logo.h + + graphics_lib.o: logo.h + + logo.h: $(COMPONENT_PATH)/logo.bmp + bmp2h -i $^ -o $@ + +这个示例会在当前目录（构建目录）中生成 graphics_lib.o 和 logo.h 文件，而 logo.bmp 随组件一起提供并位于组件路径下。因为 logo.h 是一个生成的文件，所以当调用 ``make clean`` 时需要清理它，这就是为什么要将它添加到 ``COMPONENT_EXTRA_CLEAN`` 变量中。 + +润色与改进 +^^^^^^^^^^ + +将 logo.h 添加作为 ``graphics_lib.o`` 的依赖项会导致在编译 ``graphics_lib.c`` 之前先生成它。 + +如果另一个组件中的源文件需要使用 logo.h，则必须将此组件的名称添加到另一个组件的 ``COMPONENT_DEPENDS`` 列表中，以确保组件按顺序编译。 + +嵌入二进制数据 +^^^^^^^^^^^^^^ + +有时您的组件希望使用一个二进制文件或者文本文件，但是您又不希望将它重新格式化为 C 源文件。 + +这时，您可以在 ``component.mk`` 文件中设置变量 ``COMPONENT_EMBED_FILES``，以这种方式指定要嵌入的文件的名称： + +.. code:: + + COMPONENT_EMBED_FILES := server_root_cert.der + +或者，如果文件是字符串，则可以使用变量 ``COMPONENT_EMBED_TXTFILES``，这将把文本文件的内容当成以 null 结尾的字符串嵌入： + +.. code:: + + COMPONENT_EMBED_TXTFILES := server_root_cert.pem + +文件的内容会被编译进 flash 中的 .rodata 段，并通过符号名称来访问，如下所示： + +.. code:: c + + extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); + extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); + +符号名称是根据文件的全名生成的，如 ``COMPONENT_EMBED_FILES`` 中的所示，字符 / ， . ， 等都将会被下划线替代。符号名称中的 ``_binary`` 前缀由 ``objcopy`` 添加，对于文本和二进制文件都是相同的。 + +有关使用此技术的示例，请参考 :example:`protocols/https_request` - 证书文件的内容会在编译时从 .pem 文件中加载。 + +.. _fully-overriding-component-makefile: + +完全覆盖组件的 Makefile +~~~~~~~~~~~~~~~~~~~~~~~ + +显然，在某些情况下，所有这些配置都不足以满足某个组件，例如，当组件基本上是另一个第三方组件的包装器时，该第三方组件最初不打算在 ESP-IDF 构建系统下工作，在这种情况下，可以通过设置 ``COMPONENT_OWNBUILDTARGET`` 和可能的 ``COMPONENT_OWNCLEANTARGET``，并在 ``component.mk`` 中定义名为 ``build`` 和 ``clean`` 的目标。构建目标可以执行任何操作，只要它为项目生成了 ``$(COMPONENT_LIBRARY)`` ，并最终被链接到应用程序二进制文件中即可。 + +（实际上，这并不是必须的 - 如果 ``COMPONENT_ADD_LDFLAGS`` 变量被覆盖，那么组件可以指示链接器链接其他二进制文件。） + +.. _custom-sdkconfig-defaults-legacy: + +自定义 sdkconfig 的默认值 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +对于示例工程或者其他您不想指定完整 sdkconfig 配置的项目，但是您确实希望覆盖 ESP-IDF 默认值中的某些键值，则可以在项目中创建文件 ``sdkconfig.defaults``,运行 ``make defconfig`` 或从头创建新配置时将会使用此文件。 + +要想覆盖此文件的名称，请设置 ``SDKCONFIG_DEFAULTS`` 环境变量。 + +保存 flash 参数 +~~~~~~~~~~~~~~~ + +在某些情况下，我们希望在没有 IDF 的情况下烧写目标板卡，对于这种情况，我们希望保存构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以简单编写一段脚本来保存二进制文件和 esptool.py，并且使用命令 ``make print_flash_cmd`` 来查看烧写 flash 时的参数。 + +.. code:: bash + + --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin + +然后使用这段 flash 参数作为 esptool write_flash 命令的参数： + +.. code:: bash + + python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin + +构建 Bootloader +--------------- + +引导程序默认作为 ``make all`` 的一部分被构建，或者也可以通过 ``make bootloader-clean`` 来单独构建，此外还可以通过 ``make bootloader-list-components`` 来查看构建引导程序时包含的组件。 + +引导程序是一个特殊的组件，因为主项目中的二级引导程序拥有单独的 .EFL 和 .BIN 文件。但是它与主项目共享配置和构建目录。 + +这是通过在 components/bootloader/subproject 下添加子项目来完成的。这个子项目有自己的 Makefile，但它希望通过 components/bootloader/Makefile.projectbuild 文件中的一些配置使自己从主项目的 Makefile 被调用。有关详细信息，请参阅这些文件。 diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 60bba24ef..e9616ec0c 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -1,540 +1,1079 @@ -构建系统 -======== +构建系统（CMake 版） +******************** :link_to_translation:`en:[English]` -本文将介绍乐鑫物联网开发框架中的 ``构建系统`` 和 ``组件`` 的相关概念。 +本文档将介绍基于 CMake 的 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念，此外 ESP-IDF 还支持 :doc:`基于 GNU Make 的构建系统 `。 -如果您想了解如何构建一个新的 ESP-IDF 项目，请阅读本文档。 - -我们建议您使用 `ESP-IDF 模板工程 `_ 来开始您的新项目。 - -使用构建系统 ------------- - -ESP-IDF 的 :idf_file:`README.md` 文件对如何使用构建系统来构建项目作了简要的说明。 +如需您想了解如何使用 CMake 构建系统来组织和构建新的 ESP-IDF 项目或组件，请阅读本文档。 概述 ----- +==== -一个 ESP-IDF 项目可以看作是许多不同组件的集合，例如对于一个展示当前湿度的网站服务器来说，它可能会包含如下一些组件： +一个 ESP-IDF 项目可以看作是多个不同组件的集合，例如一个显示当前湿度的网页服务器会包含以下组件： -- ESP32 基础库（libc，rom bindings 等） -- WiFi 驱动库 -- TCP/IP 协议栈 -- FreeRTOS 操作系统 -- 网站服务器 -- 湿度传感器的驱动 -- 将上述组件组织在一起的主代码 +- ESP32 基础库，包括 libc、ROM bindings 等 +- Wi-Fi 驱动 +- TCP/IP 协议栈 +- FreeRTOS 操作系统 +- 网页服务器 +- 湿度传感器的驱动 +- 负责将上述组件整合到一起的主程序 -ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，构建系统会查找 ESP-IDF 目录、项目目录和用户自定义目录（可选）中所有的组件，然后使用基于文本的菜单系统让用户配置 ESP-IDF 项目中需要的每个组件。在配置结束后，构建系统开始编译整个项目。 +ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，构建系统会前往 ESP-IDF 目录、项目目录和用户自定义目录（可选）中查找所有组件，允许用户通过文本菜单系统配置 ESP-IDF 项目中用到的每个组件。在所有组件配置结束后，构建系统开始编译整个项目。 概念 -~~~~ +---- -- ``项目`` 特指一个目录，其中包含了构建可执行文件的所有源文件和配置，还有其他的支持型输出文件，比如分区表、数据/文件系统分区和引导程序。 +- ``项目`` 特指一个目录，其中包含了构建可执行应用程序所需的全部文件和配置，以及其他支持型文件，例如分区表、数据/文件系统分区和引导程序。 +- ``项目配置`` 保存在项目根目录下名为 ``sdkconfig`` 的文件中，可以通过 ``idf.py menuconfig`` 进行修改，且一个项目只能包含一个项目配置。 +- ``应用程序`` 是由 ESP-IDF 构建得到的可执行文件。一个项目通常会构建两个应用程序：项目应用程序（可执行的主文件，即用户自定义的固件）和引导程序（启动并初始化项目应用程序）。 +- ``组件`` 是模块化且独立的代码，会被编译成静态库（.a 文件）并链接到应用程序。部分组件由 ESP-IDF 官方提供，其他组件则来源于其它开源项目。 +- ``目标`` 特指运行构建后应用程序的硬件设备。ESP-IDF 当前仅支持 ``ESP32`` 这一个硬件目标。 -- ``项目配置`` 保存在项目根目录下名为 sdkconfig 的文件中，它可以通过 ``make menuconfig`` 进行修改，且一个项目只能包含一个项目配置。 +请注意，以下内容并不属于项目的组成部分： -- ``应用程序`` 是由 ESP-IDF 构建得到的可执行文件。一个项目通常会构建两个应用程序：项目应用程序（主可执行文件，即用户自定义的固件）和引导程序（启动并初始化项目应用程序的引导程序）。 +- ``ESP-IDF`` 并不是项目的一部分，它独立于项目，通过 ``IDF_PATH`` 环境变量（保存 ``esp-idf`` 目录的路径）链接到项目，从而将 IDF 框架与项目分离。 +- 交叉编译工具链并不是项目的组成部分，它应该被安装在系统 PATH 环境变量中。 -- ``组件`` 是模块化的、独立的代码，它们被编译成静态库（.a 文件）后再链接成应用程序，有些组件是 ESP-IDF 官方提供的，有些则可能来自其它项目。 +使用构建系统 +============ -以下内容并不是项目的组成部分： +.. _idf.py: -- ``ESP-IDF`` 并不是项目的一部分，相反，它是独立的，并通过 IDF_PATH 环境变量链接到项目中，这样做就可以使 IDF 框架与您的项目分离，其中 IDF_PATH 变量保存了 ESP-IDF 目录的路径。 +idf.py +------ -- 交叉编译工具链并不是项目的组成部分，它应该被安装在系统 PATH 环境变量中，或者可以在项目配置中显式指定工具链的前缀为本地的安装路径。 +``idf.py`` 命令行工具提供了一个前端，可以帮助您轻松管理项目的构建过程，它管理了以下工具： -示例项目 -~~~~~~~~ +- CMake_，配置待构建的系统 +- 命令行构建工具（Ninja_ 或 `GNU Make`） +- `esptool.py`_，烧录 ESP32 -示例项目的目录树结构可能如下所示： +:ref:`入门指南 ` 简要介绍了如何设置 ``idf.py`` 用于配置、构建并烧录项目。 -.. code:: +``idf.py`` 应运行在 ESP-IDF 的 ``项目`` 目录下，即包含 ``CMakeLists.txt`` 文件的目录。仅包含 Makefile 的老式项目并不支持 ``idf.py``。 - - myProject/ - - Makefile - - sdkconfig - - components/ - component1/ - component.mk - - Kconfig - - src1.c - - component2/ - component.mk - - Kconfig - - src1.c - - include/ - component2.h - - main/ - src1.c - - src2.c - - component.mk - - build/ +运行 ``idf.py --help`` 查看完整的命令列表。下面总结了最常用的命令： -该示例项目 ``myProject`` 包含以下组成部分： +- ``idf.py menuconfig`` 会运行 ``menuconfig`` 工具来配置项目。 +- ``idf.py build`` 会构建在当前目录下找到的项目，它包括以下步骤： -- 项目顶层 Makefile，该 Makefile 设置了 ``PROJECT_NAME`` 变量，还可以定义作用于整个项目的其它 make 变量（可选）。顶层 Makefile 会导入核心 Makefile 文件 ``$(IDF_PATH)/make/project.mk`` ，由它负责实现 ESP-IDF 构建系统的剩余部分。 + - 根据需要创建 ``build`` 构建目录，它用于保存构建过程的输出文件，可以使用 ``-B`` 选项修改默认的构建目录。 + - 根据需要运行 CMake_ 配置命令，为主构建工具生成构建文件。 + - 运行主构建工具（Ninja_ 或 `GNU Make`）。默认情况下，构建工具会被自动检测，可以使用 ``-G`` 选项显式地指定构建工具。 -- 项目配置文件 sdkconfig，执行 ``make menuconfig`` 后会创建或更新此文件，该文件中保存了项目中所有组件的配置信息（包括 ESP-IDF 本身）。``sdkconfig`` 文件可能会也可能不会被添加到项目的源代码管理系统中。 + 构建过程是增量式的，如果自上次构建以来源文件或项目配置没有发生改变，则不会执行任何操作。 -- 可选的组件目录中包含了属于项目一部分的自定义组件，不是每一个项目都需要它，但它有助于构建可重用代码或者导入第三方组件。 +- ``idf.py clean`` 会把构建输出的文件从构建目录中删除，从而清理整个项目。下次构建时会强制“重新完整构建”这个项目。清理时，不会删除 CMake 配置输出及其他文件。 +- ``idf.py fullclean`` 会将整个 ``build`` 目录下的内容全部删除，包括所有 CMake 的配置输出文件。下次构建项目时，CMake 会从头开始配置项目。请注意，该命令会递归删除构建目录下的 *所有文件*，请谨慎使用。项目配置文件不会被删除。 +- ``idf.py flash`` 会在必要时自动构建项目，并将生成的二进制程序烧录进 ESP32 设备中。``-p`` 和 ``-b`` 选项可分别设置串口的设备名和烧录时的波特率。 +- ``idf.py monitor`` 用于显示 ESP32 设备的串口输出。``-p`` 选项可用于设置主机端串口的设备名，按下 ``Ctrl-]`` 可退出监视器。更多有关监视器的详情，请参阅 :doc:`tools/idf-monitor`。 -- ``main`` 目录是一个特殊的 ``伪组件``，它包含项目本身的源代码。``main`` 是默认名称，Makefile 变量 ``COMPONENT_DIRS`` 默认会导入此组件，但您也可以修改此变量（或者设置 ``EXTRA_COMPONENT_DIRS`` ）以查找其他位置的组件。 +多个 ``idf.py`` 命令可合并成一个，例如，``idf.py -p COM4 clean flash monitor`` 会依次清理源码树，构建项目，烧录进 ESP32 设备，最后运行串口监视器。 -- ``build`` 目录在项目构建的时候创建或者更新，里面包含有构建生成的临时目标文件和库以及最终输出的二进制文件。此目录通常不会被添加到项目的源代码管理系统中，也不会随着项目源代码被发布。 +.. Note:: 环境变量 ``ESPPORT`` 和 ``ESPBAUD`` 可分别用作 ``-p`` 和 ``-b`` 选项的默认值。在命令行中，重新为这两个选项赋值，会覆盖其默认值。 -组件目录中会包含组件自己的 Makefile 文件 ``component.mk`` ，里面会定义一些变量来控制该组件的构建过程，以及它与整个项目的集成。更多详细信息请参考 `组件 Makefiles <#component-makefiles>`_。 +.. _idf.py-size: -每个组件还可以包含一个 ``Kconfig`` 文件，它用于定义 ``menuconfig`` 时展示的组件配置信息的选项规则。某些组件还可能还会包含 ``Kconfig.projbuild`` 和 ``Makefile.projbuild`` 特殊文件，他们可以用来覆盖项目的部分配置。 - -项目 Makefiles -~~~~~~~~~~~~~~ - -每个项目都有一个 Makefile ，它包含整个项目的构建设置。默认情况下，项目 Makefile 可以非常小。 - -最小 Makefile 示例 -^^^^^^^^^^^^^^^^^^ - -.. code:: - - PROJECT_NAME := myProject - - include $(IDF_PATH)/make/project.mk - -必须设置的项目变量 -^^^^^^^^^^^^^^^^^^ - -- ``PROJECT_NAME``: 项目名称，最终输出的二进制文件也使用该名称，即 myProject.bin，myProject.elf 。 - -可选的项目变量 -^^^^^^^^^^^^^^ - -以下这些变量都有默认值，用户可以重写这些变量以自定义构建行为。查看 ``make/project.mk`` 文件可以获得所有的实现细节。 - -- ``PROJECT_PATH``： 顶层项目目录，默认是包含 Makefile 文件的目录，许多其他的项目变量都基于此变量。注意，项目路径中不能包含有空格。 -- ``BUILD_DIR_BASE``： 所有对象、库、二进制文件的输出目录，默认为 ``$(PROJECT_PATH)/build``。 -- ``COMPONENT_DIRS``： 组件的搜索目录，默认为 ``$(IDF_PATH)/components``，``$(PROJECT_PATH)/components``，``$(PROJECT_PATH)/main`` 和 ``EXTRA_COMPONENT_DIRS`` 。如果您不希望从这些目录中搜索组件，请重写此变量。 -- ``EXTRA_COMPONENT_DIRS``： 组件额外的搜索路径，可选。 -- ``COMPONENTS``： 要构建进项目中的组件列表，默认为 ``COMPONENT_DIRS`` 指定目录中所有的组件。 -- ``EXCLUDE_COMPONENTS``： 在构建的过程中需要剔除的组件列表，可选。请注意这只会减少构建的时间，并不会减少最终二进制文件的大小。 -- ``TEST_EXCLUDE_COMPONENTS``： 在构建单元测试的过程中需要剔除的组件列表，可选。 - -以上这些 Makefile 变量中的任何路径都要使用绝对路径，您可以使用 ``$(PROJECT_PATH)/xxx``，``$(IDF_PATH)/xxx``，或者使用 Make 内置函数 ``$(abspath xxx)`` 将相对路径转换为绝对路径。 - -以上这些变量要在 Makefile 中 ``include $(IDF_PATH)/make/project.mk`` 的前面进行设置。 - -.. _component-makefiles: - -组件 Makefiles -~~~~~~~~~~~~~~ - -每个项目都包含一个或者多个组件，这些组件可以是 ESP-IDF 的一部分，也可以从其他组件目录添加。 - -组件是包含 ``component.mk`` 文件的任何目录。 - -搜索组件 -~~~~~~~~ - -搜索 ``COMPONENT_DIRS`` 中指定的目录以查找项目会使用的组件，目录可以是组件本身（即他们包含 ``component.mk`` 文件），也可以是包含组件的上层目录。 - -运行 ``make list-components`` 命令可以查询这些变量的值，这有助于调试组件的搜索路径是否正确。 - -同名组件 +高级命令 ^^^^^^^^ -ESP-IDF 搜索组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进行，这意味着在默认情况下，首先是 ESP-IDF 组件，然后是项目组件，最后是 ``EXTRA_COMPONENT_DIRS`` 中的组件。如果这些目录中的两个或者多个包含具有相同名字的组件，则使用搜索到的最后一个位置的组件。这就允许将组件复制到项目目录中再修改来覆盖 ESP-IDF 组件，如果使用这种方式，ESP-IDF 目录本身可以保持不变。 +- ``idf.py app``，``idf.py bootloader``，``idf.py partition_table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。 +- ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 ESP32。 +- ``idf.py -p PORT erase_flash`` 会使用 esptool.py 擦除 ESP32 的整个 Flash。 +- ``idf.py size`` 会打印应用程序相关的大小信息，``idf.py size-components`` 和 ``idf.py size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。 +- ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。 -.. _minimal-component-makefile: +同时调用多个 ``idf.py`` 命令时，命令的输入顺序并不重要，它们会按照正确的顺序依次执行，并保证每一条命令都生效（即先构建后烧录，先擦除后烧录等）。 -最小组件 Makefile -^^^^^^^^^^^^^^^^^ +直接使用 CMake +-------------- -最简单的 ``component.mk`` 文件可以是一个空文件，如果文件为空，则组件的默认构建行为会被设置为： +为了方便，:ref:`idf.py` 已经封装了 CMake_ 命令，但是您愿意，也可以直接调用 CMake。 -- makefile 所在目录中的所有源文件（``*.c``，``*.cpp``，``*.cc``，``*.S``）将会被编译进组件库中。 -- 子目录 ``include`` 将被添加到其他组件的全局头文件搜索路径中。 -- 组件库将会被链接到项目的应用程序中。 +.. highlight:: bash -更完整的组件 makefile 可以查看 `组件 Makefile 示例 <#example-component-makefile>`_。 +当 ``idf.py`` 在执行某些操作时，它会打印出其运行的每条命令以便参考。例如运行 ``idf.py build`` 命令与在 bash shell（或者 Windows Command Prompt）中运行以下命令是相同的:: -请注意，空的 ``component.mk`` 文件同没有 ``component.mk`` 文件之间存在本质差异，前者会调用默认的组件构建行为，后者不会发生默认的组件构建行为。一个组件中如果只包含影响项目配置或构建过程的文件，那么它可以没有 ``component.mk`` 文件。 + mkdir -p build + cd build + cmake .. -G Ninja # 或者 'Unix Makefiles' + ninja -.. _preset-component-variables: +在上面的命令列表中，``cmake`` 命令对项目进行配置，并生成用于最终构建工具的构建文件。在这个例子中，最终构建工具是 Ninja_: 运行 ``ninja`` 来构建项目。 -预设的组件变量 -^^^^^^^^^^^^^^ +没有必要多次运行 ``cmake``。第一次构建后，往后每次只需运行 ``ninja`` 即可。如果项目需要重新配置，``ninja`` 会自动重新调用 ``cmake``。 -以下特定于组件的变量可以在 ``component.mk`` 中使用，但不应该被修改。 +若在 CMake 中使用 ``ninja`` 或 ``make``，则多数 ``idf.py`` 子命令也会有其对应的目标，例如在构建目录下运行 ``make menuconfig`` 或 ``ninja menuconfig`` 与运行 ``idf.py menuconfig`` 是相同的。 -- ``COMPONENT_PATH``： 组件的目录，即包含 ``component.mk`` 文件的绝对路径，路径中不能包含空格。 -- ``COMPONENT_NAME``： 组件的名字，默认为组件目录的名称。 -- ``COMPONENT_BUILD_DIR``： 组件的构建目录，即存放组件构建输出的绝对路径，它是 `$(BUILD_DIR_BASE)` 的子目录。该变量也是构建组件时的当前工作目录，所以 make 中的相对路径都以此目录为基础。 -- ``COMPONENT_LIBRARY``： 组件构建后的静态库文件（相对于组件的构建目录）的名字，默认为 ``$(COMPONENT_NAME).a``。 +.. Note:: + 如果您已经熟悉了 CMake_，那么可能会发现 ESP-IDF 的 CMake 构建系统不同寻常，为了减少样板文件，该系统封装了 CMake 的许多功能。请参考 :ref:`write-pure-component` 以编写更多 ``CMake 风格`` 的组件。 -以下变量在项目顶层中设置，并被导出到组件中构建时使用： +.. _flash-with-ninja-or-make: -- ``PROJECT_NAME``： 项目名称，在项目的 Makefile 中设置。 -- ``PROJECT_PATH``： 包含项目 Makefile 的目录的绝对路径。 -- ``COMPONENTS``： 此次构建中包含的所有组件的名字。 -- ``CONFIG_*``： 项目配置中的每个值在 make 中都对应一个以 ``CONFIG_`` 开头的变量。 -- ``CC``，``LD``，``AR``，``OBJCOPY``： gcc xtensa 交叉编译工具链中每个工具的完整路径。 -- ``HOSTCC``，``HOSTLD``，``HOSTAR``： 主机本地工具链中每个工具的全名。 -- ``IDF_VER``： ESP-IDF 的版本号，可以通过检索 ``$(IDF_PATH)/version.txt`` 文件（假如存在的话）或者使用 git 命令 ``git describe`` 来获取。这里推荐的格式是在一行中指定主 IDF 的发布版本号，例如标记为 ``v2.0`` 的发布版本或者是标记任意一次提交记录的 ``v2.0-275-g0efaa4f``。应用程序可以通过调用 :cpp:func:`esp_get_idf_version` 函数来使用该变量。 -- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: ESP-IDF 的组件版本，可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量，版本号 ``v4.0-dev-*``， ``v4.0-beta1``， ``v4.0-rc1`` 和 ``v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的，但是 ``IDF_VER`` 的值是不同的。 - -如果您在 ``component.mk`` 文件中修改这些变量，这并不会影响其它组件的构建，但可能会使您的组件变得难以构建或调试。 - -.. _optional-project-wide-component-variables: - -可选的项目通用组件变量 +使用 Ninja/Make 来烧录 ^^^^^^^^^^^^^^^^^^^^^^ -可以在 ``component.mk`` 中设置以下变量来控制整个项目的构建行为： +您可以直接使用 ninja 或 make 运行如下命令来构建项目并烧录:: -- ``COMPONENT_ADD_INCLUDEDIRS``： 相对于组件目录的路径，将被添加到项目中所有组件的头文件搜索路径中。如果该变量未被覆盖，则默认为 ``include`` 目录。如果一个头文件路径仅仅为当前组件所用，那么应该将该路径添加到 ``COMPONENT_PRIV_INCLUDEDIRS`` 中。 -- ``COMPONENT_ADD_LDFLAGS``： 添加链接参数到全局 ``LDFLAGS`` 中用以指导链接最终的可执行文件，默认为 ``-l$(COMPONENT_NAME)``。如果将预编译好的库添加到此目录，请使用它们为绝对路径，即 ``$(COMPONENT_PATH)/libwhatever.a``。 -- ``COMPONENT_DEPENDS``： 需要在当前组件之前构建的组件列表，这对于处理链接时的依赖不是必需的，因为所有组件的头文件目录始终可用。如果一个组件会生成一个头文件，然后另外一个组件需要使用它，此时该变量就有必要进行设置。大多数的组件不需要设置此变量。 -- ``COMPONENT_ADD_LINKER_DEPS``： 保存一些文件的路径，当这些文件发生改变时，会触发 ELF 文件重新链接。该变量通常用于链接脚本文件和二进制文件，大多数的组件不需要设置此变量。 + ninja flash -以下变量仅适用于属于 ESP-IDF 的组件： +或:: -- ``COMPONENT_SUBMODULES``： 组件使用的 git 子模块的路径列表（相对于 ``COMPONENT_PATH``）。这些路径会在构建的过程中被检查（并在必要的时候初始化）。如果组件位于 ``IDF_PATH`` 目录之外，则忽略此变量。 + make app-flash +可用的目标还包括：``flash``、``app-flash`` （仅用于 app）、``bootloader-flash`` （仅用于 bootloader）。 + +以这种方式烧录时，可以通过设置 ``ESPPORT`` 和 ``ESPBAUD`` 环境变量来指定串口设备和波特率。您可以在操作系统或 IDE 项目中设置该环境变量，或者直接在命令行中进行设置:: + + ESPPORT=/dev/ttyUSB0 ninja flash + +.. Note:: 在命令的开头为环境变量赋值属于 Bash shell 的语法，可在 Linux 、macOS 和 Windows 的类 Bash shell 中运行，但在 Windows Command Prompt 中无法运行。 + +或:: + + make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000 + +.. Note:: 在命令末尾为变量赋值属于 ``make`` 的语法，适用于所有平台的 ``make``。 + +在 IDE 中使用 CMake +------------------- + +您还可以使用集成了 CMake 的 IDE，仅需将项目 ``CMakeLists.txt`` 文件的路径告诉 IDE 即可。集成 CMake 的 IDE 通常会有自己的构建工具（CMake 称之为“生成器”），它是组成 IDE 的一部分，用来构建源文件。 + +向 IDE 中添加除 ``build`` 目标以外的自定义目标（如添加 “Flash” 目标到 IDE）时，建议调用 ``idf.py`` 命令来执行这些“特殊”的操作。 + +有关将ESP-IDF 同 CMake 集成到 IDE 中的详细信息，请参阅 :ref:`build_system_metadata`。 + +.. _setting-python-interpreter: + +设置 Python 解释器 +------------------ + +目前，ESP-IDF 仅适用于 Python 2.7，如果系统中默认的 ``python`` 解释器是 Python 3.x，可能会出现问题。 + +如果使用了 ``idf.py``，并以 ``python2 $IDF_PATH/tools/idf.py ...`` 的方式运行 ``idf.py`` 则会解决这个问题（``idf.py`` 会通知其余 Python 进程使用相同的 Python 解释器）。你可以通过设置 shell 别名或其他脚本来简化该命令。 + +如果直接使用 CMake，运行 ``cmake -D PYTHON=python2 ...``，CMake 会使用传入的值覆盖默认的 Python 解释器。 + +如果使用集成 CMake 的 IDE，可以在 IDE 的图形用户界面中给名为 ``PYTHON`` 的 CMake cache 变量设置新的值来覆盖默认的 Python 解释器。 + +如果想在命令行中更优雅地管理 Python 的各个版本，请查看 pyenv_ 或 virtualenv_ 工具，它们会帮助您更改默认的 python 版本。 + +.. _example-project-structure: + +示例项目 +======== + +.. highlight:: none + +示例项目的目录树结构可能如下所示:: + + - myProject/ + - CMakeLists.txt + - sdkconfig + - components/ - component1/ - CMakeLists.txt + - Kconfig + - src1.c + - component2/ - CMakeLists.txt + - Kconfig + - src1.c + - include/ - component2.h + - main/ - src1.c + - src2.c + - build/ + +该示例项目 ``myproject`` 包含以下组成部分： + +- 顶层项目 CMakeLists.txt 文件，这是 CMake 用于学习如何构建项目的主要文件，可以在这个文件中设置项目全局的 CMake 变量。顶层项目 CMakeLists.txt 文件会导入 :idf_file:`/tools/cmake/project.cmake` 文件，由它负责实现构建系统的其余部分。该文件最后会设置项目的名称，并定义该项目。 +- ``sdkconfig`` 项目配置文件，执行 ``idf.py menuconfig`` 时会创建或更新此文件，文件中保存了项目中所有组件（包括 ESP-IDF 本身）的配置信息。 ``sdkconfig`` 文件可能会也可能不会被添加到项目的源码管理系统中。 +- 可选的 ``component`` 目录中包含了项目的部分自定义组件，并不是每个项目都需要这种自定义组件，但它组件有助于构建可复用的代码或者导入第三方（不属于 ESP-IDF）的组件。 +- ``main`` 目录是一个特殊的 ``伪组件``，包含项目本身的源代码。``main`` 是默认名称，CMake 变量 ``COMPONENT_DIRS`` 默认包含此组件，但您可以修改此变量。或者，您也可以在顶层 CMakeLists.txt 中设置 ``EXTRA_COMPONENT_DIRS`` 变量以查找其他指定位置处的组件。有关详细信息，请参阅 :ref:`重命名 main 组件 `。如果项目中源文件较多，建议将其归于组件中，而不是全部放在 ``main`` 中。 +- ``build`` 目录是存放构建输出的地方，如果没有此目录，``idf.py`` 会自动创建。CMake 会配置项目，并在此目录下生成临时的构建文件。随后，在主构建进程的运行期间，该目录还会保存临时目标文件、库文件以及最终输出的二进制文件。此目录通常不会添加到项目的源码管理系统中，也不会随项目源码一同发布。 + +每个组件目录都包含一个 ``CMakeLists.txt`` 文件，里面会定义一些变量以控制该组件的构建过程，以及其与整个项目的集成。更多详细信息请参阅 :ref:`component-directories`。 + +每个组件还可以包含一个 ``Kconfig`` 文件，它用于定义 ``menuconfig`` 时展示的 :ref:`component-configuration` 选项。某些组件可能还会包含 ``Kconfig.projbuild`` 和 ``project_include.cmake`` 特殊文件，它们用于 :ref:`override_project_config`。 + +项目 CMakeLists 文件 +==================== + +每个项目都有一个顶层 ``CMakeLists.txt`` 文件，包含整个项目的构建设置。默认情况下，项目 CMakeLists 文件会非常小。 + +最小 CMakeLists 文件示例 +------------------------ + +.. highlight:: cmake + +最小项目:: + + cmake_minimum_required(VERSION 3.5) + include($ENV{IDF_PATH}/tools/cmake/project.cmake) + project(myProject) + + +.. _project-mandatory-parts: + +必要部分 +-------- + +每个项目都要按照上面显示的顺序添加上述三行代码： + +- ``cmake_minimum_required(VERSION 3.5)`` 必须放在 CMakeLists.txt 文件的第一行，它会告诉 CMake 构建该项目所需要的最小版本号。ESP-IDF 支持 CMake 3.5 或更高的版本。 +- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` 会导入 CMake 的其余功能来完成配置项目、检索组件等任务。 +- ``project(myProject)`` 会创建项目本身，并指定项目名称。该名称会作为最终输出的二进制文件的名字，即 ``myProject.elf`` 和 ``myProject.bin``。每个 CMakeLists 文件只能定义一个项目。 + +.. _optional_project_variable: + +可选的项目变量 +-------------- + +以下这些变量都有默认值，用户可以覆盖这些变量值以自定义构建行为。更多实现细节，请参阅 :idf_file:`/tools/cmake/project.cmake` 文件。 + +- ``COMPONENT_DIRS``：组件的搜索目录，默认为 ``${IDF_PATH}/components``、``${PROJECT_PATH}/components`` 和 ``EXTRA_COMPONENT_DIRS``。如果您不想在这些位置搜索组件，请覆盖此变量。 +- ``EXTRA_COMPONENT_DIRS``：用于搜索组件的其它可选目录列表。路径可以是相对于项目目录的相对路径，也可以是绝对路径。 +- ``COMPONENTS``：要构建进项目中的组件名称列表，默认为 ``COMPONENT_DIRS`` 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过 ``COMPONENT_REQUIRES`` 指定了它依赖的另一个组件，则会自动将其添加到 ``COMPONENTS`` 中，所以 ``COMPONENTS`` 列表可能会非常短。 +- ``COMPONENT_REQUIRES_COMMON``：每个组件都需要的通用组件列表，这些通用组件会自动添加到每个组件的 ``COMPONENT_PRIV_REQUIRES`` 列表中以及项目的 ``COMPONENTS`` 列表中。默认情况下，此变量设置为 ESP-IDF 项目所需的最小核心“系统”组件集。通常您无需在项目中更改此变量。 + +以上变量中的路径可以是绝对路径，或者是相对于项目目录的相对路径。 + +请使用 `cmake 中的 set 命令 `_ 来设置这些变量，即 ``set(VARIABLE "VALUE")``。请注意，``set()`` 命令需放在 ``include(...)`` 之前，``cmake_minimum(...)`` 之后。 + +.. _rename-main: + +重命名 ``main`` 组件 +-------------------- + +构建系统会对 ``main`` 组件进行特殊处理。假如 ``main`` 组件位于预期的位置（即 `${PROJECT_PATH}/main`），那么它会被自动添加到构建系统中。其他组件也会作为其依赖项被添加到构建系统中，这使用户免于处理依赖关系，并提供即时可用的构建功能。重命名 ``main`` 组件会减轻上述这些幕后工作量，但要求用户指定重命名后的组件位置，并手动为其添加依赖项。重命名 ``main`` 组件的步骤如下： + +1. 重命名 ``main`` 目录。 +2. 在项目 CMakeLists.txt 文件中设置 ``EXTRA_COMPONENT_DIRS``，并添加重命名后的 ``main`` 目录。 +3. 在组件的 CMakeLists.txt 文件中设置 ``COMPONENT_REQUIRES`` 或 ``COMPONENT_PRIV_REQUIRES`` 以指定依赖项。 + + +.. _component-directories: + +组件 CMakeLists 文件 +==================== + +每个项目都包含一个或多个组件，这些组件可以是 ESP-IDF 的一部分，可以是项目自身组件目录的一部分，也可以从自定义组件目录添加（ :ref:`见上文 `）。 + +组件是 ``COMPONENT_DIRS`` 列表中包含 ``CMakeLists.txt`` 文件的任何目录。 + +搜索组件 +-------- + +搜索 ``COMPONENT_DIRS`` 中的目录列表以查找项目的组件，此列表中的目录可以是组件自身（即包含 `CMakeLists.txt` 文件的目录），也可以是子目录为组件的顶级目录。 + +当 CMake 运行项目配置时，它会记录本次构建包含的组件列表，它可用于调试某些组件的添加/排除。 + +同名组件 +-------- + +ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指定的顺序依次进行，这意味着在默认情况下，首先搜索 ESP-IDF 内部组件，然后是项目组件，最后是 ``EXTRA_COMPONENT_DIRS`` 中的组件。如果这些目录中的两个或者多个包含具有相同名字的组件，则使用搜索到的最后一个位置的组件。这就允许将组件复制到项目目录中再修改以覆盖 ESP-IDF 组件，如果使用这种方式，ESP-IDF 目录本身可以保持不变。 + +.. _minimum_cmakelists: + +最小的组件 CMakeLists 文件 +-------------------------- + +.. highlight:: cmake + +最小组件 ``CMakeLists.txt`` 文件内容如下:: + + set(COMPONENT_SRCS "foo.c") + set(COMPONENT_ADD_INCLUDEDIRS "include") + register_component() + +- ``COMPONENT_SRCS`` 是用空格分隔的源文件列表（``*.c``，``*.cpp``，``*.cc``，``*.S``），里面所有的源文件都将会编译进组件库中。 +- ``COMPONENT_ADD_INCLUDEDIRS`` 是用空格分隔的目录列表，里面的路径会被添加到所有需要该组件的组件（包括 main 组件）全局 include 搜索路径中。 +- ``register_component()`` 使用上述设置的变量将组件添加到构建系统中，构建生成与组件同名的库，并最终被链接到应用程序中。如果因为使用了 `CMake 中的 if 命令 `_ 或类似命令而跳过了这一步，那么该组件将不会被添加到构建系统中。 + +上述目录通常设置为相对于 ``CMakeLists.txt`` 文件的相对路径，当然也可以设置为绝对路径。 + +有关更完整的 ``CMakeLists.txt`` 示例，请参阅 :ref:`component_cmakelists_example`。 + +.. _preset_component_variables: + +预设的组件变量 +-------------- + +以下专用于组件的变量可以在组件 CMakeLists 中使用，但不建议修改： + +- ``COMPONENT_PATH``：组件目录，即包含 ``CMakeLists.txt`` 文件的绝对路径，它与 ``CMAKE_CURRENT_SOURCE_DIR`` 变量一样，路径中不能包含空格。 +- ``COMPONENT_NAME``：组件名，与组件目录名相同。 +- ``COMPONENT_TARGET``：库目标名，它由构建系统在内部为组件创建。 + +以下变量在项目级别中被设置，但可在组件 CMakeLists 中使用： + +- ``PROJECT_NAME``：项目名，在项目 CMakeLists.txt 文件中设置。 +- ``PROJECT_PATH``：项目目录（包含项目 CMakeLists 文件）的绝对路径，与 ``CMAKE_SOURCE_DIR`` 变量相同。 +- ``COMPONENTS``：此次构建中包含的所有组件的名称，具体格式为用分号隔开的 CMake 列表。 +- ``CONFIG_*``：项目配置中的每个值在 cmake 中都对应一个以 ``CONFIG_`` 开头的变量。更多详细信息请参阅 :doc:`Kconfig `。 +- ``IDF_VER``：ESP-IDF 的 git 版本号，由 ``git describe`` 命令生成。 +- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: ESP-IDF 的组件版本，可用于条件表达式。请注意这些信息的精确度不如 ``IDF_VER`` 变量，版本号 ``v4.0-dev-*``， ``v4.0-beta1``， ``v4.0-rc1`` 和 ``v4.0`` 对应的 ``IDF_VERSION_*`` 变量值是相同的，但是 ``IDF_VER`` 的值是不同的。 +- ``IDF_TARGET``：项目的硬件目标名称。 +- ``PROJECT_VER``：项目版本号。 + + * 如果在项目 CMakeLists.txt 文件中设置了 ``PROJECT_VER`` 变量，则该变量值可以使用。 + * 或者，如果 ``${PROJECT_PATH}/version.txt`` 文件存在，其内容会用作 ``PROJECT_VER`` 的值。 + * 或者，如果项目位于某个 Git 仓库中，则使用 ``git describe`` 命令的输出作为 ``PROJECT_VER`` 的值。 + * 否则，``PROJECT_VER`` 的值为空。 + +如果您在组件的 ``CMakeLists.txt`` 中修改以上变量，并不会影响其他组件的构建，但可能会使该组件变得难以构建或调试。 + +- ``COMPONENT_ADD_INCLUDEDIRS``：相对于组件目录的相对路径，为被添加到所有需要该组件的其他组件的全局 include 搜索路径中。如果某个 include 路径仅仅在编译当前组件时需要，请将其添加到 ``COMPONENT_PRIV_INCLUDEDIRS`` 中。 +- ``COMPONENT_REQUIRES`` 是一个用空格分隔的组件列表，列出了当前组件依赖的其他组件。如果当前组件有一个头文件位于 ``COMPONENT_ADD_INCLUDEDIRS`` 目录下，且该头文件包含了另一个组件的头文件，那么这个被依赖的组件需要在 ``COMPONENT_REQUIRES`` 中指出。这种依赖关系可以是递归的。 + + ``COMPONENT_REQUIRES`` 可以为空，因为所有的组件都需要一些常用的组件（如 newlib 组件提供的 libc 库、freertos 组件提供的 RTOS 功能），这些通用组件已经在项目级变量 ``COMPONENT_REQUIRES_COMMON`` 中被设置。 + + 如果一个组件仅需要额外组件的头文件来编译其源文件（而不是全局引入它们的头文件），则这些被依赖的组件需要在 ``COMPONENT_PRIV_REQUIRES`` 中指出。 + + 请参阅 :ref:`component_dependency`，查看详细信息。 可选的组件特定变量 -^^^^^^^^^^^^^^^^^^ +------------------ -以下变量可以在 ``component.mk`` 中进行设置，用以控制该组件的构建行为： +以下变量可在 ``CMakeLists.txt`` 中进行设置，用以控制该组件的构建行为： -- ``COMPONENT_PRIV_INCLUDEDIRS``： 相对于组件目录的目录路径，该目录仅会被添加到该组件源文件的头文件搜索路径中。 -- ``COMPONENT_EXTRA_INCLUDES``： 编译组件的源文件时需要指定的额外的头文件搜索路径，这些路径将以 ``-l`` 为前缀传递给编译器。这和 ``COMPONENT_PRIV_INCLUDEDIRS`` 变量的功能有些类似，但是这些路径不会相对于组件目录进行扩展。 -- ``COMPONENT_SRCDIRS``： 相对于组件目录的目录路径，这些路径用于搜索源文件（``*.cpp``，``*.c``，``*.S``），默认为 ``.``，即组件目录本身。重写该变量可以指定包含源文件的不同目录列表。 -- ``COMPONENT_OBJS``： 要编译生成的目标文件，默认是 ``COMPONENT_SRCDIRS`` 中每个源文件的 .o 文件。重写该变量将允许您剔除 ``COMPONENT_SRCDIRS`` 中的某些源文件，否则他们将会被编译。相关示例请参阅 `指定需要编译的组件源文件 <#specify-source-files>`_。 -- ``COMPONENT_EXTRA_CLEAN``： 相对于组件构建目录的路径，指向 ``component.mk`` 文件中自定义 make 规则生成的任何文件，它们也是 ``make clean`` 命令需要删除的文件。相关示例请参阅 `源代码生成 <#source-code-generation>`_。 -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``： 这些目标允许您完全覆盖组件的默认编译行为。有关详细信息，请参阅 `完全覆盖组件的 Makefile <#fully-overriding-component-makefile>`_。 -- ``COMPONENT_CONFIG_ONLY``： 如果设置了此标志，则表示组件根本不会产生构建输出（即不会构建得到 ``COMPONENT_LIBRARY``），并且会忽略大多数其它组件变量。此标志用于 IDF 内部组件，其中仅包含 ``KConfig.projbuild`` 和/或 ``Makefile.projbuild`` 文件来配置项目，但是没有源文件。 -- ``CFLAGS``： 传递给 C 编译器的标志。根据项目设置已经定义一组默认的 ``CFLAGS``，可以通过 ``CFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。 -- ``CPPFLAGS``： 传递给 C 预处理器的标志（用于 ``.c``，``.cpp`` 和 ``.S`` 文件）。根据项目设置已经定义一组默认的 ``CPPFLAGS`` ，可以通过 ``CPPFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。 -- ``CXXFLAGS``： 传递给 C++ 编译器的标志。根据项目设置已经定义一组默认的 ``CXXFLAGS`` ，可以通过 ``CXXFLAGS +=`` 来为组件添加特定的标志，也可以完全重写该变量（尽管不推荐这么做）。 +- ``COMPONENT_PRIV_INCLUDEDIRS``：相对于组件目录的相对路径，仅会被添加到该组件的 include 搜索路径中。 +- ``COMPONENT_PRIV_REQUIRES``：以空格分隔的组件列表，用于编译或链接当前组件的源文件。这些组件的头文件路径不会传递给其余需要它的组件，仅用于编译当前组件的源代码。更多详细信息请参阅 :ref:`component_dependency`。 +- ``COMPONENT_SRCS``：要编译进当前组件的源文件的路径，推荐使用此方法向构建系统中添加源文件。 +- ``COMPONENT_SRCDIRS``：相对于组件目录的源文件目录路径，用于搜索源文件（``*.cpp``，``*.c``，``*.S``）。匹配成功的源文件会替代 ``COMPONENT_SRCS`` 中指定的源文件，进而被编译进组件。即设置 ``COMPONENT_SRCDIRS`` 会导致 ``COMPONENT_SRCS`` 会被忽略。此方法可以很容易地将源文件整体导入到组件中，但并不推荐使用（详情请参阅 :ref:`cmake-file-globbing`）。 +- ``COMPONENT_SRCEXCLUDE``：需要从组件中剔除的源文件路径。当某个目录中有大量的源文件需要被导入组件中，但同时又有个别文件不需要导入时，可以配合 ``COMPONENT_SRCDIRS`` 变量一起设置。路径可以是相对于组件目录的相对路径，也可以是绝对路径。 +- ``COMPONENT_ADD_LDFRAGMENTS``：组件使用的链接片段文件的路径，用于自动生成链接器脚本文件。详细信息请参阅 :doc:`链接脚本生成机制 `。 -如果要将编译标志应用于单个源文件，您可以将该源文件的目标规则覆盖，例如： +.. Note:: -.. code:: makefile + 如果没有设置 ``COMPONENT_SRCDIRS`` 或 ``COMPONENT_SRCS``，组件不会被编译成库文件，但仍可以被添加到 include 路径中，以便在编译其他组件时使用。 - apps/dhcpserver.o: CFLAGS += -Wno-unused-variable +.. _component_build_control: + +组件编译控制 +------------ + +.. highlight:: cmake + +在编译特定组件的源文件时，可以使用 ``target_compile_options`` 命令来传递编译器选项:: + + target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable) + +这条命令封装了 CMake 的 `target_compile_options`_ 命令。 + +如果给单个源文件指定编译器标志，可以使用 CMake 的 `set_source_files_properties`_ 命令:: + + set_source_files_properties(mysrc.c + PROPERTIES COMPILE_FLAGS + -Wno-unused-variable + ) 如果上游代码在编译的时候发出了警告，那这么做可能会很有效。 -配置组件 -~~~~~~~~ +请注意，上述两条命令只能在组件 CMakeLists 文件的 ``register_component()`` 命令之后调用。 -每个组件都可以包含一个 Kconfig 文件，和 ``component.mk`` 放在同一个目录下。Kconfig 中包含此组件在 ``make menuconfig`` 时要展示的配置规则的设置。 +.. _component-configuration: + +组件配置 +======== + +每个组件都可以包含一个 ``Kconfig`` 文件，和 ``CMakeLists.txt`` 放在同一目录下。``Kconfig`` 文件中包含要添加到该组件配置菜单中的一些配置设置信息。 运行 menuconfig 时，可以在 ``Component Settings`` 菜单栏下找到这些设置。 创建一个组件的 Kconfig 文件，最简单的方法就是使用 ESP-IDF 中现有的 Kconfig 文件作为模板，在这基础上进行修改。 -有关示例请参阅 `添加条件配置 <#add-conditional-configuration>`_。 +有关示例请参阅 :ref:`add_conditional_config`。 预处理器定义 -~~~~~~~~~~~~ +============ -ESP-IDF 构建系统会在命令行中添加以下 C 预处理定义： +ESP-IDF 构建系统会在命令行中添加以下 C 预处理器定义： -- ``ESP_PLATFORM`` — 可以用来检测在 ESP-IDF 内发生的构建行为。 -- ``IDF_VER`` — ESP-IDF 的版本，请参阅 `预设的组件变量 <#preset-component-variables>`_。 +- ``ESP_PLATFORM``：可以用来检测在 ESP-IDF 内发生了构建行为。 +- ``IDF_VER``：定义 git 版本字符串，例如：``v2.0`` 用于标记已发布的版本，``v1.0-275-g0efaa4f`` 则用于标记任意某次的提交记录。 +- ``PROJECT_VER``：项目版本号，详细信息请参阅 :ref:`preset_component_variables`。 +- ``PROJECT_NAME``：项目名称，定义在项目 CMakeLists.txt 文件中。 + +.. _component_dependency: + +组件依赖 +======== + +编译各个组件时，ESP-IDF 系统会递归评估其组件。 + +每个组件的源文件都会使用以下路径中的头文件进行编译: + +- 当前组件的 ``COMPONENT_ADD_INCLUDEDIRS`` 和 ``COMPONENT_PRIV_INCLUDEDIRS``。 +- 当前组件的 ``COMPONENT_REQUIRES`` 和 ``COMPONENT_PRIV_REQUIRES`` 变量指定的其他组件（即当前组件的所有公共和私有依赖项）所设置的 ``COMPONENT_ADD_INCLUDEDIRS``。 +- 所有组件的 ``COMPONENT_REQUIRES`` 做递归操作，即该组件递归运算后的所有公共依赖项。 + +编写组件 +-------- + +- ``COMPONENT_REQUIRES`` 需要包含所有被当前组件的公共头文件 `#include` 的头文件所在的组件。 +- ``COMPONENT_PRIV_REQUIRES`` 需要包含被当前组件的源文件 `#include` 的头文件所在的组件（除非已经被设置在了 ``COMPONENT_PRIV_REQUIRES`` 中）。或者是当前组件正常工作必须要链接的组件。 +- ``COMPONENT_REQUIRES``、``COMPONENT_PRIV_REQUIRES`` 需要在调用 ``register_component()`` 之前设置。 +- ``COMPONENT_REQUIRES`` 和 ``COMPONENT_PRIV_REQUIRES`` 的值不能依赖于任何配置选项（``CONFIG_xxx``），这是因为在配置加载之前，依赖关系就已经被展开。其它组件变量（比如 ``COMPONENT_SRCS`` 和 ``COMPONENT_ADD_INCLUDEDIRS``）可以依赖配置选择。 +- 如果当前组件除了 ``COMPONENT_REQUIRES_COMMON`` 中设置的通用组件（比如 RTOS、libc 等）外，并不依赖其它组件，那么上述两个 ``REQUIRES`` 变量可以为空。 + +如果组件仅支持某些硬件目标（即依赖于特定的 ``IDF_TARGET``），则可以调用 ``require_idf_targets(NAMES...)`` CMake 函数来声明这个需求。在这种情况下，如果构建系统导入了不支持当前硬件目标的组件时就会报错。 + +创建项目 +-------- + +- 默认情况下，每个组件都会包含在构建系统中。 +- 如果将 ``COMPONENTS`` 变量设置为项目直接使用的最小组件列表，那么构建系统会导入： + + * ``COMPONENTS`` 中明确提及的组件。 + * 这些组件的依赖项（以及递归运算后的组件）。 + * 每个组件都依赖的通用组件。 + +- 将 ``COMPONENTS`` 设置为所需组件的最小列表，可以显著减少项目的构建时间。 + +.. _component-requirements-implementation: + +构建系统中依赖处理的实现细节 +---------------------------- + +- 在 CMake 配置进程的早期阶段会运行 ``expand_requirements.cmake`` 脚本。该脚本会对所有组件的 CMakeLists.txt 文件进行局部的运算，得到一张组件依赖关系图（此图可能会有闭环）。此图用于在构建目录中生成 ``component_depends.cmake`` 文件。 +- CMake 主进程会导入该文件，并以此来确定要包含到构建系统中的组件列表（内部使用的 ``BUILD_COMPONENTS`` 变量）。``BUILD_COMPONENTS`` 变量已排好序，依赖组件会排在前面。由于组件依赖关系图中可能存在闭环，因此不能保证每个组件都满足该排序规则。如果给定相同的组件集和依赖关系，那么最终的排序结果应该是确定的。 +- CMake 会将 ``BUILD_COMPONENTS`` 的值以 “Component names:” 的形式打印出来。 +- 然后执行构建系统中包含的每个组件的配置。 +- 每个组件都被正常包含在构建系统中，然后再次执行 CMakeLists.txt 文件，将组件库加入构建系统。 + +组件依赖顺序 +^^^^^^^^^^^^ + +``BUILD_COMPONENTS`` 变量中组件的顺序决定了构建过程中的其它顺序，包括： + +- 项目导入 :ref:`project_include.cmake` 文件的顺序。 +- 生成用于编译（通过 ``-I`` 参数）的头文件路径列表的顺序。请注意，对于给定组件的源文件，仅需将该组件的依赖组件的头文件路径告知编译器。 构建的内部过程 -~~~~~~~~~~~~~~ +============== -顶层：项目 Makefile -^^^^^^^^^^^^^^^^^^^ +关于 CMake_ 以及 CMake 命令的详细信息，请参阅 `CMake v3.5 官方文档`_ 。 -- ``make`` 始终从项目目录处运行，并且项目的 makefile 名字通常为 Makefile 。 -- 项目的 makefile 文件会设置 ``PROJECT_NAME`` ，并且可以自定义其他可选的项目变量。 -- 项目 makefile 文件会导入 ``$(IDF_PATH)/make/project.mk`` ，该文件中会导入项目级的 Make 逻辑。 -- ``project.mk`` 填写默认的项目级 make 变量，并导入项目配置中的 make 变量。如果生成的包含项目配置的 makefile 文件已经过期，那么它将会被重新生成（通过 ``project_config.mk`` 中的目标规则），然后 make 进程从顶层重新开始。 -- ``project.mk`` 根据默认组件目录或者可选项目变量中设置的自定义组件列表来编译组件。 -- 每个组件都可以设置一些 `可选的项目通用组件变量 <#optional-project-wide-component-variables>`_ ，他们会通过 ``component_project_vars.mk`` 被导入 ``project.mk`` 文件中。如果这些文件有缺失或者过期，他们会被重新生成（通过对组件 makefile 的递归调用），然后 make 进程从顶层重新开始。 -- 组件中的 Makefile.projbuild 文件被包含在了 make 的进程中，以添加额外的目标或者配置。 -- 默认情况下，项目 makefile 还为每个组件生成顶层的编译和清理目标，并设置 app 和 clean 目标来调用所有这些子目标。 -- 为了编译每个组件，对组件 makefile 执行递归构建。 +project.cmake 的内容 +-------------------- -为了更好地理解项目的构建过程，请通读 ``project.mk`` 文件。 +当项目 CMakeLists 文件导入 ``project.cmake`` 文件时，``project.cmake`` 会定义一些实用的模块和全局变量。如果系统环境中没有设置 ``IDF_PATH``，那么它还会自动设置 ``IDF_PATH`` 变量。 -第二层：组件 Makefile 文件 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``project.cmake`` 文件还重写了 CMake_ 内置的 ``project`` 函数，以添加所有 ESP-IDF 项目特有的功能。 -- 每次调用组件 makefile 文件都是通过 ``$(IDF_PATH)/make/component_wrapper.mk`` 这个包装器进行的。 -- 此组件包装器包含了所有组件的 ``Makefile.componentbuild`` 文件，使这些文件中的任何配置，变量都可用于每个组件。 -- 调用 ``component_wrapper.mk`` 时将当前目录设置为组件构建目录，并将 ``COMPONENT_MAKEFILE`` 变量设置为 ``component.mk`` 的绝对路径。 -- ``component_wrapper.mk`` 为所有组件变量设置默认值，然后导入 ``component.mk`` 文件来覆盖或修改这些变量。 -- 如果未定义 ``COMPONENT_OWNBUILDTARGET`` 和 ``COMPONENT_OWNCLEANTARGET`` 文件，则会为组件的源文件和必备组件 ``COMPONENT_LIBRARY`` 静态库文件创建默认构建和清理目标。 -- ``component_project_vars.mk`` 文件在 ``component_wrapper.mk`` 中有自己的目标，如果由于组件的 makefile 或者项目配置的更改而需要重建此文件，则从 ``project.mk`` 文件中进行评估。 +project 函数 +------------ -为了更好地理解组件制作过程，请阅读 ``component_wrapper.mk`` 文件和 ESP-IDF 中的 ``component.mk`` 文件。 +自定义的 ``project()`` 函数会执行以下步骤： -以非交互的方式运行 Make -~~~~~~~~~~~~~~~~~~~~~~~ +- 确定硬件目标（由 ``IDF_TARGET`` 环境变量设置），并将其保存在 CMake cache 中。如果环境变量中设置的硬件目标与 CMake cache 中的不匹配，则会报错并退出。 +- 计算组件依赖，并构造 ``BUILD_COMPONENTS`` 变量，它是包含所有需要导入到构建系统中的组件列表（:ref:`详情请见上文`）。 +- 查找项目中所有的组件（搜索 ``COMPONENT_DIRS``，并按 ``COMPONENTS`` 进行过滤（前提是设置了该变量）。 +- 从 ``sdkconfig`` 文件中加载项目配置信息，生成 ``sdkconfig.cmake`` 和 ``sdkconfig.h`` 文件，分别用在 CMake 和 C/C++ 中定义配置项。如果项目配置发生了更改，CMake 会自动重新运行，重新生成上述两个文件，接着重新配置项目。 +- 根据硬件目标（``IDF_TARGET``）的值，将 `CMAKE_TOOLCHAIN_FILE`_ 变量设置为相应的工具链文件。 +- 调用 `CMake 的 project 函数 `_ 声明实际的 CMake-level 项目。 +- 加载 git 版本号。如果在 git 中检出了新的版本，就会使用一些技巧重新运行 CMake。详情请参考 :ref:`cmake-file-globbing`。 +- 从包含有 :ref:`project_include.cmake` 文件的组件中导入该文件。 +- 将每个组件都添加到构建系统中。每个组件的 CMakeLists 文件都会调用 ``register_component`` 函数，它会调用 CMake 的 `add_library `_ 函数来添加一个库，然后添加源文件、编译选项等。 +- 将最终的应用程序可执行文件添加到构建系统中。 +- 返回并为组件之间指定依赖关系（将每个组件的公共头文件目录添加到其他组件中）。 -如果在运行 ``make`` 的时候不希望出现交互式提示（例如：在IDE或自动构建系统中），可以将 ``BATCH_BUILD=1`` 添加到make的参数中（或者将其设置为环境变量）。 +更多详细信息请参阅 :idf_file:`/tools/cmake/project.cmake` 文件和 :idf_file:`/tools/cmake/idf_functions.cmake` 文件。 -设置 ``BATCH_BUILD`` 意味着： +CMake 调试 +---------- -- 详细输出（与 ``V=1`` 相同，见下文），如果不需要详细输出，就设置 ``V=0`` 。 -- 如果项目配置缺少新配置项（来自新组件或者 ESP-IDF 更新），则项目使用默认值，而不是提示用户输入每个项目。 -- 如果构建系统需要调用 ``menuconfig`` ，则会打印错误并且构建失败。 +调试 ESP-IDF CMake 构建系统的一些技巧： -.. _make-size: - -构建目标的进阶用法 -~~~~~~~~~~~~~~~~~~ - -- ``make app``，``make bootloader``，``make partition table`` 可以根据需要为项目单独构建生成应用程序文件、启动引导文件和分区表文件。 -- ``make erase_flash`` 和 ``make erase_ota`` 会调用 esptool.py 脚本分别擦除整块闪存芯片或者其中 OTA 分区的内容。 -- ``make size`` 会打印应用程序的大小信息。``make size-components`` 和 ``make size-files`` 两者功能相似，分别打印每个组件或者每个源文件大小的详细信息。 - -调试 Make 的过程 -~~~~~~~~~~~~~~~~ - -调试 ESP-IDF 构建系统的一些技巧： - -- 将 ``V=1`` 添加到 make 的参数中（或将其设置为环境变量）将使 make 回显所有已经执行的命令，以及为子 make 输入的每个目录。 -- 运行 ``make -w`` 将导致 make 在为子 make 输入时回显每个目录——与 ``V=1`` 相同但不回显所有命令。 -- 运行 ``make --trace`` （可能除了上述参数之一）将打印出构建时的每个目标，以及导致它构建的依赖项）。 -- 运行 ``make -p`` 会打印每个 makefile 中每个生成的目标的（非常详细的）摘要。 - -更多调试技巧和通用的构建信息，请参阅 `GNU 构建手册 `_。 +- CMake 运行时，会打印大量诊断信息，包括组件列表和组件路径。 +- 运行 ``cmake -DDEBUG=1``，IDF 构建系统会生成更详细的诊断输出。 +- 运行 ``cmake`` 时指定 ``--trace`` 或 ``--trace-expand`` 选项会提供大量有关控制流信息。详情请参考 `CMake 命令行文档`_。 .. _warn-undefined-variables: 警告未定义的变量 ^^^^^^^^^^^^^^^^ -默认情况下，如果引用了未定义的变量（如 ``$(DOES_NOT_EXIST)`` ，构建过程将会打印警告，这对于查找变量名称中的错误非常有用。 +默认情况下，``idf.py`` 在调用 CMake_ 时会给它传递 ``--warn-uninitialized`` 标志，如果在构建的过程中引用了未定义的变量，CMake_ 会打印警告。这对查找有错误的 CMake 文件非常有用。 -如果不想要此行为，可以在 menuconfig 顶层菜单下的 `SDK tool configuration` 中禁用它。 +如果您不想启用此功能，可以给 ``idf.py`` 传递 ``--no-warnings`` 标志。 -请注意，如果在 Makefile 中使用 ``ifdef`` 或者 ``ifndef`` ，则此选项不会出发警告。 +.. _override_project_config: -覆盖项目的部分内容 -~~~~~~~~~~~~~~~~~~ +覆盖项目的部分设置 +------------------ -Makefile.projbuild -^^^^^^^^^^^^^^^^^^ +.. _project_include.cmake: -如果一个组件含有必须要在项目构建过程的顶层进行计算的变量，则可以在组件目录下创建名为 ``Makefile.projbuild`` 的文件，项目在执行 ``project.mk`` 的时候会导入此 makefile 。 +project_include.cmake +^^^^^^^^^^^^^^^^^^^^^ -例如，如果您的组件需要为整个项目添加 CFLAGS（不仅仅是为自身的源文件），那么可以在 ``Makefile.projbuild`` 中设置 ``CFLAGS +=`` 。 +如果组件的某些构建行为需要在组件 CMakeLists 文件之前被执行，您可以在组件目录下创建名为 ``project_include.cmake`` 的文件，``project.cmake`` 在运行过程中会导入此 CMake 文件。 -``Makefile.projbuild`` 文件在 ESP-IDF 中大量使用，用于定义项目范围的构建功能，例如 ``esptool.py`` 命令行参数和 ``bootloader`` 这个特殊的程序。 +``project_include.cmake`` 文件在 ESP-IDF 内部使用，以定义项目范围内的构建功能，比如 ``esptool.py`` 的命令行参数和 ``bootloader`` 这个特殊的应用程序。 -请注意， ``Makefile.projbuild`` 对于最常见的组件不是必需的 - 例如向项目中添加 include 目录，或者将 LDFLAGS 添加到最终链接步骤，同样可以通过 ``component.mk`` 文件来自定义这些值。有关详细信息，请参阅 `可选的项目通用组件变量 <#optional-project-wide-component-variables>`_ 。 +与组件 ``CMakeLists.txt`` 文件有所不同，在导入``project_include.cmake`` 文件的时候，当前源文件目录（即 ``CMAKE_CURRENT_SOURCE_DIR``）和工作目录为项目目录。如果想获得当前组件的绝对路径，可以使用 ``COMPONENT_PATH`` 变量。 -.. warning:: +请注意，``project_include.cmake`` 对于大多数常见的组件并不是必需的。例如给项目添加 include 搜索目录，给最终的链接步骤添加 ``LDFLAGS`` 选项等等都可以通过 ``CMakeLists.txt`` 文件来自定义。详细信息请参考 :ref:`optional_project_variable`。 - 在此文件中设置变量或者目标时要小心，由于这些值包含在项目的顶层 makefile 中，因此他们可以影响或者破坏所有组件的功能！ +``project_include.cmake`` 文件会按照 ``BUILD_COMPONENTS`` 变量中组件的顺序（由 CMake 记录）依次导入。即只有在当前组件所有依赖组件的 ``project_include.cmake`` 文件都被导入后，当前组件的 ``project_include.cmake`` 文件才会被导入，除非两个组件在同一个依赖闭环中。如果某个 ``project_include.cmake`` 文件依赖于另一组件设置的变量，则要特别注意上述情况。更多详情请参阅 :ref:`component-requirements-implementation`。 + +在 ``project_include.cmake`` 文件中设置变量或目标时要格外小心，这些值被包含在项目的顶层 CMake 文件中，因此他们会影响或破坏所有组件的功能。 KConfig.projbuild ^^^^^^^^^^^^^^^^^ -这相当于 ``Makefile.projbuild`` 的组件配置 KConfig 文件，如果要在 menuconfig 的顶层添加配置选项，而不是在 ``组件配置`` 子菜单中，则可以在 ``component.mk`` 文件所在目录中的 KConfig.projbuild 文件中定义这些选项。 +与 ``project_include.cmake`` 类似，也可以为组件定义一个 KConfig 文件以实现全局的 :ref:`component-configuration`。如果要在 menuconfig 的顶层添加配置选项，而不是在 “Component Configuration” 子菜单中，则可以在 ``CMakeLists.txt`` 文件所在目录的 KConfig.projbuild 文件中定义这些选项。 -在此文件中添加配置时要小心，因为他们将包含在整个项目配置中，在可能的情况下，通常最好为组件创建和配置 KConfig 文件。 +在此文件中添加配置时要小心，因为这些配置会包含在整个项目配置中。在可能的情况下，请为 :ref:`component-configuration` 创建 KConfig 文件。 -Makefile.componentbuild -^^^^^^^^^^^^^^^^^^^^^^^ +.. _config_only_component: -对于一些特殊的组件，比如它们会使用工具从其余文件中生成源文件，这时就有必要将配置、宏或者变量的定义添加到每个组件的构建过程中。这是通过在组件目录中包含 ``Makefile.componentbuild`` 文件来实现的。此文件在 ``component.mk`` 文件之前被导入 ``component_wrapper.mk`` 中。同 ``Makefile.projbuild`` 文件一样，请留意这些文件，因为他们包含在每个组件的构建中，所有只有在编译完全不同的组件时才会出现 ``Makefile.componentbuild`` 错误。 - -仅配置的组件 -^^^^^^^^^^^^ - -仅配置的组件是一类不包含源文件的特殊组件，只有 ``Kconfig.projbuild`` 和 ``Makefile.projbuild`` 文件，可以在 ``conponent.mk`` 文件中设置标志 ``COMPONENT_CONFIG_ONLY``。如果设置了此标志，则忽略大多数其他组件变量，并且不会为组件执行构建操作。 - -.. _example-component-makefile: - -组件 Makefile 示例 -~~~~~~~~~~~~~~~~~~ - -因为构建环境试图设置大多数情况都能工作的合理默认值，所以 ``component.mk`` 可能非常小，甚至是空的，请参考 `最小组件 Makefile <#minimal-component-makefile>`_。但是某些功能通常需要覆盖组件的变量。 - -以下是 ``component.mk`` 的一些更高级的示例： - -增加源文件目录 -^^^^^^^^^^^^^^ - -默认情况下，将忽略子目录。如果您的项目在子目录中而不是在组件的根目录中有源文件，那么您可以通过设置 ``COMPONENT_SRCDIRS`` 将其告知构建系统： - -.. code:: - - COMPONENT_SRCDIRS := src1 src2 - -构建系统将会编译 src1/ 和 src2/ 子目录中的所有源文件。 - -.. _specify-source-files: - -指定源文件 +仅配置组件 ^^^^^^^^^^ -标准 ``component.mk`` 逻辑将源目录中的所有 .S 和 .c 文件添加为无条件编译的源。通过将 ``COMPONENT_OBJS`` 变量手动设置为需要生成的对象的名称，可以绕过该逻辑并对要编译的对象进行硬编码。 +仅配置组件是一类不包含源文件的特殊组件，仅包含 ``Kconfig.projbuild``、``KConfig`` 和 ``CMakeLists.txt`` 文件，该 ``CMakeLists.txt`` 文件仅有一行代码，调用了 ``register_config_only_component()`` 函数。此函数会将组件导入到项目构建中，但不会构建任何库，也不会将头文件添加到任何 include 搜索路径中。 -.. code:: +如果 CMakeLists.txt 文件没有调用 ``register_component()`` 或 ``register_config_only_component()``，那么该文件将会被排除在项目构建之外。根据项目的配置，有时可能需要这么做。 - COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o - COMPONENT_SRCDIRS := . thing anotherthing +.. _component_cmakelists_example: -请注意，还需要另外设置 ``COMPONENT_SRCDIRS`` 。 +组件 CMakeLists 示例 +==================== -.. _add-conditional-configuration: +因为构建环境试图设置大多数情况都能工作的合理默认值，所以组件 ``CMakeLists.txt`` 文件可能非常小，甚至是空的，请参考 :ref:`minimum_cmakelists`。但有些功能往往需要覆盖 :ref:`preset_component_variables` 才能实现。 + +以下是组件 CMakeLists 文件的更高级的示例。 + +.. _add_conditional_config: 添加条件配置 -^^^^^^^^^^^^ +------------ -配置系统可用于有条件地编译某些文件，具体取决于 ``make menuconfig`` 中选择的选项。为此，ESP-IDF 具有 ``compile_only_if`` 和 ``compile_only_if_not`` 的宏： +配置系统可用于根据项目配置中选择的选项有条件地编译某些文件。 -``Kconfig``: +.. highlight:: none -.. code:: +``Kconfig``:: - config FOO_ENABLE_BAR - bool "Enable the BAR feature." - help - This enables the BAR feature of the FOO component. + config FOO_ENABLE_BAR + bool "Enable the BAR feature." + help + This enables the BAR feature of the FOO component. -``component.mk``: +``CMakeLists.txt``:: -.. code:: + set(COMPONENT_SRCS "foo.c" "more_foo.c") - $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) + if(CONFIG_FOO_ENABLE_BAR) + list(APPEND COMPONENT_SRCS "bar.c") + endif() -从示例中可以看出， ``compile_only_if`` 宏将条件和目标文件列表作为参数。如果条件为真（在这种情况下：如果在 menuconfig 中启用了 BAR 功能），将始终编译目标文件（在本例中为 bar.o）。相反的情况也是如此，如果条件不成立，bar.o 将永远不会被编译。 ``compile_only_if_not`` 执行相反的操作，如果条件为 false 则编译，如果条件为 true 则不编译。 +上述示例使用了 CMake 的 `if `_ 函数和 `list APPEND `_ 函数。 -这也可以用于选择或者删除实现，如下所示： +也可用于选择或删除某一实现，如下所示： -``Kconfig``: +``Kconfig``:: -.. code:: + config ENABLE_LCD_OUTPUT + bool "Enable LCD output." + help + Select this if your board has a LCD. - config ENABLE_LCD_OUTPUT - bool "Enable LCD output." - help - Select this if your board has a LCD. + config ENABLE_LCD_CONSOLE + bool "Output console text to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output debugging output to the lcd - config ENABLE_LCD_CONSOLE - bool "Output console text to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output debugging output to the lcd + config ENABLE_LCD_PLOT + bool "Output temperature plots to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output temperature plots - config ENABLE_LCD_PLOT - bool "Output temperature plots to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output temperature plots +.. highlight:: cmake -``component.mk``: +``CMakeLists.txt``:: -.. code:: + if(CONFIG_ENABLE_LCD_OUTPUT) + set(COMPONENT_SRCS lcd-real.c lcd-spi.c) + else() + set(COMPONENT_SRCS lcd-dummy.c) + endif() - # If LCD is enabled, compile interface to it, otherwise compile dummy interface - $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o) - $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o) + # 如果启用了控制台或绘图功能，则需要加入字体 + if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT) + list(APPEND COMPONENT_SRCS "font.c") + endif() - #We need font if either console or plot is enabled - $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) -请注意使用 Make 或者函数来包含字体文件。其他的替换函数，比如 ``and`` 和 ``if`` 也适用于此处。也可以使用不在 menuconfig 中定义的变量，ESP-IDF 使用默认的 Make 策略，将一个空的或者只包含空格的变量视为 false ，而其中任何非空格的比那辆都为 true 。 +硬件目标的的条件判断 +-------------------- -（注意：本文档的历史版本建议将目标文件添加到 ``COMPONENT_OBJS`` 中，虽然这仍然可行，但是只有当组件中的所有目标文件都明确命名时才会起作用，并且在 ``make clean`` 后并不会清除 make 中取消选择的目标文件）。 +CMake 文件可以使用 ``IDF_TARGET`` 变量来获取当前的硬件目标。 -.. _source-code-generation: +此外，如果当前的硬件目标是 ``xyz``（即 ``IDF_TARGET=xyz``），那么 Kconfig 变量 ``CONFIG_IDF_TARGET_XYZ`` 同样也会被设置。 -源代码生成 -^^^^^^^^^^ +请注意，组件可以依赖 ``IDF_TARGET`` 变量，但不能依赖这个 Kconfig 变量。同样也不可在 CMake 文件的 ``include`` 语句中使用 Kconfig 变量，在这种上下文中可以使用 ``IDF_TARGET``。 -某些组件会出现源文件未随组件本身提供，而必须从另外一个文件生成的情况。假设我们的组件有一个头文件，该文件由 BMP 文件转换后的二进制数据组成，假设使用 bmp2h 的工具进行转换，然后将头文件包含在名为 graphics_lib.c 的文件中： -.. code:: +生成源代码 +---------- - COMPONENT_EXTRA_CLEAN := logo.h +有些组件的源文件可能并不是由组件本身提供，而必须从另外的文件生成。假设组件需要一个头文件，该文件由 BMP 文件转换后（使用 bmp2h 工具）的二进制数据组成，然后将头文件包含在名为 graphics_lib.c 的文件中:: - graphics_lib.o: logo.h + add_custom_command(OUTPUT logo.h + COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h + DEPENDS ${COMPONENT_DIR}/logo.bmp + VERBATIM) - logo.h: $(COMPONENT_PATH)/logo.bmp - bmp2h -i $^ -o $@ + add_custom_target(logo DEPENDS logo.h) + add_dependencies(${COMPONENT_LIB} logo) -这个示例会在当前目录（构建目录）中生成 graphics_lib.o 和 logo.h 文件，而 logo.bmp 随组件一起提供并位于组件路径下。因为 logo.h 是一个生成的文件，所以当调用 ``make clean`` 时需要清理它，这就是为什么要将它添加到 ``COMPONENT_EXTRA_CLEAN`` 变量中。 + set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY + ADDITIONAL_MAKE_CLEAN_FILES logo.h) -润色与改进 -^^^^^^^^^^ +这个示例改编自 `CMake 的一则 FAQ `_，其中还包含了一些同样适用于 ESP-IDF 构建系统的示例。 -将 logo.h 添加作为 ``graphics_lib.o`` 的依赖项会导致在编译 ``graphics_lib.c`` 之前先生成它。 +这个示例会在当前目录（构建目录）中生成 logo.h 文件，而 logo.bmp 会随组件一起提供在组件目录中。因为 logo.h 是一个新生成的文件，一旦项目需要清理，该文件也应该要被清除。因此，要将该文件添加到 `ADDITIONAL_MAKE_CLEAN_FILES`_ 属性中。 -如果另一个组件中的源文件需要使用 logo.h，则必须将此组件的名称添加到另一个组件的 ``COMPONENT_DEPENDS`` 列表中，以确保组件按顺序编译。 +.. Note:: + + 如果需要生成文件作为项目 CMakeLists.txt 的一部分，而不是作为组件 CMakeLists.txt 的一部分，此时需要使用 ``${PROJECT_PATH}`` 替代 ``${COMPONENT_DIR}``，使用 ``${PROJECT_NAME}.elf`` 替代 ``${COMPONENT_LIB}``。 + +如果某个源文件是从其他组件中生成，且包含 ``logo.h`` 文件，则需要调用 ``add_dependencies``， 在这两个组件之间添加一个依赖项，以确保组件源文件按照正确顺序进行编译。 嵌入二进制数据 -^^^^^^^^^^^^^^ +--------------------- -有时您的组件希望使用一个二进制文件或者文本文件，但是您又不希望将它重新格式化为 C 源文件。 +有时您的组件希望使用一个二进制文件或者文本文件，但是您又不希望将它们重新格式化为 C 源文件，这时，您可以在组件 CMakeLists 中添加 ``COMPONENT_EMBED_FILES`` 变量，指定要嵌入的文件名称（以空格分隔）:: -这时，您可以在 ``component.mk`` 文件中设置变量 ``COMPONENT_EMBED_FILES``，以这种方式指定要嵌入的文件的名称： + set(COMPONENT_EMBED_FILES server_root_cert.der) -.. code:: +或者，如果文件是字符串，则可以设置 ``COMPONENT_EMBED_TXTFILES`` 变量，把文件的内容转成以 null 结尾的字符串嵌入:: - COMPONENT_EMBED_FILES := server_root_cert.der + set(COMPONENT_EMBED_TXTFILES server_root_cert.pem) -或者，如果文件是字符串，则可以使用变量 ``COMPONENT_EMBED_TXTFILES``，这将把文本文件的内容当成以 null 结尾的字符串嵌入： +.. highlight:: c -.. code:: +文件的内容会被添加到 Flash 的 .rodata 段，用户可以通过符号名来访问，如下所示:: - COMPONENT_EMBED_TXTFILES := server_root_cert.pem + extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); + extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); -文件的内容会被编译进 flash 中的 .rodata 段，并通过符号名称来访问，如下所示： +符号名会根据文件全名生成，如 ``COMPONENT_EMBED_FILES`` 中所示，字符 ``/``、``.`` 等都会被下划线替代。符号名称中的 _binary 前缀由 objcopy 命令添加，对文本文件和二进制文件都是如此。 -.. code:: c +.. highlight:: cmake - extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); - extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); +如果要将文件嵌入到项目中，而非组件中，可以调用 ``target_add_binary_data`` 函数:: -符号名称是根据文件的全名生成的，如 ``COMPONENT_EMBED_FILES`` 中的所示，字符 / ， . ， 等都将会被下划线替代。符号名称中的 ``_binary`` 前缀由 ``objcopy`` 添加，对于文本和二进制文件都是相同的。 + target_add_binary_data(myproject.elf "main/data.bin" TEXT) -有关使用此技术的示例，请参考 :example:`protocols/https_request` - 证书文件的内容会在编译时从 .pem 文件中加载。 +并这行代码放在项目 CMakeLists.txt 的 ``project()`` 命令之后，修改 ``myproject.elf`` 为你自己的项目名。如果最后一个参数是 ``TEXT``，那么构建系统会嵌入以 null 结尾的字符串，如果最后一个参数被设置为 ``BINARY``，则将文件内容按照原样嵌入。 -.. _fully-overriding-component-makefile: +有关使用此技术的示例，请参考 :example:`protocols/https_request`，证书文件的内容会在编译时从 .pem 文件中加载。 -完全覆盖组件的 Makefile -~~~~~~~~~~~~~~~~~~~~~~~ +代码和数据的存放 +---------------- -显然，在某些情况下，所有这些配置都不足以满足某个组件，例如，当组件基本上是另一个第三方组件的包装器时，该第三方组件最初不打算在 ESP-IDF 构建系统下工作，在这种情况下，可以通过设置 ``COMPONENT_OWNBUILDTARGET`` 和可能的 ``COMPONENT_OWNCLEANTARGET``，并在 ``component.mk`` 中定义名为 ``build`` 和 ``clean`` 的目标。构建目标可以执行任何操作，只要它为项目生成了 ``$(COMPONENT_LIBRARY)`` ，并最终被链接到应用程序二进制文件中即可。 +ESP-IDF 还支持自动生成链接脚本，它允许组件通过链接片段文件定义其代码和数据在内存中的存放位置。构建系统会处理这些链接片段文件，并将处理后的结果扩充进链接脚本，从而指导应用程序二进制文件的链接过程。更多详细信息与快速上手指南，请参阅 :doc:`链接脚本生成机制 `。 -（实际上，这并不是必须的 - 如果 ``COMPONENT_ADD_LDFLAGS`` 变量被覆盖，那么组件可以指示链接器链接其他二进制文件。） +.. _component-build-full-override: + +完全覆盖组件的构建过程 +---------------------- + +.. highlight:: cmake + +当然，在有些情况下，上面提到的方法不一定够用。如果组件封装了另一个第三方组件，而这个第三方组件并不能直接在 ESP-IDF 的构建系统中工作，在这种情况下，就需要放弃 ESP-IDF 的构建系统，改为使用 CMake 的 ExternalProject_ 功能。组件 CMakeLists 示例如下:: + + # 用于 quirc 的外部构建过程，在源目录中运行并生成 libquirc.a + externalproject_add(quirc_build + PREFIX ${COMPONENT_DIR} + SOURCE_DIR ${COMPONENT_DIR}/quirc + CONFIGURE_COMMAND "" + BUILD_IN_SOURCE 1 + BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a + INSTALL_COMMAND "" + ) + + # 将 libquirc.a 添加到构建系统中 + add_library(quirc STATIC IMPORTED GLOBAL) + add_dependencies(quirc quirc_build) + + set_target_properties(quirc PROPERTIES IMPORTED_LOCATION + ${COMPONENT_DIR}/quirc/libquirc.a) + set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES + ${COMPONENT_DIR}/quirc/lib) + + set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES + "${COMPONENT_DIR}/quirc/libquirc.a") + +（上述 CMakeLists.txt 可用于创建名为 ``quirc`` 的组件，该组件使用自己的 Makefile 构建 quirc_ 项目。） + +- ``externalproject_add`` 定义了一个外部构建系统。 + + - 设置 ``SOURCE_DIR``、``CONFIGURE_COMMAND``、``BUILD_COMMAND`` 和 ``INSTALL_COMMAND``。如果外部构建系统没有配置这一步骤，可以将 ``CONFIGURE_COMMAND`` 设置为空字符串。在 ESP-IDF 的构建系统中，一般会将 ``INSTALL_COMMAND`` 变量设置为空。 + - 设置 ``BUILD_IN_SOURCE``，即构建目录与源目录相同。否则，您也可以设置 ``BUILD_DIR`` 变量。 + - 有关 ``externalproject_add()`` 命令的详细信息，请参阅 ExternalProject_。 + +- 第二组命令添加了一个目标库，指向外部构建系统生成的库文件。为了添加 include 目录，并告知 CMake 该文件的位置，需要再设置一些属性。 +- 最后，生成的库被添加到 `ADDITIONAL_MAKE_CLEAN_FILES`_ 中。即执行 ``make clean`` 后会删除该库。请注意，构建系统中的其他目标文件不会被删除。 + +.. note:: 当外部构建系统使用 PSRAM 时，请记得将 ``-mfix-esp32-psram-cache-issue`` 添加到 C 编译器的参数中。关于该标志的更多详细信息，请参考 :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`。 + +.. _ADDITIONAL_MAKE_CLEAN_FILES_note: + +ExternalProject 的依赖与构建清理 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +对于外部项目的构建，CMake 会有一些不同寻常的行为： + +- `ADDITIONAL_MAKE_CLEAN_FILES`_ 仅在使用 Make 构建系统时有效。如果使用 Ninja_ 或 IDE 自带的构建系统，执行项目清理时，这些文件不会被删除。 +- ExternalProject_ 会在 clean 运行后自动重新运行配置和构建命令。 +- 可以采用以下两种方法来配置外部构建命令： + + 1. 将外部 ``BUILD_COMMAND`` 命令设置为对所有源代码完整的重新编译。如果传递给 ``externalproject_add`` 命令的 ``DEPENDS`` 的依赖项发生了改变，或者当前执行的是项目清理操作（即运行了 ``idf.py clean``、``ninja clean`` 或者 ``make clean``），那么就会执行该命令。 + 2. 将外部 ``BUILD_COMMAND`` 命令设置为增量式构建命令，并给 ``externalproject_add`` 传递 ``BUILD_ALWAYS 1`` 参数。即不管实际的依赖情况，每次构建时，都会构建外部项目。这种方式仅当外部构建系统具备增量式构建的能力，且运行时间不会很长时才推荐。 + +构建外部项目的最佳方法取决于项目本身、其构建系统，以及是否需要频繁重新编译项目。 .. _custom-sdkconfig-defaults: 自定义 sdkconfig 的默认值 -~~~~~~~~~~~~~~~~~~~~~~~~~ +========================= -对于示例工程或者其他您不想指定完整 sdkconfig 配置的项目，但是您确实希望覆盖 ESP-IDF 默认值中的某些键值，则可以在项目中创建文件 ``sdkconfig.defaults``,运行 ``make defconfig`` 或从头创建新配置时将会使用此文件。 +对于示例工程或者其他您不想指定完整 sdkconfig 配置的项目，但是您确实希望覆盖 ESP-IDF 默认值中的某些键值，则可以在项目中创建 ``sdkconfig.defaults`` 文件。重新创建新配置时将会用到此文件，另外在 ``sdkconfig`` 没有设置新配置值时，上述文件也会被用到。 -要想覆盖此文件的名称，请设置 ``SDKCONFIG_DEFAULTS`` 环境变量。 +如若需要覆盖此文件的名称，请设置 ``SDKCONFIG_DEFAULTS`` 环境变量。 -保存 flash 参数 -~~~~~~~~~~~~~~~ +依赖于硬件目标的 sdkconfig 默认值 +--------------------------------- -在某些情况下，我们希望在没有 IDF 的情况下烧写目标板卡，对于这种情况，我们希望保存构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以简单编写一段脚本来保存二进制文件和 esptool.py，并且使用命令 ``make print_flash_cmd`` 来查看烧写 flash 时的参数。 +除了 ``sdkconfig.defaults`` 之外，构建系统还将从 ``sdkconfig.defaults.TARGET_NAME`` 文件加载默认值，其中 ``IDF_TARGET`` 的值为 ``TARGET_NAME``。例如，对于 ``ESP32`` 这个硬件目标，sdkconfig 的默认值会首先从 ``sdkconfig.defaults`` 获取，然后再从 ``sdkconfig.defaults.esp32`` 获取。 -.. code:: bash +如果使用 ``SDKCONFIG_DEFAULTS`` 覆盖了 sdkconfig 默认文件的名称，则硬件目标的 sdkconfig 默认文件名也会从 ``SDKCONFIG_DEFAULTS`` 值中派生。 - --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin +.. _flash_parameters: -然后使用这段 flash 参数作为 esptool write_flash 命令的参数： +Flash 参数 +========== -.. code:: bash +有些情况下，我们希望在没有 IDF 时也能烧写目标板卡，为此，我们希望可以保存已构建的二进制文件、esptool.py 和 esptool write_flash 命令的参数。可以通过编写一段简单的脚本来保存二进制文件和 esptool.py。 - python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin +运行项目构建之后，构建目录将包含项目二进制输出文件（``.bin`` 文件），同时也包含以下烧录数据文件： + +- ``flash_project_args`` 包含烧录整个项目的参数，包括应用程序 (app)、引导程序 (bootloader)、分区表，如果设置了 PHY 数据，也会包含此数据。 +- ``flash_app_args`` 只包含烧录应用程序的参数。 +- ``flash_bootloader_args`` 只包含烧录引导程序的参数。 + +.. highlight:: bash + +您可以参照如下命令将任意烧录参数文件传递给 ``esptool.py``:: + + python esptool.py --chip esp32 write_flash @build/flash_project_args + +也可以手动复制参数文件中的数据到命令行中执行。 + +构建目录中还包含生成的 ``flasher_args.json`` 文件，此文件包含 JSON 格式的项目烧录信息，可用于 ``idf.py`` 和其它需要项目构建信息的工具。 构建 Bootloader +=============== + +引导程序默认作为 ``idf.py build`` 的一部分被构建，也可以通过 ``idf.py bootloader`` 来单独构建。 + +引导程序是 :idf:`/components/bootloader/subproject` 内部独特的“子项目”，它有自己的项目 CMakeLists.txt 文件，能够构建独立于主项目的 ``.ELF`` 和 ``.BIN`` 文件，同时它又与主项目共享配置和构建目录。 + +子项目通过 :idf_file:`/components/bootloader/project_include.cmake` 文件作为外部项目插入到项目的顶层，主构建进程会运行子项目的 CMake，包括查找组件（主项目使用的组件的子集），生成引导程序专用的配置文件（从主 ``sdkconfig`` 文件中派生）。 + +选择硬件目标 +============ + +当前 ESP-IDF 仅支持一个硬件目标，即 ``esp32``，这也是构建系统默认的硬件目标。开发人员可以按照如下方法来添加对新硬件目标的支持:: + + rm sdkconfig + idf.py -DIDF_TARGET=new_target reconfigure + +.. _write-pure-component: + +编写纯 CMake 组件 +================= + +ESP-IDF 构建系统用“组件”的概念“封装”了 CMake，并提供了很多帮助函数来自动将这些组件集成到项目构建当中。 + +然而，“组件”概念的背后是一个完整的 CMake 构建系统，因此可以制作纯 CMake 组件。 + +.. highlight:: cmake + +下面是使用纯 CMake 语法为 ``json`` 组件编写的最小 CMakeLists 文件的示例:: + + add_library(json STATIC + cJSON/cJSON.c + cJSON/cJSON_Utils.c) + + target_include_directories(json PUBLIC cJSON) + +- 这实际上与 IDF 中的 :idf_file:`json 组件 ` 是等效的。 +- 因为组件中的源文件不多，所以这个 CMakeLists 文件非常简单。对于具有大量源文件的组件而言，ESP-IDF 支持的组件通配符，可以简化组件 CMakeLists 的样式。 +- 每当组件中新增一个与组件同名的库目标时，ESP-IDF 构建系统会自动将其添加到构建中，并公开公共的 include 目录。如果组件想要添加一个与组件不同名的库目标，就需要使用 CMake 命令手动添加依赖关系。 + +组件中使用第三方 CMake 项目 +=========================== + +CMake 在许多开源的 C/C++ 项目中广泛使用，用户可以在自己的应用程序中使用开源代码。CMake 构建系统的一大好处就是可以导入这些第三方的项目，有时候甚至不用做任何改动。这就允许用户使用当前 ESP-IDF 组件尚未提供的功能，或者使用其它库来实现相同的功能。 + +.. highlight:: cmake + +假设 ``main`` 组件需要导入一个假想库 ``foo``，相应的组件 CMakeLists 文件如下所示:: + + # 注册组件 + register_component() + + # 设置 `foo` 项目中的一些 CMake 变量，以控制 `foo` 的构建过程 + set(FOO_BUILD_STATIC OFF) + set(FOO_BUILD_TESTS OFF) + + # 创建并导入第三方库目标 + add_subdirectory(foo) + + # 将 IDF 全局的编译器设置、宏定义及其它选项传递给 `foo` 目标 + target_include_directories(foo ${IDF_INCLUDE_DIRECTORIES}) + target_compile_options(foo ${IDF_COMPILE_OPTIONS}) + target_compile_definitions(foo ${IDF_COMPILE_DEFINITIONS}) + + # 将 `foo` 目标链接至 `main` 组件 + target_link_libraries(main foo) + +实际的案例请参考 :example:`build_system/cmake/import_lib`。请注意，导入第三方库所需要做的工作可能会因库的不同而有所差异。建议仔细阅读第三方库的文档，了解如何将其导入到其它项目中。阅读第三方库的 CMakeLists.txt 文件以及构建结构也会有所帮助。 + +用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 `_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 `。 + +每当使用 ESP-IDF 构建系统时，CMake 变量 ``ESP_PLATFORM`` 都会被设置为 1。如果要在通用的 CMake 代码加入 IDF 特定的代码时，可以采用 ``if (ESP_PLATFORM)`` 的形式加以分隔。 + +在自定义 CMake 项目中使用 ESP-IDF +================================= + +ESP-IDF 提供了一个模板 CMake 项目，可以基于此轻松创建应用程序。然而在有些情况下，用户可能已有一个现成的 CMake 项目，或者想自己创建一个 CMake 项目，此时就希望将 IDF 中的组件以库的形式链接到用户目标（库/可执行文件）。 + +.. highlight:: cmake + +使用 :idf_file:`tools/cmake/idf_functions.cmake` 中提供的 ``idf_import_components`` 和 ``idf_link_components`` 函数可以实现上述功能，例如:: + + cmake_minimum_required(VERSION 3.5) + project(my_custom_app C) + + # 源文件 main.c 包含有 app_main() 函数的定义 + add_executable(${CMAKE_PROJECT_NAME}.elf main.c) + + # 提供 idf_import_components 及 idf_link_components 函数 + include($ENV{IDF_PATH}/tools/cmake/idf_functions.cmake) + + # 为 idf_import_components 做一些配置 + # 使能创建构件（不是每个项目都必须） + set(IDF_BUILD_ARTIFACTS ON) + set(IDF_PROJECT_EXECUTABLE ${CMAKE_PROJECT_NAME}.elf) + set(IDF_BUILD_ARTIFACTS_DIR ${CMAKE_BINARY_DIR}) + + # idf_import_components 封装了 add_subdirectory()，为组件创建库目标，然后使用给定的变量接收“返回”的库目标。 + # 在本例中，返回的库目标被保存在“component”变量中。 + idf_import_components(components $ENV{IDF_PATH} esp-idf) + + # idf_link_components 封装了 target_link_libraries()，将被 idf_import_components 处理过的组件链接到目标 + idf_link_components(${CMAKE_PROJECT_NAME}.elf "${components}") + +上述代码片段导入了 ESP-IDF 目录下的所有组件，并使用了 KConfig 中的默认值，同时还允许创建其它一些构件（比如分区表、包含项目信息的 json 文件、引导程序等）。除此以外，用户还可以设置其它的构建参数，其完整列表如下： + +- ``IDF_BUILD_ARTIFACTS``：构建工件，例如引导加载程序、分区表二进制文件、分区二进制数据、将二进制文件烧录到目标芯片时所需的包含项目信息的 json 文件等。同时需要设置 ``IDF_PROJECT_EXECUTABLE`` 和 ``IDF_BUILD_ARTIFACTS_DIR`` 变量。 +- ``IDF_PROJECT_EXECUTABLE``：最终可执行文件的名称。某些工件在创建的时候需要此参数。 +- ``IDF_BUILD_ARTIFACTS_DIR``：创建的构件被存放的位置。 +- ``IDF_EXTRA_COMPONENTS_DIR``：在 :idf:`默认组件目录 ` 之外的组件搜索路径。 +- ``IDF_COMPONENTS``：要导入的组件列表，设置此变量可以精简导入的组件，仅导入需要的组件，加快构建的速度。如果没有设置该变量，将会导入默认组件目录以及 ``IDF_EXTRA_COMPONENTS_DIR`` （如果设置了该变量）中找到的所有组件。请注意，该列表中组件的依赖组件（除了 ``IDF_COMPONENT_REQUIRES_COMMON`` 之外）也会被加入到构建之中。 +- ``IDF_COMPONENT_REQUIRES_COMMON``：通用组件依赖列表。无论 ``IDF_COMPONENTS`` 的值是什么，此列表中的组件及其依赖组件都会被导入到构建中。默认情况下，此变量被设置为核心“系统”组件的最小集合。 +- ``IDF_SDKCONFIG_DEFAULTS``：配置文件的覆盖路径，如果未设置，组件将会使用默认的配置选项来构建。 +- ``IDF_BUILD_TESTS``：在构建中包含组件的测试。默认情况下，所有的组件测试都会被包含。组件测试可通过 ``IDF_TEST_COMPONENTS`` 和 ``IDF_TEST_EXCLUDE_COMPONENTS`` 进行过滤。 +- ``IDF_TEST_COMPONENTS``：如果设置了 ``IDF_BUILD_TESTS``，构建中只会包含此列表中的组件测试。如果没有设置 ``IDF_BUILD_TESTS``，请忽略此项。 +- ``IDF_TEST_EXCLUDE_COMPONENTS``：如果设置了 ``IDF_BUILD_TESTS``，此列表中的组件测试将不会包含在构建中。如果没有设置 ``IDF_BUILD_TESTS``，请忽略此项。该变量的优先级高于 ``IDF_TEST_COMPONENTS``，这意味着，即使 ``IDF_TEST_COMPONENTS`` 中也存在此列表中的组件测试，它也不会被包含到构建之中。 + +:example:`build_system/cmake/idf_as_lib` 中的示例演示了如何在自定义的 CMake 项目创建一个类似于 :example:`Hello World ` 的应用程序。 + +.. _cmake-file-globbing: + +文件通配符 & 增量构建 +===================== + +.. highlight:: cmake + +在 ESP-IDF 组件中添加源文件的首选方法是在 ``COMPONENT_SRCS`` 中手动列出它们:: + + set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c) + +这是在 CMake 中手动列出源文件的 `最佳实践 `_。然而，当有许多源文件都需要添加到构建中时，这种方法就会很不方便。ESP-IDF 构建系统因此提供了另一种替代方法，即使用 ``COMPONENT_SRCDIRS`` 来指定源文件:: + + set(COMPONENT_SRCDIRS library platform) + +后台会使用通配符在指定的目录中查找源文件。但是请注意，在使用这种方法的时候，如果组件中添加了一个新的源文件，CMake 并不知道重新运行配置，最终该文件也没有被加入构建中。 + +如果是自己添加的源文件，这种折衷还是可以接受的，因为用户可以触发一次干净的构建，或者运行 ``idf.py reconfigure`` 来手动重启 CMake_。但是，如果你需要与其他使用 Git 等版本控制工具的开发人员共享项目时，问题就会变得更加困难，因为开发人员有可能会拉取新的版本。 + +ESP-IDF 中的组件使用了第三方的 Git CMake 集成模块（:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`），任何时候源码仓库的提交记录发生了改变，该模块就会自动重新运行 CMake。即只要 拉取了新的 ESP-IDF 版本，CMake 就会重新运行。 + +对于不属于 ESP-IDF 的项目组件，有以下几个选项供参考： + +- 如果项目文件保存在 Git 中，ESP-IDF 会自动跟踪 Git 修订版本，并在它发生变化时重新运行 CMake。 +- 如果一些组件保存在第三方 Git 仓库中（不在项目仓库或 ESP-IDF 仓库），则可以在组件 CMakeLists 文件中调用 ``git_describe`` 函数，以便在 Git 修订版本发生变化时自动重启 CMake。 +- 如果没有使用 Git，请记住在源文件发生变化时手动运行 ``idf.py reconfigure``。 +- 使用 ``COMPONENT_SRCS`` 在项目组件中列出所有源文件，可以完全避免这一问题。 + +具体选择哪一方式，就要取决于项目本身，以及项目用户。 + +.. _build_system_metadata: + +构建系统的元数据 +================ + +为了将 ESP-IDF 集成到 IDE 或者其它构建系统中，CMake 在构建的过程中会在 ``build/`` 目录下生成大量元数据文件。运行 ``cmake`` 或 ``idf.py reconfigure`` （或任何其它 ``idf.py`` 构建命令），可以重新生成这些元数据文件。 + +- ``compile_commands.json`` 是标准格式的 JSON 文件，它描述了在项目中参与编译的每个源文件。CMake 其中的一个功能就是生成此文件，许多 IDE 都知道如何解析此文件。 +- ``project_description.json`` 包含有关 ESP-IDF 项目、已配置路径等的一些常规信息。 +- ``flasher_args.json`` 包含 esptool.py 工具用于烧录项目二进制文件的参数，此外还有 ``flash_*_args`` 文件，可直接与 esptool.py 一起使用。更多详细信息请参阅 :ref:`flash_parameters`。 +- ``CMakeCache.txt`` 是 CMake 的缓存文件，包含 CMake 进程、工具链等其它信息。 +- ``config/sdkconfig.json`` 包含 JSON 格式的项目配置结果。 +- ``config/kconfig_menus.json`` 是在 menuconfig 中显示菜单的 JSON 格式版本，用于外部 IDE 的 UI。 + +JSON 配置服务器 --------------- -引导程序默认作为 ``make all`` 的一部分被构建，或者也可以通过 ``make bootloader-clean`` 来单独构建，此外还可以通过 ``make bootloader-list-components`` 来查看构建引导程序时包含的组件。 +.. highlight :: json -引导程序是一个特殊的组件，因为主项目中的二级引导程序拥有单独的 .EFL 和 .BIN 文件。但是它与主项目共享配置和构建目录。 +``confserver.py`` 工具可以帮助 IDE 轻松地与配置系统的逻辑进行集成，它运行在后台，通过使用 stdin 和 stdout 读写 JSON 文件的方式与调用进程交互。 -这是通过在 components/bootloader/subproject 下添加子项目来完成的。这个子项目有自己的 Makefile，但它希望通过 components/bootloader/Makefile.projectbuild 文件中的一些配置使自己从主项目的 Makefile 被调用。有关详细信息，请参阅这些文件。 +您可以通过 ``idf.py confserver`` 或 ``ninja confserver`` 从项目中运行 ``confserver.py``，也可以使用不同的构建生成器来触发类似的目标。 + +配置服务器会向 stderr 输出方便阅读的错误和警告信息，向 stdout 输出 JSON 文件。启动时，配置服务器将以 JSON 字典的形式输出系统中每个配置项的完整值，以及范围受限的值的可用范围。``sdkconfig.json`` 中包含有相同的信息:: + + {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } } + +配置服务器仅发送可见的配置项，其它不可见的或者被禁用的配置项可从 ``kconfig_menus.json`` 静态文件中解析得到，此文件还包含菜单结构和其它元数据（描述、类型、范围等）。 + +然后配置服务器将等待客户端的输入，客户端会发起请求，要求更改一个或多个配置项的值，内容的格式是个 JSON 对象，后面跟一个换行符:: + + {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } } + +配置服务器将解析此请求，更新 ``sdkconfig`` 文件，并返回完整的变更列表:: + + {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}} + +当前不可见或者禁用的配置项会返回 ``null``，任何新的可见配置项则会返回其当前新的可见值。 + +如果配置项的取值范围因另一个值的变化发生了改变，那么配置服务器会发送:: + + {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } } + +如果传递的数据无效，那么 JSON 对象中会有 ``error`` 字段:: + + {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]} + +默认情况下，变更后的配置不会被写进 sdkconfig 文件。更改的内容在发出 “save” 命令之前会先储存在内存中:: + + {"version": 1, "save": null } + +若要从已保存的文件中重新加载配置值，并丢弃内存中的任何更改，可以发送 “load” 命令:: + + {"version": 1, "load": null } + +“load” 和 “save” 的值可以是新的路径名，也可以设置为 "null" 用以加载/保存之前使用的路径名。 + +配置服务器对 “load” 命令的响应始终是完整的配置值和取值范围的集合，这与服务器初始启动阶段的响应相同。 + +“load”、“set” 和 “save” 的任意组合可以在一条单独的命令中发送出去，服务器按照组合中的顺序执行命令。因此，可以使用一条命令实现从文件中加载配置，更新配置值，然后将其保存到文件中。 + +.. Note:: 配置服务器不会自动加载外部对 ``sdkconfig`` 文件的任何更改。如果文件被外部编辑，则需要发送 “load” 命令或重启服务器。 + +.. Note:: ``sdkconfig`` 文件更新后，配置服务器不会重新运行 CMake 来生成其它的构建文件和元数据文件。这些文件会在下一次运行 ``CMake`` 或 ``idf.py`` 时自动生成。 + +.. _gnu-make-to: + +从 ESP-IDF GNU Make 构建系统迁移到 CMake 构建系统 +================================================= + +ESP-IDF CMake 构建系统与旧版的 GNU Make 构建系统在某些方面非常相似，例如将 ``component.mk`` 文件改写 ``CMakeLists.txt``，像 ``COMPONENT_ADD_INCLUDEDIRS`` 和 ``COMPONENT_SRCDIRS`` 等变量可以保持不变，只需将语法改为 CMake 语法即可。 + +自动转换工具 +------------ + +.. highlight:: bash + +:idf_file:`/tools/cmake/convert_to_cmake.py` 中提供了一个项目自动转换工具。运行此命令时需要加上项目路径，如下所示:: + + $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir + +项目目录必须包含 Makefile 文件，并确保主机已安装 GNU Make (``make``) 工具，并且被添加到了 PATH 环境变量中。 + +该工具会将项目 Makefile 文件和所有组件的 ``component.mk`` 文件转换为对应的 ``CMakeLists.txt`` 文件。 + +转换过程如下：该工具首先运行 ``make`` 来展开 ESP-IDF 构建系统设置的变量，然后创建相应的 CMakelists 文件来设置相同的变量。 + +转换工具并不能处理复杂的 Makefile 逻辑或异常的目标，这些需要手动转换。 + +CMake 中不可用的功能 +-------------------- + +有些功能已从 CMake 构建系统中移除，或者已经发生很大改变。GNU Make 构建系统中的以下变量已从 CMake 构建系统中删除： + +- ``COMPONENT_BUILD_DIR``：由 ``CMAKE_CURRENT_BINARY_DIR`` 替代。 +- ``COMPONENT_LIBRARY``：默认为 ``$(COMPONENT_NAME).a`` 但是库名可以被组件覆盖。在 CMake 构建系统中，组件库名称不可再被组件覆盖。 +- ``CC``、``LD``、``AR``、``OBJCOPY``：gcc xtensa 交叉工具链中每个工具的完整路径。CMake 使用 ``CMAKE_C_COMPILER``、``CMAKE_C_LINK_EXECUTABLE`` 和 ``CMAKE_OBJCOPY`` 进行替代。完整列表请参阅 `CMake 语言变量 `_。 +- ``HOSTCC``、``HOSTLD``、``HOSTAR``：宿主机本地工具链中每个工具的全名。CMake 系统不再提供此变量，外部项目需要手动检测所需的宿主机工具链。 +- ``COMPONENT_ADD_LDFLAGS``：用于覆盖链接标志。CMake 中使用 `target_link_libraries`_ 命令替代。 +- ``COMPONENT_ADD_LINKER_DEPS``：链接过程依赖的文件列表。`target_link_libraries`_ 通常会自动推断这些依赖。对于链接脚本，可以使用自定义的 CMake 函数 ``target_linker_scripts``。 +- ``COMPONENT_SUBMODULES``：不再使用。CMake 会自动枚举 ESP-IDF 仓库中所有的子模块。 +- ``COMPONENT_EXTRA_INCLUDES``：曾是 ``COMPONENT_PRIV_INCLUDEDIRS`` 变量的替代版本，仅支持绝对路径。CMake 系统中统一使用 ``COMPONENT_PRIV_INCLUDEDIRS`` （可以是相对路径，也可以是绝对路径）。 +- ``COMPONENT_OBJS``：以前，可以以目标文件列表的方式指定组件源，现在，可以通过 ``COMPONENT_SRCS`` 以源文件列表的形式指定组件源。 +- ``COMPONENT_OBJEXCLUDE``：已被 ``COMPONENT_SRCEXCLUDE`` 替换。用于指定源文件（绝对路径或组件目录的相对路径）。 +- ``COMPONENT_EXTRA_CLEAN``：已被 ``ADDITIONAL_MAKE_CLEAN_FILES`` 属性取代，注意，:ref:`CMake 对此项功能有部分限制 `。 +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 `_ 替代，详细内容请参阅 :ref:`component-build-full-override`。 +- ``COMPONENT_CONFIG_ONLY``：已被 ``register_config_only_component()`` 函数替代，请参阅 :ref:`config_only_component`。 +- ``CFLAGS``、``CPPFLAGS``、``CXXFLAGS``：已被相应的 CMake 命令替代，请参阅 :ref:`component_build_control`。 + +无默认值的变量 +-------------- + +以下变量不再具有默认值： + +- ``COMPONENT_SRCDIRS`` +- ``COMPONENT_ADD_INCLUDEDIRS`` + +不再需要的变量 +-------------- + +如果设置了 ``COMPONENT_SRCS``，就不需要再设置 ``COMPONENT_SRCDIRS``。实际上，CMake 构建系统中如果设置了 ``COMPONENT_SRCDIRS``，那么 ``COMPONENT_SRCS`` 就会被忽略。 + +从 Make 中烧录 +-------------- + +仍然可以使用 ``make flash`` 或者类似的目标来构建和烧录，但是项目 ``sdkconfig`` 不能再用来指定串口和波特率。可以使用环境变量来覆盖串口和波特率的设置，详情请参阅 :ref:`flash-with-ninja-or-make`。 + +.. _esp-idf-template: https://github.com/espressif/esp-idf-template +.. _Cmake: https://cmake.org +.. _ninja: https://ninja-build.org +.. _esptool.py: https://github.com/espressif/esptool/#readme +.. _CMake v3.5 官方文档: https://cmake.org/cmake/help/v3.5/index.html +.. _cmake 命令行文档: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options +.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/add_library.html +.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html +.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html +.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html +.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html +.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html +.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F +.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html +.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html +.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages +.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html +.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html +.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries +.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html +.. _quirc: https://github.com/dlbeer/quirc +.. _pyenv: https://github.com/pyenv/pyenv#README +.. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/zh_CN/api-guides/console.rst b/docs/zh_CN/api-guides/console.rst index c7a6408ac..45872445f 100644 --- a/docs/zh_CN/api-guides/console.rst +++ b/docs/zh_CN/api-guides/console.rst @@ -16,7 +16,7 @@ ESP-IDF 提供了 ``console`` 组件，它包含了开发基于串口的交互 行编辑功能允许用户通过按键输入来编辑命令，使用退格键删除符号，使用左/右键在命令中移动光标，使用上/下键导航到之前输入的命令，使用制表键（“Tab”）来自动补全命令。 -.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[esp32]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``make monitor`` 来调用）。 +.. note:: 此功能依赖于终端应用程序对 ANSI 转移符的支持，显示原始 UART 数据的串口监视器不能与行编辑库一同使用。如果运行 get_started/console 示例程序的时候观察到的输出结果是 ``[6n`` 或者类似的转义字符而不是命令行提示符 ``[esp32]>`` 时，就表明当前的串口监视器不支持 ANSI 转移字符。已知可用的串口监视程序有 GNU screen，minicom 和 idf_monitor.py（可以通过在项目目录下执行 ``idf.py monitor`` 来调用）。 前往这里可以查看 `linenoise `_ 库提供的所有函数的描述。 diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index a45461678..03163469a 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -7,7 +7,7 @@ API 指南 一般注意事项 构建系统 - 构建系统 (CMake) + 构建系统 (传统 GNU Make) 错误处理 严重错误 Event Handling @@ -21,10 +21,10 @@ API 指南 Bootloader 分区表 Secure Boot <../security/secure-boot> - ULP Coprocessor - ULP 协处理器 (CMake) + ULP 协处理器 + ULP ( CMake) 单元测试 - 单元测试 (CMake) + 单元测试 (传统 GNU Make) 应用层跟踪 控制台终端组件 ROM debug console diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst index f440d3c5a..f8d2f0843 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst @@ -8,7 +8,7 @@ 配置硬件 ^^^^^^^^ -1. 根据 :doc:`../../hw-reference/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options-cmake` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。 +1. 根据 :doc:`../../hw-reference/get-started-wrover-kit` 文档中 :ref:`get-started-esp-wrover-kit-v4.1-setup-options` 章节所描述的信息，设置 JP8 便可以启用 JTAG 功能。 2. 检查 ESP32 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index 32823497f..8d525a77c 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -194,7 +194,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G 上传待调试的应用程序 ~~~~~~~~~~~~~~~~~~~~ -您可以像往常一样构建并上传 ESP32 应用程序，具体请参阅 :ref:`get-started-build-and-flash` 章节。 +您可以像往常一样构建并上传 ESP32 应用程序，具体请参阅 :ref:`get-started-build` 章节。 除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下:: diff --git a/docs/zh_CN/api-guides/jtag-debugging/setup-openocd-windows.rst b/docs/zh_CN/api-guides/jtag-debugging/setup-openocd-windows.rst index 740af5b5e..6cd2e508c 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/setup-openocd-windows.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/setup-openocd-windows.rst @@ -6,7 +6,7 @@ IDF 工具安装程序 ================ -如果您正在使用 CMake 构建系统，并遵循 :doc:`/get-started-cmake/windows-setup` 章节的指导使用了 ``ESP-IDF Tools Installer`` 的 V1.2 及其以上版本，那么默认情况下您已经安装好了 ``OpenOCD`` 软件。 +如果您正在使用 CMake 构建系统，并遵循 :doc:`/get-started/windows-setup` 章节的指导使用了 ``ESP-IDF Tools Installer`` 的 V1.2 及其以上版本，那么默认情况下您已经安装好了 ``OpenOCD`` 软件。 ``ESP-IDF Tools Installer`` 会将 ``OpenOCD`` 添加到环境变量 ``PATH`` 中，这样你就可以在任何目录运行它。 diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index fe04714c8..2588c8aa1 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -57,7 +57,7 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设 * :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` 默认会被使能。如果程序抛出了不可修复或者未处理的异常，并且此时已经连接上了 JTAG 调试器（即 OpenOCD 正在运行），那么 ESP-IDF 将会进入调试器工作模式。 * :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 默认没有使能。在所有任务堆栈的末尾设置观察点，从 1 号开始索引。这是调试任务堆栈溢出的最准确的方式。 -更多有关设置编译时的选项的信息，请参阅 :ref:`make menuconfig `。 +更多有关设置编译时的选项的信息，请参阅 :ref:`idf.py menuconfig `。 .. _jtag-debugging-tip-freertos-support: diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index deff7c14c..c4b84a618 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -11,12 +11,12 @@ 分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。 -在使用分区表时，最简单的方法就是用 `make menuconfig` 选择一张预定义的分区表： +在使用分区表时，最简单的方法就是用 `idf.py menuconfig` 选择一张预定义的分区表： - "Single factory app, no OTA" - "Factory app, two OTA definitions" -在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `make partition_table` ，即可以打印当前使用分区表的信息摘要。 +在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `idf.py partition_table` ，即可以打印当前使用分区表的信息摘要。 内置分区表 ------------ @@ -102,7 +102,7 @@ SubType 字段长度为 8 bit，内容与具体 Type 有关。目前，esp-idf - phy (1) 分区用于存放 PHY 初始化数据，从而保证可以为每个设备单独配置 PHY，而非必须采用固件中的统一 PHY 初始化数据。 - 默认配置下，phy 分区并不启用，而是直接将 phy 初始化数据编译至应用程序中，从而节省分区表空间（直接将此分区删掉）。 - - 如果需要从此分区加载 phy 初始化数据，请运行 ``make menuconfig``，并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。 + - 如果需要从此分区加载 phy 初始化数据，请运行 ``idf.py menuconfig``，并且使能 :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` 选项。此时，您还需要手动将 phy 初始化数据烧至设备 flash（esp-idf 编译系统并不会自动完成该操作）。 - nvs (2) 是专门给 :doc:`非易失性存储 (NVS) API <../api-reference/storage/nvs_flash>` 使用的分区。 - 用于存储每台设备的 PHY 校准数据（注意，并不是 PHY 初始化数据）。 @@ -142,7 +142,7 @@ Flags 字段 烧写到 ESP32 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。 -如果您在 ``make menuconfig`` 指定了分区表 CSV 文件的名称，然后执行 ``make partition_table``。这时，转换将在编译过程中自动完成。 +如果您在 ``idf.py menuconfig`` 指定了分区表 CSV 文件的名称，然后执行 ``idf.py partition_table``。这时，转换将在编译过程中自动完成。 手动将 CSV 文件转换为二进制文件: @@ -152,7 +152,7 @@ Flags 字段 python gen_esp32part.py binary_partitions.bin input_partitions.csv -在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``make partition_table`` 时，我们正是这样打印上文展示的信息摘要的）: +在标准输出（stdout）上，打印二进制分区表的内容（在运行 ``idf.py partition_table`` 时，我们正是这样打印上文展示的信息摘要的）: python gen_esp32part.py binary_partitions.bin @@ -166,13 +166,13 @@ MD5 校验和 烧写分区表 ---------- -- ``make partition_table-flash`` ：使用 esptool.py 工具烧写分区表。 -- ``make flash`` ：会烧写所有内容，包括分区表。 +- ``idf.py partition_table-flash`` ：使用 esptool.py 工具烧写分区表。 +- ``idf.py flash`` ：会烧写所有内容，包括分区表。 -在执行 ``make partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。 +在执行 ``idf.py partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。 .. note:: - 分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``make erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 + 分区表的更新并不会擦除根据之前分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。 .. _secure boot: security/secure-boot.rst diff --git a/docs/zh_CN/api-guides/tools/idf-monitor.rst b/docs/zh_CN/api-guides/tools/idf-monitor.rst index d756422da..72651108f 100644 --- a/docs/zh_CN/api-guides/tools/idf-monitor.rst +++ b/docs/zh_CN/api-guides/tools/idf-monitor.rst @@ -8,8 +8,9 @@ IDF 监视器是一个串行终端程序，用于收发目标设备串口的串 在 IDF 中调用以下目标函数可以启用此监视器： -- **若使用 Make 编译系统，请调用**：``make monitor`` - **若使用 CMake 编译系统，则请调用**：``idf.py monitor`` +- **若使用传统 GNU Make 编译系统，请调用**：``make monitor`` + 操作快捷键 @@ -26,7 +27,7 @@ Ctrl+T 菜单退出键 - Ctrl+] 将 exit 字符发送至远程 - Ctrl+P 重置目标设备，进入 Bootloader，通过 RTS 线暂停应用程序 重置目标设备，通过 RTS 线（如已连接）进入 Bootloader，此时开发板不运行任何程序。等待其他设备启动时可以使用此操作。 - Ctrl+R 通过 RTS 线重置目标设备 重置设备，并通过 RTS 线（如已连接）重新启动应用程序。 -- Ctrl+F 编译并烧录此项目 暂停 idf_monitor，运行 ``make flash`` (``idf.py flash``) 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。 +- Ctrl+F 编译并烧录此项目 暂停 idf_monitor，运行 ``idf.py flash`` 目标，然后恢复 idf_monitor。任何改动的源文件都会被重新编译，然后重新烧录。 - Ctrl+A (A) 仅编译及烧录应用程序 暂停 idf_monitor，运行 ``app-flash`` 目标，然后恢复 idf_monitor。 这与 ``flash`` 类似，但只有主应用程序被编译并被重新烧录。 - Ctrl+Y 停止/恢复日志输出在屏幕上打印 激活时，会丢弃所有传入的串行数据。允许在不退出监视器的情况下快速暂停和检查日志输出。 - Ctrl+L 停止/恢复向文件写入日志输出 在工程目录下创建一个文件，用于写入日志输出。可使用快捷键停止/恢复该功能（退出 IDF 监视器也会终止该功能） @@ -91,7 +92,7 @@ IDF 监视器在后台运行以下命令，解码各地址:: 或者选择配置 panic 处理器以运行 GDBStub，GDBStub 工具可以与 GDB_ 项目调试器进行通信，允许读取内存、检查调用堆栈帧和变量等。GDBStub 虽然没有 JTAG 通用，但不需要使用特殊硬件。 -如需启用 GDBStub，请运行 ``make menuconfig`` （适用于 Make 编译系统）或 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 +如需启用 GDBStub，请运行 ``idf.py menuconfig`` （适用于 CMake 编译系统），并将 :ref:`CONFIG_ESP32_PANIC` 选项设置为 ``Invoke GDBStub``。 在这种情况下，如果 panic 处理器被触发，只要 IDF 监视器监控到 GDBStub 已经加载，panic 处理器就会自动暂停串行监控并使用必要的参数运行 GDB。GDB 退出后，通过 RTS 串口线复位开发板。如果未连接 RTS 串口线，请按复位键，手动复位开发板。 @@ -103,7 +104,7 @@ IDF 监控器在后台运行如下命令:: 输出筛选 ~~~~~~~~~~~~~~~~ -IDF 监视器有两种启用方式：运行 ``make monitor PRINT_FILTER=""`` （适用于 Make）或者 ``idf.py monitor --print-filter=""`` （适用于 CMake），其中，``PRINT_FILTER`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。 +IDF 监视器有两种启用方式：运行 ``idf.py monitor PRINT_FILTER=""`` （适用于 CMake） 或者 ``make monitor PRINT_FILTER=""`` （适用于传统 GNU Make），其中，``--print-filter`` 是输出筛选的参数。参数默认值为空字符串，可打印任何内容。 若需对打印内容设置限制，可指定 ``:`` 等选项，其中 ```` 是标签字符串，```` 是 ``{N, E, W, I, D, V, *}`` 集合中的一个字母，指的是 :doc:`日志 <../../api-reference/system/log>` 级别。 @@ -159,18 +160,6 @@ IDF 监视器有两种启用方式：运行 ``make monitor PRINT_FILTER=""`` （ D (309) light_driver: [light_init, 74]:status: 1, mode: 2 -简单监视器 -============== - -较早版本的 ESP-IDF 使用 pySerial_ 命令行工具 miniterm_ 作为串行控制台程序。 - -.. note:: 仅适用于 Make 编译系统，不适用于 CMake 编译系统。 - -此程序仍然可以通过 ``make simple_monitor`` 运行。 - -IDF 监视器基于 miniterm，可使用相同的快捷键。 - - IDF 监视器已知问题 ============================= diff --git a/docs/zh_CN/api-guides/ulp-cmake.rst b/docs/zh_CN/api-guides/ulp-cmake.rst deleted file mode 100644 index 345042588..000000000 --- a/docs/zh_CN/api-guides/ulp-cmake.rst +++ /dev/null @@ -1,167 +0,0 @@ -ULP 协处理器编程 (CMake) -=================================== - -:link_to_translation:`en:[English]` - -.. toctree:: - :maxdepth: 1 - - 指令集参考 - 使用宏进行编程（遗留） - - -ULP（Ultra Low Power 超低功耗）协处理器是一种简单的有限状态机 (FSM)，可以在主处理器处于深度睡眠模式时，使用 ADC、温度传感器和外部 I2C 传感器执行测量操作。ULP 协处理器可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设寄存器。ULP 协处理器使用 32 位固定宽度的指令，32 位内存寻址，配备 4 个 16 位通用寄存器。 - -安装工具链 ------------------------- - -ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 工具链`_ 进行编译。 - -1. 从提供的网址中下载最新工具链的预编译二进制文件：https://github.com/espressif/binutils-esp32ulp/releases. - -2. 将工具链解压缩到一个目录中，并将工具链的 ``bin/`` 目录路径添加到 ``PATH`` 环境变量中。 - -编译 ULP 代码 ------------------- - -若需要将 ULP 代码编译为某组件的一部分，则必须执行以下步骤： - -1. 用汇编语言编写的 ULP 代码必须导入到一个或多个 .S 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。 - -.. note: - 该目录不要添加到 ``COMPONENT_SRCDIRS`` 环境变量中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``COMPONENT_SRCDIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``xtensa-esp32-elf-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别的最简单方法就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也不应该添加到 ``COMPONENT_SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。 - -2. 修改组件 CMakeLists.txt，添加必要的 ULP CMake 定义，示例如下:: - - set(ULP_APP_NAME ulp_${COMPONENT_NAME}) - set(ULP_S_SOURCES ulp/ulp_assembly_source_file.S) - set(ULP_EXP_DEP_SRCS "ulp_c_source_file.c") - include(${IDF_PATH}/components/ulp/component_ulp_common.cmake) - -代码解释如下： - -``set(ULP_APP_NAME ulp_${COMPONENT_NAME})`` - 为生成的 ULP 应用程序设置名称，不带扩展名。此名称用于 ULP 应用程序的构建输出：ELF 文件、.map 文件、二进制文件、生成的头文件和链接器导出文件。 - -``set(ULP_S_SOURCES "ulp/ulp_assembly_source_file_1.S ulp/ulp_assembly_source_file_2.S")`` - 设置要传递给 ULP 汇编器的程序集文件列表，用空格隔开，路径可以是绝对路径，也可以是组件 CMakeLists.txt 的相对路径。 - -``set(ULP_EXP_DEP_SRCS "ulp_c_source_file_1.c ulp_c_source_file_2.c")`` - 设置组件中源文件名称的列表。所有包含被生成的头文件的原文件都必须在列表里。此列表建立正确构建依赖项，并确保在构建过程会先生成才编译包含头文件的原文件。请参考下文，查看为 ULP 应用程序生成的头文件等相关概念。此列表需要用空格隔开，路径可以是组件 CMakeLists.txt 文件的相对路径，也可以是绝对路径。 - -``include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)`` - 包含 ULP 编译步骤的通用定义。使用 ULP 工具链为 ULP 目标文件、ELF 文件、二进制文件等设置编译规则。 - -3. 使用常规方法（例如 `idf.py app`）编译应用程序 - - 在内部，编译系统将按照以下步骤编译 ULP 程序： - - 1. **通过 C 预处理器运行每个程序集文件 (foo.S)。** 此步骤在组件编译目录中生成预处理的程序集文件 (foo.ulp.S)，同时生成依赖文件 (foo.ulp.d)。 - - 2. **通过汇编器运行预处理过的汇编源码。** 此步骤会生成目标文件 (foo.ulp.o) 和清单 (foo.ulp.lst)。清单文件仅用于调试，不用于编译进程的后续步骤。 - - 3. **通过 C 预处理器运行链接器脚本模板。** 模板位于 components/ulp/ld 目录中。 - - 4. **将目标文件链接到 ELF 输出文件** (ulp_app_name.elf)。此步骤生成的.map 文件 (ulp_app_name.map) 默认用于调试。 - - 5. **将 ELF 文件中的内容转储为二进制文件** (ulp_app_name.bin)，以便嵌入到应用程序中。 - - 6. **使用 esp32ulp-elf-nm 在 ELF 文件中生成全局符号列表** (ulp_app_name.sym)。 - - 7. **创建 LD 导出脚本和头文件** (ulp_app_name.ld 和 ulp_app_name.h)，包含来自 ulp_app_name.sym 的符号。此步骤可借助 esp32ulp_mapgen.py 工具来完成。 - - 8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。** - -访问 ULP 程序变量 -------------------------------- - -在 ULP 程序中定义的全局符号也可以在主程序中使用。 - -例如，ULP 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数:: - - .global measurement_count - measurement_count: .long 0 - - /* later, use measurement_count */ - move r3, measurement_count - ld r3, r3, 0 - -主程序需要在启动 ULP 程序之前初始化 ``measurement_count`` 变量，编译系统生成 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件可以实现上述操作，这些文件在 ULP 编程中定义了全局符号，包含了在 ULP 程序中定义的所有全局符号，前缀为 ``ulp_``。 - -头文件包含对此类符号的声明:: - - extern uint32_t ulp_measurement_count; - -注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。对于函数和数组，先获取符号地址，然后转换为适当的类型。 - -生成的链接器脚本文件定义了 RTC_SLOW_MEM 中的符号位置:: - - PROVIDE ( ulp_measurement_count = 0x50000060 ); - -如果要从主程序访问 ULP 程序变量，先包含生成的头文件，并使用上述变量，操作如下:: - - #include "ulp_app_name.h" - - // later - void init_ulp_vars() { - ulp_measurement_count = 64; - } - -注意，ULP 程序在 RTC 内存中只能使用 32 位字的低 16 位，因为寄存器是 16 位的，并且不具备从字的高位加载的指令。 - -同样，ULP 储存指令将寄存器值写入 32 位字的低 16 位中。高 16 位写入的值取决于储存指令的地址，因此在读取 ULP 写的变量时，主应用程序需要屏蔽高 16 位，例如:: - - printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX); - -启动 ULP 程序 ------------------------- - -要运行 ULP 程序，主应用程序需要调用 ``ulp_load_binary`` 函数将 ULP 程序加载到 RTC 内存中，然后调用 ``ulp_run`` 函数，启动 ULP 程序。 - -注意，在 menuconfig 中必须启用 "Enable Ultra Low Power (ULP) Coprocessor" 选项，以便为 ULP 预留内存。"RTC slow memory reserved for coprocessor" 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序，则 RTC 内存必须足以容纳最大的程序。 - -每个 ULP 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB （假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``）:: - - extern const uint8_t bin_start[] asm("_binary_ulp_app_name_bin_start"); - extern const uint8_t bin_end[] asm("_binary_ulp_app_name_bin_end"); - - void start_ulp_program() { - ESP_ERROR_CHECK( ulp_load_binary( - 0 /* load address, set to 0 when using default linker scripts */, - bin_start, - (bin_end - bin_start) / sizeof(uint32_t)) ); - } - -.. doxygenfunction:: ulp_load_binary - -一旦上述程序加载到 RTC 内存后，应用程序即可启动此程序，并将入口点的地址传递给 ``ulp_run`` 函数:: - - ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) ); - -.. doxygenfunction:: ulp_run - -上述生成的头文件 ``${ULP_APP_NAME}.h`` 声明了入口点符号。在 ULP 应用程序的汇编源代码中，此符号必须标记为 ``.global``:: - - - .global entry - entry: - /* code starts here */ - - -ULP 程序流 ----------------- - -ULP 协处理器由定时器启动，而调用 ``ulp_run`` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 150 KHz 晶振器生成）。使用 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器 (x = 0..4) 设置 Tick 数值。第一次启动 ULP 时，使用 ``SENS_ULP_CP_SLEEP_CYC0_REG`` 设置定时器 Tick 数值，之后，ULP 程序可以使用 ``sleep`` 指令来另外选择 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器。 - -此应用程序可以调用 ``ulp_set_wakeup_period`` 函数来设置 ULP 定时器周期值 (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4)。 - -.. doxygenfunction:: ulp_set_wakeup_period - -一旦定时器达到在所选的 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器中设置的数值，ULP 协处理器就会启动，并调用 ``ulp_run`` 的入口点开始运行程序。 - -程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。 - -如果想禁用定时器（有效防止 ULP 程序再次运行），请清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位，可在 ULP 代码或主程序中进行以上操作。 - - -.. _binutils-esp32ulp 工具链: https://github.com/espressif/binutils-esp32ulp diff --git a/docs/zh_CN/api-guides/ulp-legacy.rst b/docs/zh_CN/api-guides/ulp-legacy.rst new file mode 100644 index 000000000..976d6db28 --- /dev/null +++ b/docs/zh_CN/api-guides/ulp-legacy.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/ulp.rst \ No newline at end of file diff --git a/docs/zh_CN/api-guides/ulp.rst b/docs/zh_CN/api-guides/ulp.rst index 976d6db28..a6b8f9246 100644 --- a/docs/zh_CN/api-guides/ulp.rst +++ b/docs/zh_CN/api-guides/ulp.rst @@ -1 +1,167 @@ -.. include:: ../../en/api-guides/ulp.rst \ No newline at end of file +ULP 协处理器编程 +=================================== + +:link_to_translation:`en:[English]` + +.. toctree:: + :maxdepth: 1 + + 指令集参考 + 使用宏进行编程（遗留） + + +ULP（Ultra Low Power 超低功耗）协处理器是一种简单的有限状态机 (FSM)，可以在主处理器处于深度睡眠模式时，使用 ADC、温度传感器和外部 I2C 传感器执行测量操作。ULP 协处理器可以访问 RTC_SLOW_MEM 内存区域及 RTC_CNTL、RTC_IO、SARADC 等外设寄存器。ULP 协处理器使用 32 位固定宽度的指令，32 位内存寻址，配备 4 个 16 位通用寄存器。 + +安装工具链 +------------------------ + +ULP 协处理器代码是用汇编语言编写的，并使用 `binutils-esp32ulp 工具链`_ 进行编译。 + +1. 从提供的网址中下载最新工具链的预编译二进制文件：https://github.com/espressif/binutils-esp32ulp/releases. + +2. 将工具链解压缩到一个目录中，并将工具链的 ``bin/`` 目录路径添加到 ``PATH`` 环境变量中。 + +编译 ULP 代码 +------------------ + +若需要将 ULP 代码编译为某组件的一部分，则必须执行以下步骤： + +1. 用汇编语言编写的 ULP 代码必须导入到一个或多个 .S 扩展文件中，且这些文件必须放在组件目录中一个独立的目录中，例如 `ulp/`。 + +.. note: + 该目录不要添加到 ``COMPONENT_SRCDIRS`` 环境变量中。因为 ESP-IDF 构建系统将基于文件扩展名编译在 ``COMPONENT_SRCDIRS`` 中搜索到的文件。对于 ``.S`` 文件，使用的是 ``xtensa-esp32-elf-as`` 汇编器。但这并不适用于 ULP 程序集文件，因此体现这种区别的最简单方法就是将 ULP 程序集文件放到单独的目录中。同样，ULP 程序集源文件也不应该添加到 ``COMPONENT_SRCS`` 中。请参考如下步骤，查看如何正确添加 ULP 程序集源文件。 + +2. 修改组件 CMakeLists.txt，添加必要的 ULP CMake 定义，示例如下:: + + set(ULP_APP_NAME ulp_${COMPONENT_NAME}) + set(ULP_S_SOURCES ulp/ulp_assembly_source_file.S) + set(ULP_EXP_DEP_SRCS "ulp_c_source_file.c") + include(${IDF_PATH}/components/ulp/component_ulp_common.cmake) + +代码解释如下： + +``set(ULP_APP_NAME ulp_${COMPONENT_NAME})`` + 为生成的 ULP 应用程序设置名称，不带扩展名。此名称用于 ULP 应用程序的构建输出：ELF 文件、.map 文件、二进制文件、生成的头文件和链接器导出文件。 + +``set(ULP_S_SOURCES "ulp/ulp_assembly_source_file_1.S ulp/ulp_assembly_source_file_2.S")`` + 设置要传递给 ULP 汇编器的程序集文件列表，用空格隔开，路径可以是绝对路径，也可以是组件 CMakeLists.txt 的相对路径。 + +``set(ULP_EXP_DEP_SRCS "ulp_c_source_file_1.c ulp_c_source_file_2.c")`` + 设置组件中源文件名称的列表。所有包含被生成的头文件的原文件都必须在列表里。此列表建立正确构建依赖项，并确保在构建过程会先生成才编译包含头文件的原文件。请参考下文，查看为 ULP 应用程序生成的头文件等相关概念。此列表需要用空格隔开，路径可以是组件 CMakeLists.txt 文件的相对路径，也可以是绝对路径。 + +``include(${IDF_PATH}/components/ulp/component_ulp_common.cmake)`` + 包含 ULP 编译步骤的通用定义。使用 ULP 工具链为 ULP 目标文件、ELF 文件、二进制文件等设置编译规则。 + +3. 使用常规方法（例如 `idf.py app`）编译应用程序 + + 在内部，编译系统将按照以下步骤编译 ULP 程序： + + 1. **通过 C 预处理器运行每个程序集文件 (foo.S)。** 此步骤在组件编译目录中生成预处理的程序集文件 (foo.ulp.S)，同时生成依赖文件 (foo.ulp.d)。 + + 2. **通过汇编器运行预处理过的汇编源码。** 此步骤会生成目标文件 (foo.ulp.o) 和清单 (foo.ulp.lst)。清单文件仅用于调试，不用于编译进程的后续步骤。 + + 3. **通过 C 预处理器运行链接器脚本模板。** 模板位于 components/ulp/ld 目录中。 + + 4. **将目标文件链接到 ELF 输出文件** (ulp_app_name.elf)。此步骤生成的.map 文件 (ulp_app_name.map) 默认用于调试。 + + 5. **将 ELF 文件中的内容转储为二进制文件** (ulp_app_name.bin)，以便嵌入到应用程序中。 + + 6. **使用 esp32ulp-elf-nm 在 ELF 文件中生成全局符号列表** (ulp_app_name.sym)。 + + 7. **创建 LD 导出脚本和头文件** (ulp_app_name.ld 和 ulp_app_name.h)，包含来自 ulp_app_name.sym 的符号。此步骤可借助 esp32ulp_mapgen.py 工具来完成。 + + 8. **将生成的二进制文件添加到要嵌入应用程序的二进制文件列表中。** + +访问 ULP 程序变量 +------------------------------- + +在 ULP 程序中定义的全局符号也可以在主程序中使用。 + +例如，ULP 程序可以定义 ``measurement_count`` 变量，此变量可以定义程序从深度睡眠中唤醒芯片之前需要进行的 ADC 测量的次数:: + + .global measurement_count + measurement_count: .long 0 + + /* later, use measurement_count */ + move r3, measurement_count + ld r3, r3, 0 + +主程序需要在启动 ULP 程序之前初始化 ``measurement_count`` 变量，编译系统生成 ``${ULP_APP_NAME}.h`` 和 ``${ULP_APP_NAME}.ld`` 文件可以实现上述操作，这些文件在 ULP 编程中定义了全局符号，包含了在 ULP 程序中定义的所有全局符号，前缀为 ``ulp_``。 + +头文件包含对此类符号的声明:: + + extern uint32_t ulp_measurement_count; + +注意，所有符号（包括变量、数组、函数）均被声明为 ``uint32_t``。对于函数和数组，先获取符号地址，然后转换为适当的类型。 + +生成的链接器脚本文件定义了 RTC_SLOW_MEM 中的符号位置:: + + PROVIDE ( ulp_measurement_count = 0x50000060 ); + +如果要从主程序访问 ULP 程序变量，先包含生成的头文件，并使用上述变量，操作如下:: + + #include "ulp_app_name.h" + + // later + void init_ulp_vars() { + ulp_measurement_count = 64; + } + +注意，ULP 程序在 RTC 内存中只能使用 32 位字的低 16 位，因为寄存器是 16 位的，并且不具备从字的高位加载的指令。 + +同样，ULP 储存指令将寄存器值写入 32 位字的低 16 位中。高 16 位写入的值取决于储存指令的地址，因此在读取 ULP 写的变量时，主应用程序需要屏蔽高 16 位，例如:: + + printf("Last measurement value: %d\n", ulp_last_measurement & UINT16_MAX); + +启动 ULP 程序 +------------------------ + +要运行 ULP 程序，主应用程序需要调用 ``ulp_load_binary`` 函数将 ULP 程序加载到 RTC 内存中，然后调用 ``ulp_run`` 函数，启动 ULP 程序。 + +注意，在 menuconfig 中必须启用 "Enable Ultra Low Power (ULP) Coprocessor" 选项，以便为 ULP 预留内存。"RTC slow memory reserved for coprocessor" 选项设置的值必须足够储存 ULP 代码和数据。如果应用程序组件包含多个 ULP 程序，则 RTC 内存必须足以容纳最大的程序。 + +每个 ULP 程序均以二进制 BLOB 的形式嵌入到 ESP-IDF 应用程序中。应用程序可以引用此 BLOB，并以下面的方式加载此 BLOB （假设 ULP_APP_NAME 已被定义为 ``ulp_app_name``）:: + + extern const uint8_t bin_start[] asm("_binary_ulp_app_name_bin_start"); + extern const uint8_t bin_end[] asm("_binary_ulp_app_name_bin_end"); + + void start_ulp_program() { + ESP_ERROR_CHECK( ulp_load_binary( + 0 /* load address, set to 0 when using default linker scripts */, + bin_start, + (bin_end - bin_start) / sizeof(uint32_t)) ); + } + +.. doxygenfunction:: ulp_load_binary + +一旦上述程序加载到 RTC 内存后，应用程序即可启动此程序，并将入口点的地址传递给 ``ulp_run`` 函数:: + + ESP_ERROR_CHECK( ulp_run(&ulp_entry - RTC_SLOW_MEM) ); + +.. doxygenfunction:: ulp_run + +上述生成的头文件 ``${ULP_APP_NAME}.h`` 声明了入口点符号。在 ULP 应用程序的汇编源代码中，此符号必须标记为 ``.global``:: + + + .global entry + entry: + /* code starts here */ + + +ULP 程序流 +---------------- + +ULP 协处理器由定时器启动，而调用 ``ulp_run`` 则可启动此定时器。定时器为 RTC_SLOW_CLK 的 Tick 事件计数（默认情况下，Tick 由内部 150 KHz 晶振器生成）。使用 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器 (x = 0..4) 设置 Tick 数值。第一次启动 ULP 时，使用 ``SENS_ULP_CP_SLEEP_CYC0_REG`` 设置定时器 Tick 数值，之后，ULP 程序可以使用 ``sleep`` 指令来另外选择 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器。 + +此应用程序可以调用 ``ulp_set_wakeup_period`` 函数来设置 ULP 定时器周期值 (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4)。 + +.. doxygenfunction:: ulp_set_wakeup_period + +一旦定时器达到在所选的 ``SENS_ULP_CP_SLEEP_CYCx_REG`` 寄存器中设置的数值，ULP 协处理器就会启动，并调用 ``ulp_run`` 的入口点开始运行程序。 + +程序保持运行，直到遇到 ``halt`` 指令或非法指令。一旦程序停止，ULP 协处理器电源关闭，定时器再次启动。 + +如果想禁用定时器（有效防止 ULP 程序再次运行），请清除 ``RTC_CNTL_STATE0_REG`` 寄存器中的 ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` 位，可在 ULP 代码或主程序中进行以上操作。 + + +.. _binutils-esp32ulp 工具链: https://github.com/espressif/binutils-esp32ulp diff --git a/docs/zh_CN/api-guides/unit-tests-cmake.rst b/docs/zh_CN/api-guides/unit-tests-legacy.rst similarity index 82% rename from docs/zh_CN/api-guides/unit-tests-cmake.rst rename to docs/zh_CN/api-guides/unit-tests-legacy.rst index 1f3453f99..82aba2258 100644 --- a/docs/zh_CN/api-guides/unit-tests-cmake.rst +++ b/docs/zh_CN/api-guides/unit-tests-legacy.rst @@ -1,7 +1,9 @@ -ESP32 中的单元测试 (CMake) -========================== +ESP32 中的单元测试 +================== :link_to_translation:`en:[English]` +.. include:: ../gnu-make-legacy.rst + ESP-IDF 中附带了一个基于 ``Unity`` 的单元测试应用程序框架，且所有的单元测试用例分别保存在 ESP-IDF 仓库中每个组件的 ``test`` 子目录中。 @@ -32,19 +34,12 @@ C 文件可以包含多个测试用例。测试文件的名字要以 “test” 来声明主函数的区域， ``unity_platform.c`` 会自动调用 ``UNITY_BEGIN()``\ ， 然后运行测试用例，最后调用 ``UNITY_END()``\ 。 -``test`` 子目录需要包含 ：ref：`组件 CMakeLists.txt `，因为他们本身就是一种组件。ESP-IDF 使用了 -``unity`` 测试框架，需要将其指定为组件的依赖项。通常，组件 -：ref：`需要手动指定待编译的源文件 `;但是，对于测试组件来说，这个要求被放宽了，仅仅是建议使用 “COMPONENT_SRCDIRS”。 +每一个测试子目录下都应该包含一个 +``component.mk``\ ，并且里面至少要包含如下的一行内容： -总的来说，``test`` 子目录下最简单的 CMakeLists.txt 文件可能如下所示: +.. code:: makefile -.. code:: cmake - - set(COMPONENT_SRCDIRS ".") - set(COMPONENT_ADD_INCLUDEDIRS ".") - set(COMPONENT_REQUIRES unity) - - register_component() + COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive 更多关于如何在 Unity 下编写测试用例的信息，请查阅 http://www.throwtheswitch.org/unity 。 @@ -117,6 +112,21 @@ DUT2（slave）终端： 一旦 DUT2 发送了该信号，您需要在 DUT2 的终端输入回车，然后 DUT1 会从 ``unity_wait_for_signal`` 函数中解除阻塞，并开始更改 GPIO 的电平。 +信号也可以用来在不同 DUT 之间传递参数。例如，DUT1 希望能够拿到 DUT2 的 MAC 地址，来进行蓝牙连接。 +这时，我们可以使用 ``unity_wait_for_signal_param`` 以及 ``unity_send_signal_param``。 + +DUT1 终端:: + + Waiting for signal: [dut2 mac address]! + Please input parameter value from any board send this signal and press "Enter" key. + + +DUT2 终端:: + + Send signal: [dut2 mac address][10:20:30:40:50:60]! + +一旦 DUT2 发送信号，您需要在 DUT1 输入 ``10:20:30:40:50:60`` 及回车，然后 DUT1 会从 ``unity_wait_for_signal_param`` 中获取到蓝牙地址的字符串，并解除阻塞开始蓝牙连接。 + 添加多阶段测试用例 ------------------ @@ -150,23 +160,23 @@ DUT2（slave）终端： 切换到 ``tools/unit-test-app`` 目录下进行配置和编译： -- ``idf.py menuconfig`` - 配置单元测试程序。 +- ``make menuconfig`` - 配置单元测试程序。 -- ``idf.py -T all build`` - 编译单元测试程序，测试每个组件 ``test`` +- ``make TESTS_ALL=1`` - 编译单元测试程序，测试每个组件 ``test`` 子目录下的用例。 -- ``idf.py -T xxx build`` - 编译单元测试程序，测试指定的组件。 +- ``make TEST_COMPONENTS='xxx'`` - 编译单元测试程序，测试指定的组件。 -- ``idf.py -T all -E xxx build`` - +- ``make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'`` - 编译单元测试程序，测试所有（除开指定）的组件。例如 - ``idf.py -T all -E ulp mbedtls build`` - + ``make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'`` - 编译所有的单元测试，不包括 ``ulp`` 和 ``mbedtls``\ 组件。 -当编译完成时，它会打印出烧写芯片的指令。您只需要运行 ``idf.py flash`` +当编译完成时，它会打印出烧写芯片的指令。您只需要运行 ``make flash`` 即可烧写所有编译输出的文件。 -您还可以运行 ``idf.py -T all flash`` 或者 -``idf.py -T xxx flash`` +您还可以运行 ``make flash TESTS_ALL=1`` 或者 +``make TEST_COMPONENTS='xxx'`` 来编译并烧写，所有需要的文件都会在烧写之前自动重新编译。 使用 ``menuconfig`` 可以设置烧写测试程序所使用的串口。 @@ -211,13 +221,13 @@ DUT2（slave）终端： 可以输入以下任意一项来运行测试用例： -- 引号中的测试用例的名字，运行单个测试用例。 +- 引号中的测试用例的名字（例如 ``"esp_ota_begin() verifies arguments"``），运行单个测试用例。 -- 测试用例的序号，运行单个测试用例。 +- 测试用例的序号（例如 ``1``），运行单个测试用例。 -- 方括号中的模块名字，运行指定模块所有的测试用例。 +- 方括号中的模块名字（例如 ``[cxx]``），运行指定模块所有的测试用例。 -- 星号，运行所有测试用例。 +- 星号 (``*``)，运行所有测试用例。 ``[multi_device]`` 和 ``[multi_stage]`` 标签告诉测试运行者该用例是多设备测试还是多阶段测试。这些标签由 diff --git a/docs/zh_CN/api-guides/unit-tests.rst b/docs/zh_CN/api-guides/unit-tests.rst index de8e52d3e..960238e72 100644 --- a/docs/zh_CN/api-guides/unit-tests.rst +++ b/docs/zh_CN/api-guides/unit-tests.rst @@ -1,5 +1,5 @@ ESP32 中的单元测试 -================== +========================== :link_to_translation:`en:[English]` ESP-IDF @@ -32,12 +32,19 @@ C 文件可以包含多个测试用例。测试文件的名字要以 “test” 来声明主函数的区域， ``unity_platform.c`` 会自动调用 ``UNITY_BEGIN()``\ ， 然后运行测试用例，最后调用 ``UNITY_END()``\ 。 -每一个测试子目录下都应该包含一个 -``component.mk``\ ，并且里面至少要包含如下的一行内容： +``test`` 子目录需要包含 ：ref：`组件 CMakeLists.txt `，因为他们本身就是一种组件。ESP-IDF 使用了 +``unity`` 测试框架，需要将其指定为组件的依赖项。通常，组件 +：ref：`需要手动指定待编译的源文件 `;但是，对于测试组件来说，这个要求被放宽了，仅仅是建议使用 “COMPONENT_SRCDIRS”。 -.. code:: makefile +总的来说，``test`` 子目录下最简单的 CMakeLists.txt 文件可能如下所示: - COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive +.. code:: cmake + + set(COMPONENT_SRCDIRS ".") + set(COMPONENT_ADD_INCLUDEDIRS ".") + set(COMPONENT_REQUIRES unity) + + register_component() 更多关于如何在 Unity 下编写测试用例的信息，请查阅 http://www.throwtheswitch.org/unity 。 @@ -110,21 +117,6 @@ DUT2（slave）终端： 一旦 DUT2 发送了该信号，您需要在 DUT2 的终端输入回车，然后 DUT1 会从 ``unity_wait_for_signal`` 函数中解除阻塞，并开始更改 GPIO 的电平。 -信号也可以用来在不同 DUT 之间传递参数。例如，DUT1 希望能够拿到 DUT2 的 MAC 地址，来进行蓝牙连接。 -这时，我们可以使用 ``unity_wait_for_signal_param`` 以及 ``unity_send_signal_param``。 - -DUT1 终端:: - - Waiting for signal: [dut2 mac address]! - Please input parameter value from any board send this signal and press "Enter" key. - - -DUT2 终端:: - - Send signal: [dut2 mac address][10:20:30:40:50:60]! - -一旦 DUT2 发送信号，您需要在 DUT1 输入 ``10:20:30:40:50:60`` 及回车，然后 DUT1 会从 ``unity_wait_for_signal_param`` 中获取到蓝牙地址的字符串，并解除阻塞开始蓝牙连接。 - 添加多阶段测试用例 ------------------ @@ -158,23 +150,23 @@ DUT2 终端:: 切换到 ``tools/unit-test-app`` 目录下进行配置和编译： -- ``make menuconfig`` - 配置单元测试程序。 +- ``idf.py menuconfig`` - 配置单元测试程序。 -- ``make TESTS_ALL=1`` - 编译单元测试程序，测试每个组件 ``test`` +- ``idf.py -T all build`` - 编译单元测试程序，测试每个组件 ``test`` 子目录下的用例。 -- ``make TEST_COMPONENTS='xxx'`` - 编译单元测试程序，测试指定的组件。 +- ``idf.py -T xxx build`` - 编译单元测试程序，测试指定的组件。 -- ``make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'`` - +- ``idf.py -T all -E xxx build`` - 编译单元测试程序，测试所有（除开指定）的组件。例如 - ``make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'`` - + ``idf.py -T all -E ulp mbedtls build`` - 编译所有的单元测试，不包括 ``ulp`` 和 ``mbedtls``\ 组件。 -当编译完成时，它会打印出烧写芯片的指令。您只需要运行 ``make flash`` +当编译完成时，它会打印出烧写芯片的指令。您只需要运行 ``idf.py flash`` 即可烧写所有编译输出的文件。 -您还可以运行 ``make flash TESTS_ALL=1`` 或者 -``make TEST_COMPONENTS='xxx'`` +您还可以运行 ``idf.py -T all flash`` 或者 +``idf.py -T xxx flash`` 来编译并烧写，所有需要的文件都会在烧写之前自动重新编译。 使用 ``menuconfig`` 可以设置烧写测试程序所使用的串口。 @@ -219,13 +211,13 @@ DUT2 终端:: 可以输入以下任意一项来运行测试用例： -- 引号中的测试用例的名字（例如 ``"esp_ota_begin() verifies arguments"``），运行单个测试用例。 +- 引号中的测试用例的名字，运行单个测试用例。 -- 测试用例的序号（例如 ``1``），运行单个测试用例。 +- 测试用例的序号，运行单个测试用例。 -- 方括号中的模块名字（例如 ``[cxx]``），运行指定模块所有的测试用例。 +- 方括号中的模块名字，运行指定模块所有的测试用例。 -- 星号 (``*``)，运行所有测试用例。 +- 星号，运行所有测试用例。 ``[multi_device]`` 和 ``[multi_stage]`` 标签告诉测试运行者该用例是多设备测试还是多阶段测试。这些标签由 diff --git a/docs/zh_CN/cmake-pending-features.rst b/docs/zh_CN/cmake-pending-features.rst deleted file mode 100644 index 5c11a1573..000000000 --- a/docs/zh_CN/cmake-pending-features.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. important:: - 目前，CMake 编译系统尚不支持以下功能： - - - Eclipse IDE 文档 - - 安全启动 - - Flash 加密 - - 未来，CMake 编译系统将在 ESP-IDF v4.0 发布后取代现有基于 GNU Make 的编译系统，成为默认编译系统。我们会在 ESP-IDF v4.0 发布前逐步完善上述功能。 - - diff --git a/docs/zh_CN/cmake-warning.rst b/docs/zh_CN/cmake-warning.rst deleted file mode 100644 index 8815c8ae9..000000000 --- a/docs/zh_CN/cmake-warning.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. note:: - 本文档将介绍如何使用 CMake 编译系统。目前，CMake 编译系统仍处于预览发布阶段，如您在使用中遇到任何问题，请前往 ESP-IDF 提交 `Issues `_。 - - 未来，CMake 编译系统将在 ESP-IDF v4.0 发布后过渡为默认编译系统，现行基于 GNU Make 的编译系统将在 ESP-IDF v5.0 后弃用。 diff --git a/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst b/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst deleted file mode 100644 index ad19c5465..000000000 --- a/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst +++ /dev/null @@ -1,75 +0,0 @@ -在用户配置文件中添加 IDF_PATH 和 idf.py PATH (CMake) -========================================================================================================== - -:link_to_translation:`en:[英文]` - -.. include:: ../cmake-warning.rst - -使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量： - -- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径 -- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录 - -为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。 - -.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。 - -.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。 - -.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。 - -.. _add-paths-to-profile-windows-cmake: - -Windows 操作系统 ------------------------------------ - -在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。 - -在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。 - -你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。 - -- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。 -- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。 - -如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。 - - -.. _add-idf_path-to-profile-linux-macos-cmake: - -Linux 和 MacOS 操作系统 ------------------------------------- - -要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中:: - - export IDF_PATH=~/esp/esp-idf - export PATH="$IDF_PATH/tools:$PATH" - -.. note:: - - ``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。 - -请退出，并重新登录使更改生效。 - -.. note:: - - 并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。 - -运行以下命令来检查 ``IDF_PATH`` 设置是否正确:: - - printenv IDF_PATH - -此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。 - -为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令:: - - which idf.py - -这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。 - -如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入:: - - export IDF_PATH=~/esp/esp-idf - export PATH="$IDF_PATH/tools:$PATH" - -如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path-cmake` 小节跳到了这里，请返回 :ref:`get-started-start-project-cmake` 小节开始阅读。 diff --git a/docs/zh_CN/get-started-cmake/eclipse-setup.rst b/docs/zh_CN/get-started-cmake/eclipse-setup.rst deleted file mode 100644 index d0c4fb4d6..000000000 --- a/docs/zh_CN/get-started-cmake/eclipse-setup.rst +++ /dev/null @@ -1,11 +0,0 @@ -**************************************** -Eclipse IDE 创建和烧录指南 (CMake) -**************************************** - -:link_to_translation:`en:[English]` - -.. include:: ../cmake-warning.rst - -有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。 - -.. _eclipse.org: https://www.eclipse.org/ diff --git a/docs/zh_CN/get-started-cmake/establish-serial-connection.rst b/docs/zh_CN/get-started-cmake/establish-serial-connection.rst deleted file mode 100644 index 278dfb6af..000000000 --- a/docs/zh_CN/get-started-cmake/establish-serial-connection.rst +++ /dev/null @@ -1,155 +0,0 @@ -与 ESP32 创建串口连接 (CMake) -============================================== - -:link_to_translation:`en:[English]` - -本章节主要介绍如何创建 ESP32 和 PC 之间的串口连接。 - - -连接 ESP32 和 PC --------------------- - -用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。 - -以下是乐鑫 ESP32 开发板驱动程序的链接： - -.. csv-table:: - :header: 开发板, USB 驱动, 备注 - :widths: 40, 20, 40 - - :ref:`ESP32-DevKitC `, `CP210x`_ - `ESP32-LyraT `_, `CP210x`_ - `ESP32-LyraTD-MSC `_, `CP210x`_ - :ref:`ESP32-PICO-KIT `, `CP210x`_ - :ref:`ESP-WROVER-KIT `, `FTDI`_ - :ref:`ESP32 Demo 板 `, `FTDI`_ - `ESP-Prog`_, `FTDI`_, 编程板 (w/o ESP32) - `ESP32-MeshKit-Sense `_, n/a, 搭配 `ESP-Prog`_ 使用 - `ESP32-Sense Kit `_, n/a, 搭配 `ESP-Prog`_ 使用 - -.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers -.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm -.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board - -* CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 `_ -* FTDI: `FTDI 虚拟 COM 端口驱动程序 `_ - -以上驱动仅用于参考。一般情况下，当上述任一 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。 - -在 Windows 上查看端口 ---------------------- - -检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。 - -以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口： - -.. figure:: ../../_static/esp32-devkitc-in-device-manager.png - :align: center - :alt: 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 - :figclass: align-center - - 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 - -.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png - :align: center - :alt: Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口 - :figclass: align-center - - Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口 - - -在 Linux 和 MacOS 上查看端口 ------------------------------ - -查看 ESP32 开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 ESP32 对应的串口： - -Linux :: - - ls /dev/tty* - -MacOS :: - - ls /dev/cu.* - -.. note:: - - 对于 MacOS 用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。 - -.. _linux-dialout-group-cmake: - -在 Linux 中添加用户到 ``dialout`` ------------------------------------ - -当前登录用户应当可以通过 USB 对串口进行读写操作。在多数 Linux 版本中，你都可以通过以下命令，将用户添加到 ``dialout`` 组，来获许读写权限:: - - sudo usermod -a -G dialout $USER - -在 Arch Linux 中，需要通过以下命令将用户添加到 ``uucp`` 组中:: - - sudo usermod -a -G uucp $USER - -请重新登录，确保串口读写权限可以生效。 - - -确认串口连接 ------------------------- - -现在，请使用串口终端程序，验证串口连接是否可用。在本示例中，我们将使用 `PuTTY SSH Client `_， `PuTTY SSH Client `_ 既可用于 Windows 也可用于 Linux。你也可以使用其他串口程序并设置如下的通信参数。 - -运行终端，配置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下截屏分别展示了在 Windows 和 Linux 中配置串口和上述通信参数（如 115200-8-1-N）。注意，这里一定要选择在上述步骤中确认的串口进行配置。 - -.. figure:: ../../_static/putty-settings-windows.png - :align: center - :alt: 在 Windows 操作系统中使用 PuTTY 设置串口通信参数 - :figclass: align-center - - 在 Windows 操作系统中使用 PuTTY 设置串口通信参数 - -.. figure:: ../../_static/putty-settings-linux.png - :align: center - :alt: 在 Linux 操作系统中使用 PuTTY 设置串口通信参数 - :figclass: align-center - - 在 Linux 操作系统中使用 PuTTY 设置串口通信参数 - - -然后，请检查 ESP32 是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 ESP32 的应用程序，下图即为一个示例。 - -.. highlight:: none - -:: - - ets Jun 8 2016 00:22:57 - - rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) - ets Jun 8 2016 00:22:57 - - rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) - configsip: 0, SPIWP:0x00 - clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 - mode:DIO, clock div:2 - load:0x3fff0008,len:8 - load:0x3fff0010,len:3464 - load:0x40078000,len:7828 - load:0x40080000,len:252 - entry 0x40080034 - I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader - I (45) boot: compile time 18:48:10 - - ... - -如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 ESP32。 - -.. note:: - - 在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。 - -.. note:: - - 请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。 - -如你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-connect-cmake` 跳转到了这里，请从 :ref:`get-started-configure-cmake` 继续阅读。 - - -.. _esptool 文档: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader - diff --git a/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst b/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst deleted file mode 100644 index 967887f74..000000000 --- a/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst +++ /dev/null @@ -1,79 +0,0 @@ -****************************************** -从零开始设置 Linux 环境下的工具链 (CMake) -****************************************** - -:link_to_translation:`en:[English]` - -.. include:: ../cmake-warning.rst - -除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。 - -安装准备 -===================== - -编译 ESP-IDF 需要以下软件包： - -- CentOS 7:: - - sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - -- Ubuntu 和 Debian:: - - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache - - -.. note:: - 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 - -从源代码编译工具链 -================================= - -- 安装依赖： - - - CentOS 7:: - - sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make - - - Ubuntu pre-16.04:: - - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make - - - Ubuntu 16.04 及以上:: - - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - - Debian 9:: - - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - - Arch:: - - TODO - -创建工作目录，并进入该目录:: - - mkdir -p ~/esp - cd ~/esp - -下载并编译 ``crosstool-NG`` ： - -.. include:: /_build/inc/scratch-build-code.inc - -编译工具链:: - - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf - -编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 - - -后续步骤 -========== - -继续设置开发环境，请前往 :ref:`get-started-get-esp-idf-cmake` 章节。 - diff --git a/docs/zh_CN/get-started-cmake/linux-setup.rst b/docs/zh_CN/get-started-cmake/linux-setup.rst deleted file mode 100644 index 82afb790b..000000000 --- a/docs/zh_CN/get-started-cmake/linux-setup.rst +++ /dev/null @@ -1,119 +0,0 @@ -******************************************************************* -Linux 平台工具链的标准设置 (CMake) -******************************************************************* - -:link_to_translation:`en:[英文]` - -.. include:: ../cmake-warning.rst - -安装前提 -===================== - -编译 ESP-IDF 需要以下软件包： - -- CentOS 7:: - - sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - -- Ubuntu 和 Debian:: - - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache - -.. note:: - 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 - -工具链的设置 -========================= - -.. include:: /_build/inc/download-links.inc - -Linux 版的 ESP32 工具链可以从 Espressif 的网站下载： - -- 64 位 Linux： - - |download_link_linux64| - -- 32 位 Linux： - - |download_link_linux32| - -1. 下载完成后，将它解压到 ``~/esp`` 目录： - - - 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. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。 - - 要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：:: - - export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" - - 或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可:: - - alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' - - 然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。 - - .. note:: - - 如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。 - -3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确:: - - printenv PATH - - 检查字符串的开头是否包含类似的工具链路径:: - - $ 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 - - 除了 ``/home/user-name``，应该有具体的安装的主路径。 - - -权限问题 /dev/ttyUSB0 ----------------------------------------------- - -使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 ` - -Arch Linux 用户 --------------------------------- - -在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。 - -`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置： - -- https://aur.archlinux.org/packages/ncurses5-compat-libs/ -- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ - -在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。 - -或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。 - - -后续步骤 -================ - -后续开发环境设置，请参考 :ref:`get-started-get-esp-idf-cmake` 一节。 - - -相关文档 -================= - -.. toctree:: - :maxdepth: 1 - - linux-setup-scratch - - -.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst b/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst deleted file mode 100644 index 0080d8180..000000000 --- a/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst +++ /dev/null @@ -1,88 +0,0 @@ -********************************************************************* -从零开始设置 Mac OS 环境下的工具链 (CMake) -********************************************************************* - -:link_to_translation:`en:[英文]` - -.. include:: ../cmake-warning.rst - -软件包管理器 -====================== - -从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 `。 - -MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。 - - .. _homebrew: https://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php - -请参考 :ref:`工具链自定义设置 ` 章节，查看在哪些情景下需要从头开始设置工具链。 - -准备工作 -============================ - -- 安装 pip:: - - sudo easy_install pip - -- 安装 pyserial:: - - pip install --user pyserial - -- 安装 CMake 和 Ninja 编译工具： - - - 若使用 HomeBrew，你可以运行:: - - brew install cmake ninja - - - 若使用 MacPorts，你可以运行:: - - sudo port install cmake ninja - -从源代码编译工具链 -======================================== - -- 相关安装： - - - 对于 MacPorts:: - - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - - - 对于 homebrew:: - - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make - -创建一个文件系统镜像（区分大小写）:: - - hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" - -挂载:: - - hdiutil mount ~/esp/crosstool.dmg - -创建指向你工作目录的符号链接:: - - mkdir -p ~/esp - ln -s /Volumes/ctng ~/esp/ctng-volume - -前往新创建的目录：:: - - cd ~/esp/ctng-volume - -下载 ``crosstool-NG``，并开始编译： - -.. include:: /_build/inc/scratch-build-code.inc - -编译工具链：:: - - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf - -编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 - - -后续步骤 -================= - -继续设置开发环境，请前往 :ref:`获取 ESP-IDF ` 章节。 diff --git a/docs/zh_CN/get-started-cmake/macos-setup.rst b/docs/zh_CN/get-started-cmake/macos-setup.rst deleted file mode 100644 index adb0b1241..000000000 --- a/docs/zh_CN/get-started-cmake/macos-setup.rst +++ /dev/null @@ -1,95 +0,0 @@ -****************************************************************** -在 Mac OS 上安装 ESP32 工具链 (CMake) -****************************************************************** - -:link_to_translation:`en:[英文]` - -.. include:: ../cmake-warning.rst - -安装准备 -===================== - -ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 - -- 安装 pip:: - - sudo easy_install pip - -- 安装 pyserial:: - - pip install --user pyserial - -- 安装 CMake 和 Ninja 编译工具： - - - 若有 HomeBrew_，你可以运行:: - - brew install cmake ninja - - - 若有 MacPorts_，你可以运行:: - - sudo port install cmake ninja - - - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 - -- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。 - -.. note:: - - 如在任一步骤中出现以下报错信息:: - - ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun`` - - 你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。 - -安装工具链 -====================== - -.. include:: /_build/inc/download-links.inc - -下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网： - -|download_link_osx| - -完成下载后，请在 ``~/esp`` 目录下进行解压： - -.. include:: /_build/inc/unpack-code-osx.inc - -.. _setup-macos-toolchain-add-it-to-path-cmake: - -此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。 - -为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：:: - - export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH - -此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令:: - - alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" - -此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。 - -注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。 - -此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确:: - - printenv PATH - - -后续步骤 -================= - -前往 :ref:`get-started-get-esp-idf-cmake`，完成接下来的开发环境配置。 - -相关文档 -================= - -.. toctree:: - :maxdepth: 1 - - macos-setup-scratch - -.. _cmake: https://cmake.org/ -.. _ninja: https://ninja-build.org/ -.. _ccache: https://ccache.samba.org/ -.. _homebrew: https://brew.sh/ -.. _MacPorts: https://www.macports.org/install.php \ No newline at end of file diff --git a/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst b/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst deleted file mode 100644 index fc08a6f03..000000000 --- a/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _get-started-customized-setup-cmake: - -********************************************************* -工具链自定义设置 (CMake) -********************************************************* - -:link_to_translation:`en:[英文]` - -除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain-cmake`）下载二进制工具链外，你还可以自行编译工具链。 - -如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链： - -- 需要定制工具链编译配置 -- 使用其他 GCC 版本（如 4.8.5） -- 需要破解 gcc、newlib 或 libstdc++ -- 有相关兴趣或时间充裕 -- 不信任从网站下载的 bin 文件 - -如需自行编译工具链，请查看以下文档： - -.. toctree:: - :maxdepth: 1 - - windows-setup-scratch - linux-setup-scratch - macos-setup-scratch - diff --git a/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst b/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst deleted file mode 100644 index 325de61ef..000000000 --- a/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst +++ /dev/null @@ -1,94 +0,0 @@ -****************************************************************** -从零开始设置 Windows 环境下的工具链 (CMake) -****************************************************************** - -:link_to_translation:`en:[英文]` - -.. include:: ../cmake-warning.rst - -本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 ` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。 - -使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。 - - -.. note:: - 基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。 - -工具 -===== - -cmake -^^^^^ - -下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。 - -当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。 - -Ninja 编译工具 -^^^^^^^^^^^^^^^^^^^^ - -.. note:: - Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。 - -从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 `ninja`_。 - -适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 `_ （或者选择你的路径中已有的目录）。 - - -Python 2.x -^^^^^^^^^^ - -下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。 - -Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。 - -Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令:: - - pip install --user pyserial - -适用于 IDF 的 MConf -^^^^^^^^^^^^^^^^^^^^^^ - -从 `kconfig-frontends 发布页面 `_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。 - -你需将此工具解压到目录，然后 `添加到你的路径 `_。 - -工具链设置 -=============== - -.. include:: /_build/inc/download-links.inc - -下载预编译的 Windows 平台工具链： - -|download_link_win32| - -解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。 - -然后，须将该目录下的子目录 ``bin`` `添加到你的路径 `_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。 - -.. note:: - - 如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。 - - -.. _add-directory-windows-path-cmake: - -添加目录到路径 -======================== - -添加任何新目录到你的 Windows Path 环境变量： - -打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。 - -双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;``。 - - -后续步骤 -================ - -要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf-cmake`。 - -.. _ninja: https://ninja-build.org/ -.. _Python: https://www.python.org/downloads/windows/ -.. _MSYS2: https://msys2.github.io/ - diff --git a/docs/zh_CN/get-started-cmake/windows-setup-update.rst b/docs/zh_CN/get-started-cmake/windows-setup-update.rst deleted file mode 100644 index cdaf9a5b8..000000000 --- a/docs/zh_CN/get-started-cmake/windows-setup-update.rst +++ /dev/null @@ -1,3 +0,0 @@ -:orphan: - -.. Remove this file when the Chinese translation of CMake getting started guide is updated diff --git a/docs/zh_CN/get-started-cmake/windows-setup.rst b/docs/zh_CN/get-started-cmake/windows-setup.rst deleted file mode 100644 index e8d129033..000000000 --- a/docs/zh_CN/get-started-cmake/windows-setup.rst +++ /dev/null @@ -1,73 +0,0 @@ -********************************************************** -Windows 平台工具链的标准设置 (CMake) -********************************************************** - -:link_to_translation:`en:[英文]` - -.. include:: ../cmake-warning.rst - -.. note:: - 基于 CMake 的构建系统仅支持 64 位版本 Windows。 - -引言 -============ - -ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。 - -在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse ` 或支持 CMake 的图形化工具 IDE。 - -.. note:: - 基于 GNU Make 的构建系统要求 Windows 系统兼容 MSYS2_ Unix。基于 CMake 的构建系统则无此要求。 - -ESP-IDF 工具安装器 -======================= - -安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下： - -https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe - -安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。 - -安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。 - -请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。 - -安装 Git -============== - -ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。 - -如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。 - -使用终端 -================ - -在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符： - -- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。 -- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。 -- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。 - -后续步骤 -========== - -要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf-cmake`。 - -相关文档 -================= - -想要自定义安装流程的高阶用户可参照： - -.. toctree:: - :maxdepth: 1 - - windows-setup-scratch - - -.. _MSYS2: https://msys2.github.io/ -.. _cmake: https://cmake.org/download/ -.. _ninja: https://ninja-build.org/ -.. _Python: https://www.python.org/downloads/windows/ -.. _Git for Windows: https://gitforwindows.org/ -.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/ -.. _Github Desktop: https://desktop.github.com/ diff --git a/docs/zh_CN/get-started-legacy/add-idf_path-to-profile.rst b/docs/zh_CN/get-started-legacy/add-idf_path-to-profile.rst new file mode 100644 index 000000000..a1f5a1825 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/add-idf_path-to-profile.rst @@ -0,0 +1,66 @@ +在用户配置文件中添加 IDF_PATH (传统 GNU Make) +============================================= +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +为了在系统多次重新启动时保留 “IDF_PATH” 环境变量的设置，请按照以下说明将其添加到用户配置文件中。 + +.. _add-idf_path-to-profile-windows-legacy: + + +Windows +------- + +用户配置文件脚本存放在 ``C:/msys32/etc/profile.d/`` 目录中。每次打开 MSYS2 窗口时，系统都执行这些脚本。 + + +#. 在 ``C:/msys32/etc/profile.d/`` 目录下创建一个新的脚本文件。将其命名为 ``export_idf_path.sh``。 + +#. 确定 ESP-IDF 目录的路径。路径与系统配置有关，例如 ``C:\msys32\home\user-name\esp\esp-idf``。 +#. 在脚本中加入 ``export`` 命令，e.g.:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + + 请将原始 Windows 路径中将反斜杠替换为正斜杠。 + +#. 保存脚本。 + +#. 关闭 MSYS2 窗口并再次打开。输入以下命令检查是否设置了 ``IDF_PATH``:: + + printenv IDF_PATH + +将此前在脚本文件中输入的路径打印出来。 + +如果您不想在用户配置文件中永久设置 ``IDF_PATH``，则应在打开 MSYS2 窗口时手动输入:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + +如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-setup-path-legacy` 小节跳转到了这里，请返回到 :ref:`get-started-start-project-legacy` 小节。 + +.. _add-idf_path-to-profile-linux-macos-legacy: + +Linux and MacOS +--------------- + +在 ``~/.profile`` 文件中加入以下指令，创建 ``IDF_PATH``： + + export IDF_PATH=~/esp/esp-idf + +注销并重新登录以使此更改生效。 + +.. note:: + + 如果将 ``/bin/bash`` 已设为登录 shell，并且 ``.bash_profile`` 和 ``.profile`` 同时存在，则更新 ``.bash_profile``。 + +运行以下命令以确保 ``IDF_PATH`` 已经设置好:: + + printenv IDF_PATH + +此前在 ``~/.profile`` 文件中输入（或者手动设置）的路径应该被打印出来。 + +如果不想永久设置 ``IDF_PATH``，每次重启或者注销时在终端窗口中手动输入:: + + export IDF_PATH=~/esp/esp-idf + +如果您从 :ref:`get-started-setup-path-legacy` 小节跳转到了这里，在安装用于 ESP32 开发的软件时，返回到 :ref:`get-started-start-project-legacy` 小节。 diff --git a/docs/zh_CN/get-started-legacy/eclipse-setup.rst b/docs/zh_CN/get-started-legacy/eclipse-setup.rst new file mode 100644 index 000000000..97dab2618 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/eclipse-setup.rst @@ -0,0 +1,115 @@ +******************************************** +Eclipse IDE 的创建和烧录指南 (传统 GNU Make) +******************************************** +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +.. _eclipse-install-steps-legacy: + +安装 Eclipse IDE +================ + +Eclipse IDE 是一个可视化的集成开发环境，可用于编写、编译和调试 ESP-IDF 项目。 + +* 首先，请在您的平台上安装相应的 ESP-IDF，具体步骤请参考适用于 Windows、OS X 和 Linux 的相应安装步骤。 + +* 我们建议，您应首先使用命令行创建一个项目，大致熟悉项目的创建流程。此外，您还需要使用命令行 (``make menuconfig``) 对您的 ESP-IDF 项目进行配置。目前，Eclipse 尚不支持对 ESP-IDF 项目进行配置。 + +* 下载相应版本的 Eclipse Installer 至您的平台，点击 eclipse.org_。 + +* 运行 Eclipse Installer，选择 “Eclipse for C/C++ Development”（有的版本也可能显示为 CDT）。 + + +配置 Eclipse IDE +================= + +请打开安装好的 Eclipse IDE，并按照以下步骤进行操作： + +导入新项目 +---------- + +* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。 + +* 运行 Eclipse，选择 “File” -> “Import...”。 + +* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。 + +* 在下个界面中 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应输入 ESP-IDF 项目的路径，而非 ESP-IDF 本身的路径（这个稍后再填）。此外，您指定的目标路径中应包含名为 ``Makefile`` （项目 Makefile）的文件。 + +* 在本界面，找到 “Toolchain for Indexer Settings”，选择 “Cross GCC”，最后点击 “Finish”。 + + +项目属性 +-------- + +* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择 “Properties”。 + +* 点击 “C/C++ Build” 下的 “Environment” 属性页，选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。 + +* 再次点击 “Add...”，并在 “IDF_PATH” 中输入 ESP-IDF 所在的完整安装路径。 + +* 选择 “PATH” 环境变量，不要改变默认值。如果 Xtensa 工具链的路径尚不在 “PATH” 列表中，则应将该路径 (``something/xtensa-esp32-elf/bin``) 增加至列表，工具链的典型路径类似于 ``/home/user-name/esp/xtensa-esp32-elf/bin``。请注意您需要在附加路径前添加冒号 ``:``。Windows 用户需要将 ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` 添加到 ``PATH`` 环境变量的靠前位置（如果您将 msys32 安装到了其它目录，则需要更改对应的路径以匹配您的本地环境）。 + +* 在 macOS 平台上，增加一个 “PYTHONPATH” 环境变量，并将其设置为 ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``， 保证系统中预先安装的 Python （需安装 pyserial 模块）可以覆盖 Eclipse 内置的任何 Python。 + +* 前往 “C/C++ General” -> “Preprocessor Include Paths” 属性页面。 + + * 点击 “Providers” 选项卡。 + + * 从 “Providers” 列表中选择 “CDT Cross GCC Built-in Compiler Settings”，将 “Command to get compiler specs” 修改为 ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"`` + + * 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，将 “Compiler command pattern” 修改为 ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` + +* 前往 “C/C++ General” -> “Indexer” 属性页面。 + + * 去除 "Allow heuristic resolution of includes" 勾选。启用此选项时，Eclipse 有时无法找到正确的头文件目录。 + +点击 “C/C++ General" -> "Indexer” 属性页。 + + * 选择 “Enable project specific settings” 以启用本页上的其他设置。 + +.. note:: + + 取消选中 “Allow heuristic resolution of includes”。因为启用此选项时，有时会导致 Eclipse 无法找到正确的头文件目录。 + +点击 “C/C++ Build” -> “Behavior” 属性页。 + +* 选中 “Enable parallel build” 以启用多任务并行构建。 + +.. _eclipse-build-project-legacy: + +在 Eclipse IDE 中创建项目 +-------------------------- + +在首次创建项目前，Eclipse IDE 可能会显示大量有关未定义值的错误和警告，主要原因在于项目编译过程中所需的一些源文件是在 ESP-IDF 项目创建过程中自动生成的。因此，这些错误和警告将在 ESP-IDF 项目生成完成后消失。 + +* 点击 “OK”，关闭 Eclipse IDE 中的 “Properties” 对话框。 + +* 在 Eclipse IDE 界面外，打开命令管理器。进入项目目录，并通过 ``make menuconfig`` 命令对您的 ESP-IDF 项目进行配置。现阶段，您还无法在 Eclipse 中完成本操作。 + +*如果您未进行最开始的配置步骤，ESP-IDF 将提示在命令行中进行配置 - 但由于 Eclipse 暂时不支持相关功能，因此该项目将挂起或创建失败。* + +* 返回 Eclipse IDE 界面中，选择 “Project” -> “Build” 创建您的项目。 + +**提示**：如果您已经在 Eclipse IDE 环境外创建了项目，则可能需要选择 “Project” -> “Clean before choosing Project” -> “Build”，允许 Eclipse 查看所有源文件的编译器参数，并借此确定头文件包含路径。 + +在 Eclipse IDE 中烧录项目 +-------------------------- + +您可以将 ``make flash`` 目标放在 Eclipse 项目中，通过 Eclipse UI 调用 ``esptool.py`` 进行烧录： + +* 打开 “Project Explorer”，并右击您的项目（请注意右击项目本身，而非项目下的子文件，否则 Eclipse 可能会找到错误的 ``Makefile``）。 + +* 从菜单中选择 “Build Targets” -> “Create”。 + +* 输入 “flash” 为目标名称，其他选项使用默认值。 + +* 选择 “Project” -> “Build Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。 + +注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。 + +如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。 + + +.. _eclipse.org: https://www.eclipse.org/ diff --git a/docs/zh_CN/get-started-legacy/establish-serial-connection.rst b/docs/zh_CN/get-started-legacy/establish-serial-connection.rst new file mode 100644 index 000000000..21fafc3c7 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/establish-serial-connection.rst @@ -0,0 +1,132 @@ +与 ESP32 创建串口连接 (传统 GNU Make) +======================================= +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +本章节介绍如何在 ESP32 和 PC 之间建立串口连接。 + +连接 ESP32 和 PC +-------------------- + +用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，确认 ESP32 开发板上的 USB 转串口芯片（或外部串口适配器）型号，在网上搜索驱动程序并进行安装。 + +以下是乐鑫 ESP32 开发板驱动程序的链接： + +* ESP32-PICO-KIT 和 ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers `_ + +* ESP32-WROVER-KIT 和 ESP32 Demo Board - `FTDI Virtual COM Port Drivers `_ + +以上驱动仅用于参考。当您将上述 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中并自动安装。 + +在 Windows 上查看端口 +--------------------- + +检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次显示。 + +以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口： + +.. figure:: ../../_static/esp32-devkitc-in-device-manager.png + :align: center + :alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager + :figclass: align-center + + 设备管理器中 ESP32-DevKitC 的 USB 串口转换器 + +.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png + :align: center + :alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager + :figclass: align-center + + Windows 设备管理器中的两个 USB-WROVER-KIT 串行端口 + +在 Linux 和 MacOS 上检查串口 +----------------------------- + +要查看 ESP32 开发板（或外部串口适配器）的串口设备名称，运行以下命令两次，第一次先拔下开发板或适配器，第二次插入开发板或适配器之后再运行命令，第二次运行指令后出现的端口即是 ESP32 对应的串口： + +Linux :: + + ls /dev/tty* + +MacOS :: + + ls /dev/cu.* + + +.. _linux-dialout-group-legacy: + +在 Linux 添加用户到 ``dialout`` +----------------------------------- + +当前登录用户可以通过 USB 读写串口。在大多数 Linux 发行版中，这是通过以下命令将用户添加到 ``dialout`` 组来完成的:: + + sudo usermod -a -G dialout $USER + +在 Arch Linux 中，需要通过以下命令将用户添加到 ``uucp`` 组中:: + + sudo usermod -a -G uucp $USER + +重新登录以确保串行端口的读写权限被启用。 + + +确认串口连接 +------------------------ + +现在验证串口连接是可用的。您可以使用串口终端程序来执行此操作。在这个例子中，我们将使用 `PuTTY SSH Client `_ ，它有 Windows 和 Linux 等平台的版本。您也可以使用其他串口程序并设置如下的通信参数。 + +运行终端，设置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下是设置串口和在 Windows 和 Linux 上传输参数（如 115200-8-1-N）的一些截屏示例。注意选择上述步骤中确认的串口进行设置。 + +.. figure:: ../../_static/putty-settings-windows.png + :align: center + :alt: Setting Serial Communication in PuTTY on Windows + :figclass: align-center + + 在 Windows 上的 PuTTY 设置串口传输。 + +.. figure:: ../../_static/putty-settings-linux.png + :align: center + :alt: Setting Serial Communication in PuTTY on Linux + :figclass: align-center + + 在 Linux 上的 PuTTY 设置串口传输。 + +在终端打开串口，检查是否有任何打印出来的日志。日志内容取决于加载到 ESP32 的应用程序。下图为 ESP32 的一个示例日志。 + +.. highlight:: none + +:: + + ets Jun 8 2016 00:22:57 + + rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + + rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + configsip: 0, SPIWP:0x00 + clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 + mode:DIO, clock div:2 + load:0x3fff0008,len:8 + load:0x3fff0010,len:3464 + load:0x40078000,len:7828 + load:0x40080000,len:252 + entry 0x40080034 + I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader + I (45) boot: compile time 18:48:10 + + ... + +如果您看到一些清晰的日志，则表示串行连接正常，您可以继续安装，最后将应用程序上载到 ESP32。 + +.. note:: + + 对于某些串口接线配置，在 ESP32 启动并产生串行输出之前，需要在终端程序中禁用串行 RTS ＆ DTR 引脚。这取决于串口适配器硬件本身，大多数开发板（包括所有乐鑫开发板）没有这个问题。此问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况。更多详细信息，参见 `esptool documentation`_。 + +.. note:: + + 验证通讯正常后关闭串口终端。下一步，我们将使用另一个应用程序来上传 ESP32。此应用程序在终端打开时将无法访问串口。 + +如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-connect-legacy` 小节跳转到了这里，请返回到 :ref:`get-started-configure-legacy` 小节继续阅读。 + +.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader + diff --git a/docs/zh_CN/get-started-cmake/index.rst b/docs/zh_CN/get-started-legacy/index.rst similarity index 52% rename from docs/zh_CN/get-started-cmake/index.rst rename to docs/zh_CN/get-started-legacy/index.rst index 73d4f0594..ed569835e 100644 --- a/docs/zh_CN/get-started-cmake/index.rst +++ b/docs/zh_CN/get-started-legacy/index.rst @@ -1,12 +1,9 @@ -******************* -快速入门（CMake） -******************* - +*************************** +快速入门 (传统 GNU Make) +*************************** :link_to_translation:`en:[English]` -.. include:: ../cmake-warning.rst - -.. include:: ../cmake-pending-features.rst +.. include:: ../gnu-make-legacy.rst 本文档旨在指导用户搭建 ESP32 硬件开发的软件环境， @@ -40,13 +37,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 软件： -* 设置 **工具链**，用于编译 ESP32 代码； -* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**； +* 设置 **工具链**，用于编译 ESP32 **应用程序**； * 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本； * 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse `_。 -.. figure:: ../../_static/what-you-need-cmake.png +.. figure:: ../../_static/what-you-need.png :align: center :alt: ESP32 应用程序开发 :figclass: align-center @@ -68,36 +64,35 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> -.. _get-started-step-by-step-cmake: +.. _get-started-step-by-step-legacy: 详细安装步骤 -============== +============ 请根据下方详细步骤，完成安装过程。 设置开发环境 -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~ -* :ref:`get-started-setup-toolchain-cmake` -* :ref:`get-started-get-esp-idf-cmake` -* :ref:`get-started-setup-path-cmake` -* :ref:`get-started-get-packages-cmake` +* :ref:`get-started-setup-toolchain-legacy` +* :ref:`get-started-get-esp-idf-legacy` +* :ref:`get-started-setup-path-legacy` +* :ref:`get-started-get-packages-legacy` 创建您的第一个工程 -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~ -* :ref:`get-started-start-project-cmake` -* :ref:`get-started-connect-cmake` -* :ref:`get-started-configure-cmake` -* :ref:`get-started-build-cmake` -* :ref:`get-started-flash-cmake` -* :ref:`get-started-build-monitor-cmake` +* :ref:`get-started-start-project-legacy` +* :ref:`get-started-connect-legacy` +* :ref:`get-started-configure-legacy` +* :ref:`get-started-build-and-flash-legacy` +* :ref:`get-started-monitor-legacy` -.. _get-started-setup-toolchain-cmake: +.. _get-started-setup-toolchain-legacy: 第一步：设置工具链 -==================== +================== 工具链指一套用于编译代码和应用程序的程序。 @@ -107,49 +102,44 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 :hidden: Windows - Linux - MacOS + Linux + MacOS -+-------------------+-------------------+-------------------+ -| |windows-logo| | |linux-logo| | |macos-logo| | -+-------------------+-------------------+-------------------+ -| `Windows`_ | `Linux`_ | `Mac OS`_ | -+-------------------+-------------------+-------------------+ ++-----------------------------+-------------------------+----------------------------------+ +| |windows-logo| | |linux-logo| | |macos-logo| | ++-----------------------------+-------------------------+----------------------------------+ +| `Windows `_ | `Linux `_ | `Mac OS `_ | ++-----------------------------+-------------------------+----------------------------------+ .. |windows-logo| image:: ../../_static/windows-logo.png - :target: ../get-started-cmake/windows-setup.html + :target: ../get-started-legacy/windows-setup.html .. |linux-logo| image:: ../../_static/linux-logo.png - :target: ../get-started-cmake/linux-setup.html + :target: ../get-started-legacy/linux-setup.html .. |macos-logo| image:: ../../_static/macos-logo.png - :target: ../get-started-cmake/macos-setup.html + :target: ../get-started-legacy/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 +.. _Windows-legacy: ../get-started-legacy/windows-setup.html +.. _Linux-legacy: ../get-started-legacy/linux-setup.html +.. _Mac OS-legacy: ../get-started-legacy/macos-setup.html .. note:: 在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。 -此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置` 章节获取更多信息。 +此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置` 章节获取更多信息。 -.. _get-started-get-esp-idf-cmake: +.. _get-started-get-esp-idf-legacy: 第二步：获取 ESP-IDF -=========================== +===================== 除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 `_。 -请将 ESP-IDF 下载到您的本地。 - 获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。 -Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 打开终端，后运行以下命令： .. include:: /_build/inc/git-clone-bash.inc @@ -158,23 +148,6 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 -Windows 操作系统 -~~~~~~~~~~~~~~~~~~ - -.. note:: - - 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。 - -请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。 - -打开命令提示符，后运行以下命令： - -.. include:: /_build/inc/git-clone-windows.inc - -ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 - -请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 - .. include:: /_build/inc/git-clone-notes.inc .. note:: @@ -184,45 +157,44 @@ ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 cd esp-idf git submodule update --init -.. _get-started-setup-path-cmake: + +.. _get-started-setup-path-legacy: 第三步：设置环境变量 -=========================== +===================== -请在您的 PC 上设置以下环境变量，否则无法编译工程。 +工具链通过环境变量 ``IDF_PATH`` 获得 ESP-IDF 的目录。因此，您需要在 PC 中设置该环境变量，否则无法编译工程。 -- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。 -- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。 - -您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows ` 、:ref:`Linux 及 MacOS ` 操作系统的具体设置方式。 +您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows ` 、:ref:`Linux 及 MacOS ` 操作系统的具体设置方式。 -.. _get-started-get-packages-cmake: +.. _get-started-get-packages-legacy: 第四步：安装 Python 软件包 -================================= - -ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： :: +========================== +ESP-IDF 所需 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： :: + python -m pip install --user -r $IDF_PATH/requirements.txt .. note:: - 请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： + 请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： :: - ``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt`` + python2.7 -m pip install --user -r $IDF_PATH/requirements.txt -.. _get-started-start-project-cmake: + +.. _get-started-start-project-legacy: 第五步：开始创建工程 -======================= +===================== 现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下： Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -230,7 +202,7 @@ Linux 和 MacOS 操作系统 cp -r $IDF_PATH/examples/get-started/hello_world . Windows 操作系统 -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~ .. code-block:: batch @@ -243,10 +215,10 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 ESP-IDF 编译系统不支持带有空格的路径。 -.. _get-started-connect-cmake: - +.. _get-started-connect-legacy: + 第六步：连接设备 -====================== +================== 现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。 @@ -263,36 +235,28 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 请记住串口名，您会在下面的步骤中用到。 -.. _get-started-configure-cmake: +.. _get-started-configure-legacy: 第七步：配置 -================= +============= -请进入 :ref:`get-started-start-project-cmake` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。 +请进入 :ref:`get-started-start-project-legacy` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。 Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash cd ~/esp/hello_world - idf.py menuconfig - -如果您的默认 Python 版本为 3.0 以上，可能需要运行 ``python2 idf.py`` 。 + make menuconfig Windows 操作系统 -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ .. code-block:: batch cd %userprofile%\esp\hello_world - idf.py menuconfig - -Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。 - -.. note:: - - 如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path-cmake`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf-cmake`。 + make menuconfig 如果之前的步骤都正确，则会显示下面的菜单： @@ -303,6 +267,8 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 工程配置 — 主窗口 +进入菜单后，选择 ``Serial flasher config`` > ``Default serial port`` 配置串口（设备将通过该串口加载工程）。按回车键确认选择，点击 ``< Save >`` 保存配置，然后点击 ``< Exit >`` 退出 ``menuconfig``。 + ``menuconfig`` 工具的常见操作见下。 * ``上下箭头``：移动 @@ -310,118 +276,77 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 * ``ESC 键``：返回上级菜单或退出 * ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。 * ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项 -* ``英文问号``：调出有关高亮选项的帮助菜单 +* ``英文问号`` ：调出有关高亮选项的帮助菜单 * ``/ 键``：寻找配置项目 +.. note:: + + 如果您是 **Arch Linux** 用户，请前往 ``SDK tool configuration``，并将 ``Python 2 interpreter`` 的名称从 ``python`` 替换为 ``python2``。 + .. attention:: 如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。 -.. _get-started-build-cmake: +.. _get-started-build-and-flash-legacy: -第八步：编译工程 -================== - -请使用以下命令，编译烧录工程：:: - - idf.py build - -运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。 - -.. code-block:: none - - $ idf.py build - Running cmake in directory /path/to/hello_world/build - Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... - Warn about uninitialized values. - -- Found Git: /usr/bin/git (found version "2.17.0") - -- Building empty aws_iot component due to configuration - -- Component names: ... - -- Component paths: ... - - ... (more lines of build system output) - - [527/527] Generating hello-world.bin - esptool.py v2.3.1 - - Project build complete. To flash, run this command: - ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin - or run 'idf.py -p PORT flash' - -如果一切正常，编译完成后将生成 .bin 文件。 - - -.. _get-started-flash-cmake: - -第九步：烧录到设备 +第八步：编译和烧录 ==================== -请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： :: +请使用以下命令，编译烧录工程： :: - idf.py -p PORT [-b BAUD] flash + make flash -请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect-cmake`。 +运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。接着，这些二进制文件将被烧录至 ESP32 开发板。 -您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。 +如果一切顺利，您可在烧录完成后看到类似下方的打印信息（代表加载进程）。接着，开发板将会复位，应用程序 "hello_world" 开始启动。 -更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。 +.. highlight:: none -.. note:: +:: - 勾选 ``flash`` 选项将自动编译并烧录工程，因此无需再运行 ``idf.py build``。 - -.. code-block:: none - - Running esptool.py in directory [...]/esp/hello_world - Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"... - esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin - esptool.py v2.3.1 - Connecting.... - Detecting chip type... ESP32 - Chip is ESP32D0WDQ6 (revision 1) - Features: WiFi, BT, Dual Core + esptool.py v2.0-beta2 + Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... + esptool.py v2.0-beta2 + Connecting........___ Uploading stub... Running stub... Stub running... - Changing baud rate to 460800 + Changing baud rate to 921600 Changed. + Attaching SPI flash... Configuring flash size... - Auto-detected Flash size: 4MB + Auto-detected Flash size:4MB Flash params set to 0x0220 - Compressed 22992 bytes to 13019... - Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)... + Compressed 11616 bytes to 6695... + Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... + Hash of data verified. + Compressed 408096 bytes to 171625... + Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... Hash of data verified. Compressed 3072 bytes to 82... - Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... Hash of data verified. - Compressed 136672 bytes to 67544... - Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... - Hash of data verified. - + Leaving... - Hard resetting via RTS pin... - -如果一切顺利，烧录完成后，开发板将会复位，应用程序 "hello_world" 开始运行。 - -.. note:: - - （目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse 指南 `。 + Hard resetting... -.. _get-started-build-monitor-cmake: +如果您希望使用 Eclipse IDE，而非 ``make`` 编译系统，请参考 :doc:`Eclipse 指南 `。 -第十步：监视器 -================== -您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。 +.. _get-started-monitor-legacy: + +第九步：监视器 +=============== + +您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。 运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： :: - $ idf.py -p /dev/ttyUSB0 monitor - Running idf_monitor in directory [...]/esp/hello_world/build - Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"... + $ make monitor + MONITOR --- idf_monitor on /dev/ttyUSB0 115200 --- - --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- + --- Quit:Ctrl+] | Menu:Ctrl+T | Help:Ctrl+T followed by Ctrl+H --- ets Jun 8 2016 00:22:57 rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) @@ -435,7 +360,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 ... Hello world! Restarting in 10 seconds... - I (211) cpu_start: Starting scheduler on APP CPU. + I (211) cpu_start:Starting scheduler on APP CPU. Restarting in 9 seconds... Restarting in 8 seconds... Restarting in 7 seconds... @@ -452,45 +377,71 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 此时，请您： 1. 退出监视器。 -2. 打开 :ref:`menuconfig `， +2. 打开 :ref:`menuconfig `， 3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。 -4. 然后，请重新 :ref:`编译和烧录 ` 应用程序。 +4. 然后，请重新 :ref:`编译和烧录 ` 应用程序。 .. note:: - 您也可以运行以下命令，一次性执行构建、烧录和监视过程： + 您也可以运行以下命令，一次性执行构建、烧录和监视过程： :: - ``idf.py -p PORT flash monitor`` + make flash monitor -此外， - -- 请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。 -- 请前往 :ref:`idf.py`，查看更多 ``idf.py`` 命令和选项。 +此外，请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。 **恭喜，您已完成 ESP32 的入门学习！** 现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。 -更新 ESP-IDF -================= -乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf-cmake` 中的指示，重新完成克隆。 +环境变量 +========= + +用户可以在使用 ``make`` 命令时 **直接设置** 部分环境变量，而无需进入 ``make menuconfig`` 进行重新配置。这些变量包括： + ++-----------------+-----------------------------------------------------------------------+ +| 变量 | 描述与使用方式 | ++-----------------+-----------------------------------------------------------------------+ +| ``ESPPORT`` | 覆盖 ``flash`` 和 ``monitor`` 命令使用的串口。 | ++ +-----------------------------------------------------------------------+ +| | 例：``make flash ESPPORT=/dev/ttyUSB1``, ``make monitor ESPPORT=COM1``| ++-----------------+-----------------------------------------------------------------------+ +| ``ESPBAUD`` | 覆盖烧录 ESP32 时使用的串口速率。 | ++ +-----------------------------------------------------------------------+ +| | 例：``make flash ESPBAUD=9600`` | ++-----------------+-----------------------------------------------------------------------+ +| ``MONITORBAUD`` | 覆盖监控时使用的串口速率。 | ++ +-----------------------------------------------------------------------+ +| | 例：``make monitor MONITORBAUD=9600`` | ++-----------------+-----------------------------------------------------------------------+ + +.. note:: + + 您可导出环境变量（例：``export ESPPORT=/dev/ttyUSB1``）。 + 在同一会话窗口中，如果未被同步覆盖，所有 ``make`` 命令均会使用导出的环境变量值。 + + +更新 ESP-IDF +============= + +乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，在使用时，您也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf-legacy` 中的指示，重新完成克隆。 如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH `。否则，工具链将无法找到 ESP-IDF。 此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 ` 章节查看。 相关文档 -=========== +========= .. toctree:: :maxdepth: 1 add-idf_path-to-profile establish-serial-connection + make-project eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch .. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ -.. _Releases page: https://github.com/espressif/esp-idf/releases \ No newline at end of file +.. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/zh_CN/get-started-legacy/linux-setup-scratch.rst b/docs/zh_CN/get-started-legacy/linux-setup-scratch.rst new file mode 100644 index 000000000..bcab391d5 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/linux-setup-scratch.rst @@ -0,0 +1,78 @@ +***************************************************** +从零开始设置 Linux 环境下的工具链 (传统 GNU Make) +***************************************************** +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +.. note:: + + 安装工具链的标准流程可以通过阅读文档 :doc:`Linux 平台工具链的标准设置 ` 来获得，:ref:`工具链的自定义设置 ` 章节会介绍哪些情况下我们必须要重新定义工具链。 + + +安装必要的工具 +============== + +要想使用 ESP-IDF 进行编译，您需要获取以下软件包： + +- Ubuntu 和 Debian:: + + sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + +.. note:: + + 一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。 + 在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 ` 章节，通过 ``pip`` 工具来安装支持的版本。 + +从源代码编译工具链 +================== + +- 安装依赖: + + - CentOS 7:: + + sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool + + - Ubuntu pre-16.04:: + + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool + + - Ubuntu 16.04:: + + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin + + - Debian 9:: + + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin + + - Arch:: + + TODO + +新建工作目录，然后进入:: + + mkdir -p ~/esp + cd ~/esp + + +下载 ``crosstool-NG`` 然后编译: + +.. include:: /_build/inc/scratch-build-code.inc + +编译工具链:: + + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf + +编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Linux 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 + + +下一步 +====== + +继续设置开发环境，请前往 :ref:`获取 ESP-IDF ` 章节。 diff --git a/docs/zh_CN/get-started-legacy/linux-setup.rst b/docs/zh_CN/get-started-legacy/linux-setup.rst new file mode 100644 index 000000000..b51adb676 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/linux-setup.rst @@ -0,0 +1,108 @@ +******************************************* +Linux 平台工具链的标准设置 (传统 GNU Make) +******************************************* +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +安装前提 +===================== + +编译 ESP-IDF 需要以下软件包： + +- CentOS 7:: + + sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial python-pyelftools + +- Ubuntu and Debian:: + + sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + +.. note:: + + 一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。 + 在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 ` 章节，通过 ``pip`` 工具来安装支持的版本。 + +工具链的设置 +=============== + +.. include:: /_build/inc/download-links.inc + +Linux 版的 ESP32 工具链可以从 Espressif 的网站下载： + +- 64-bit Linux： + + |download_link_linux64| + +- 32-bit Linux： + + |download_link_linux32| + +1. 下载完成后，将它解压到 ``~/esp`` 目录： : + + - 64-bit Linux: + + .. include:: /_build/inc/unpack-code-linux64.inc + + - 32-bit Linux: + + .. include:: /_build/inc/unpack-code-linux32.inc + +.. _setup-linux-toolchain-add-it-to-path-legacy: + +2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。 + + 要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中： :: + + export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" + + 或者你也可以给上面的命令创建一个别名。这样做的好处是，你只在需要使用它的时候才获取工具链。将下面这行代码添加到 ``~/.profile`` 文件中即可： :: + + alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' + + 然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。 + + .. note:: + + 如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile`` 。在 CentOS 环境下, ``alias`` 需要添加到 ``.bashrc`` 文件中。 + +3. 退出并重新登录以使 ``.profile`` 更改生效。 运行以下命令来检查 ``PATH`` 设置是否正确： :: + + printenv PATH + + 检查字符串的开头是否包含类似的工具链路径:: + + $ 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 + + 除了 ``/home/user-name``，应该有具体的安装的主路径。 + +权限问题 /dev/ttyUSB0 +------------------------------ + +某些 Linux 版本可能在烧写 ESP32 时会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。 :ref:`可以通过将当前用户添加到拨出组来解决`。 + +Arch Linux 用户 +---------------- + +在 Arch 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。在 AUR_ 中向下兼容的库文件，可用于本地和 lib32 的配置： + +- https://aur.archlinux.org/packages/ncurses5-compat-libs/ +- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ + +在安装这些软件包之前，你可能需要将作者的公钥添加到你的钥匙圈中，上面链接中的“Comments”部分有所叙述。 + +或者，你也可以使用 crosstool-NG 编译一个链接 ncurses 6 的 gdb。 + +后续步骤 +========== + +要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf-legacy` 一节。 + + +.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository + diff --git a/docs/zh_CN/get-started-legacy/macos-setup-scratch.rst b/docs/zh_CN/get-started-legacy/macos-setup-scratch.rst new file mode 100644 index 000000000..fad2de3d6 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/macos-setup-scratch.rst @@ -0,0 +1,74 @@ +************************************************** +从零开始设置 Mac OS 环境下的工具链 (传统 GNU Make) +************************************************** +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +.. note:: + + 安装工具链的标准流程可以通过阅读文档 :doc:`在 MacOS 上安装 ESP32 工具链 ` 来获得， :ref:`工具链的自定义设置 ` 章节会介绍哪些情况下我们必须要重新定义工具链。 + +安装必要的工具 +===================== + +- 安装 pip:: + + sudo easy_install pip + +.. note:: + + ``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 `。 + +从源代码编译工具链 +================== + +- 安装依赖: + + - 安装 MacPorts_ 或者 homebrew_ 包管理器。MacPorts 需要安装完整的 XCode 软件，但是 homebrew 只需要安装 XCode 命令行工具即可。 + + .. _homebrew: https://brew.sh/ + .. _MacPorts: https://www.macports.org/install.php + + - 对于 MacPorts:: + + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake + + - 对于 homebrew:: + + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake + +创建大小写敏感的文件系统镜像:: + + hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" + +挂载:: + + hdiutil mount ~/esp/crosstool.dmg + +创建指向你工作目录的符号链接:: + + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume + +进入新创建的工作目录:: + + cd ~/esp/ctng-volume + +下载 ``crosstool-NG`` 然后编译: + +.. include:: /_build/inc/scratch-build-code.inc + +编译工具链:: + + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf + +编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 + + +下一步 +====== + +继续设置开发环境，请前往 :ref:`获取 ESP-IDF ` 章节。 diff --git a/docs/zh_CN/get-started-legacy/macos-setup.rst b/docs/zh_CN/get-started-legacy/macos-setup.rst new file mode 100644 index 000000000..90f032897 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/macos-setup.rst @@ -0,0 +1,60 @@ +************************************************ +在 Mac OS 上安装 ESP32 工具链 (传统 GNU Make) +************************************************ +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +安装准备 +================ + +- 安装 pip:: + + sudo easy_install pip + +.. note:: + + ``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 `。 + +安装工具链 +=============== + +.. include:: /_build/inc/download-links.inc + +Mac OS 版本的 ESP32 工具链可以从以下地址下载： + +|download_link_osx| + +下载压缩文件之后，解压到 ``~/esp`` 目录中: + +.. include:: /_build/inc/unpack-code-osx.inc + +.. _setup-macos-toolchain-add-it-to-path-legacy: + +工具链将被解压到 ``~/esp/xtensa-esp32-elf/`` 路径下。 + +在 ``~/.profile`` 文件中更新 ``PATH`` 环境变量以使用工具链。为了使 ``xtensa-esp32-elf`` 在各种终端会话中都可用，在 ``~/.profile`` 文件中加上以下指令:: + + export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH + +或者，您可以为上述命令创建一个别名。这样只有执行以下指令时工具链才能被使用。将下面的指令添加到您的 ``〜/ .profile`` 文件中:: + + alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" + +当需要使用工具链时，在命令行里输入 ``get_esp32``，就可以将工具链添加到 ``PATH`` 中。 + + +下一步 +========== + +前往 :ref:`get-started-get-esp-idf-legacy` 继续配置开发环境。 + + +相关文档 +================= + +.. toctree:: + :maxdepth: 1 + + macos-setup-scratch + diff --git a/docs/zh_CN/get-started/make-project.rst b/docs/zh_CN/get-started-legacy/make-project.rst similarity index 94% rename from docs/zh_CN/get-started/make-project.rst rename to docs/zh_CN/get-started-legacy/make-project.rst index 6456d8ef0..cd4031b36 100644 --- a/docs/zh_CN/get-started/make-project.rst +++ b/docs/zh_CN/get-started-legacy/make-project.rst @@ -1,7 +1,9 @@ -通过 make 指令创建和烧录项目 -============================= +通过 make 指令创建和烧录项目 (传统 GNU Make) +============================================ :link_to_translation:`en:[English]` +.. include:: ../gnu-make-legacy.rst + 寻找项目 ----------------- diff --git a/docs/zh_CN/get-started-legacy/toolchain-setup-scratch.rst b/docs/zh_CN/get-started-legacy/toolchain-setup-scratch.rst new file mode 100644 index 000000000..c73c7e80d --- /dev/null +++ b/docs/zh_CN/get-started-legacy/toolchain-setup-scratch.rst @@ -0,0 +1 @@ +.. include:: ../../en/get-started-legacy/toolchain-setup-scratch.rst diff --git a/docs/zh_CN/get-started-legacy/windows-setup-scratch.rst b/docs/zh_CN/get-started-legacy/windows-setup-scratch.rst new file mode 100644 index 000000000..02d164df0 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/windows-setup-scratch.rst @@ -0,0 +1 @@ +.. include:: ../../en/get-started-legacy/windows-setup-scratch.rst diff --git a/docs/zh_CN/get-started-legacy/windows-setup.rst b/docs/zh_CN/get-started-legacy/windows-setup.rst new file mode 100644 index 000000000..ab1bed7d3 --- /dev/null +++ b/docs/zh_CN/get-started-legacy/windows-setup.rst @@ -0,0 +1,69 @@ +********************************************** +Windows 平台工具链的标准设置 (传统 GNU Make) +********************************************** +:link_to_translation:`en:[English]` + +.. include:: ../gnu-make-legacy.rst + +引言 +============ + +Windows 没有内置的 "make" 环境，因此如果要安装工具链，你需要一个 GNU 兼容环境。我们这里使用 MSYS2_ 来提供该环境。你不需要一直使用这个环境（你可以使用 :doc:`Eclipse ` 或其它前端工具），但是它是在后台运行的。 + +工具链的设置 +=============== + +快速设置的方法是从 dl.espressif.com 下载集成在一起的工具链和 MSYS2 压缩文件： + +https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20181001.zip + +将 zip 压缩文件解压到 ``C:\`` (或其它路径，这里假设是 ``C:\``)，它会使用预先准备的环境创建一个 ``msys32`` 目录。 + +检出 +============ + +运行 ``C:\msys32\mingw32.exe`` 打开一个 MSYS2 的终端窗口。该窗口的环境是一个 bash shell。创建一个 ``esp`` 目录作为开发 ESP32 应用的默认地址。运行指令 :: + + mkdir -p ~/esp + +输入 ``cd ~/esp`` 就进入到新创建的目录。如果没有错误信息出现则表明此步骤已完成。 + + +.. figure:: ../../_static/msys2-terminal-window.png + :align: center + :alt: MSYS2 MINGW32 shell window + :figclass: align-center + + MSYS2 终端窗口 + +后续步骤将会使用这个窗口来为 ESP32 设置开发环境。 + +后续步骤 +========== + +要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf-legacy` 一节。 + +更新环境 +======================== + +当 IDF 更新时，有时需要新的工具链，或者将新的需求添加到 Windows MSYS2 环境中。要将旧版本的预编译环境中的数据移动到新版本： + +- 把旧的 MSYS2 环境（即 ``C:\msys32``）移动/重命名为不同的目录（即 ``C:\msys32_old``）。 +- 按照前文所述步骤下载新的预编译环境。 +- 将新的 MSYS2 环境解压缩到 ``C:\msys32`` （或其他位置）。 +- 找到旧的 ``C:\msys32_old\home`` 目录并把它移到 ``C:\msys32``。 +- 如果你不再需要 ``C:\msys32_old`` 可以将它删除。 + +你可以在系统上拥有独立的不同的 MSYS2 环境，前提是在不同的目录中。 + +相关文档 +================= + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + + +.. _MSYS2: https://msys2.github.io/ + diff --git a/docs/zh_CN/get-started/add-idf_path-to-profile.rst b/docs/zh_CN/get-started/add-idf_path-to-profile.rst index 61e8d3dbb..5c051fe53 100644 --- a/docs/zh_CN/get-started/add-idf_path-to-profile.rst +++ b/docs/zh_CN/get-started/add-idf_path-to-profile.rst @@ -1,64 +1,73 @@ -在用户配置文件中添加 IDF_PATH -============================== -:link_to_translation:`en:[English]` +在用户配置文件中添加 IDF_PATH 和 idf.py PATH +========================================================================================================== -为了在系统多次重新启动时保留 “IDF_PATH” 环境变量的设置，请按照以下说明将其添加到用户配置文件中。 +:link_to_translation:`en:[英文]` -.. _add-idf_path-to-profile-windows: +使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量： +- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径 +- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录 -Windows -------- +为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。 -用户配置文件脚本存放在 ``C:/msys32/etc/profile.d/`` 目录中。每次打开 MSYS2 窗口时，系统都执行这些脚本。 +.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。 +.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。 -#. 在 ``C:/msys32/etc/profile.d/`` 目录下创建一个新的脚本文件。将其命名为 ``export_idf_path.sh``。 +.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。 -#. 确定 ESP-IDF 目录的路径。路径与系统配置有关，例如 ``C:\msys32\home\user-name\esp\esp-idf``。 -#. 在脚本中加入 ``export`` 命令，e.g.:: +.. _add-paths-to-profile-windows: - export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" +Windows 操作系统 +----------------------------------- - 请将原始 Windows 路径中将反斜杠替换为正斜杠。 +在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。 -#. 保存脚本。 +在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。 -#. 关闭 MSYS2 窗口并再次打开。输入以下命令检查是否设置了 ``IDF_PATH``:: +你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。 - printenv IDF_PATH +- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。 +- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。 -将此前在脚本文件中输入的路径打印出来。 +如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。 -如果您不想在用户配置文件中永久设置 ``IDF_PATH``，则应在打开 MSYS2 窗口时手动输入:: - - export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" - -如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-setup-path` 小节跳转到了这里，请返回到 :ref:`get-started-start-project` 小节。 .. _add-idf_path-to-profile-linux-macos: -Linux and MacOS ---------------- +Linux 和 MacOS 操作系统 +------------------------------------ -在 ``~/.profile`` 文件中加入以下指令，创建 ``IDF_PATH``： +要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中:: export IDF_PATH=~/esp/esp-idf - -注销并重新登录以使此更改生效。 + export PATH="$IDF_PATH/tools:$PATH" .. note:: - 如果将 ``/bin/bash`` 已设为登录 shell，并且 ``.bash_profile`` 和 ``.profile`` 同时存在，则更新 ``.bash_profile``。 - -运行以下命令以确保 ``IDF_PATH`` 已经设置好:: + ``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。 + +请退出，并重新登录使更改生效。 + +.. note:: + + 并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。 + +运行以下命令来检查 ``IDF_PATH`` 设置是否正确:: printenv IDF_PATH -此前在 ``~/.profile`` 文件中输入（或者手动设置）的路径应该被打印出来。 +此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。 -如果不想永久设置 ``IDF_PATH``，每次重启或者注销时在终端窗口中手动输入:: +为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令:: + + which idf.py + +这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。 + +如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入:: export IDF_PATH=~/esp/esp-idf + export PATH="$IDF_PATH/tools:$PATH" -如果您从 :ref:`get-started-setup-path` 小节跳转到了这里，在安装用于 ESP32 开发的软件时，返回到 :ref:`get-started-start-project` 小节。 +如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。 diff --git a/docs/zh_CN/get-started/eclipse-setup.rst b/docs/zh_CN/get-started/eclipse-setup.rst index 13e66b826..066544708 100644 --- a/docs/zh_CN/get-started/eclipse-setup.rst +++ b/docs/zh_CN/get-started/eclipse-setup.rst @@ -1,113 +1,9 @@ -**************************** -Eclipse IDE 的创建和烧录指南 -**************************** +**************************************** +Eclipse IDE 创建和烧录指南 +**************************************** + :link_to_translation:`en:[English]` -.. _eclipse-install-steps: - -安装 Eclipse IDE -================ - -Eclipse IDE 是一个可视化的集成开发环境，可用于编写、编译和调试 ESP-IDF 项目。 - -* 首先，请在您的平台上安装相应的 ESP-IDF，具体步骤请参考适用于 Windows、OS X 和 Linux 的相应安装步骤。 - -* 我们建议，您应首先使用命令行创建一个项目，大致熟悉项目的创建流程。此外，您还需要使用命令行 (``make menuconfig``) 对您的 ESP-IDF 项目进行配置。目前，Eclipse 尚不支持对 ESP-IDF 项目进行配置。 - -* 下载相应版本的 Eclipse Installer 至您的平台，点击 eclipse.org_。 - -* 运行 Eclipse Installer，选择 “Eclipse for C/C++ Development”（有的版本也可能显示为 CDT）。 - - -配置 Eclipse IDE -================= - -请打开安装好的 Eclipse IDE，并按照以下步骤进行操作： - -导入新项目 ----------- - -* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。 - -* 运行 Eclipse，选择 “File” -> “Import...”。 - -* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。 - -* 在下个界面中 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应输入 ESP-IDF 项目的路径，而非 ESP-IDF 本身的路径（这个稍后再填）。此外，您指定的目标路径中应包含名为 ``Makefile`` （项目 Makefile）的文件。 - -* 在本界面，找到 “Toolchain for Indexer Settings”，选择 “Cross GCC”，最后点击 “Finish”。 - - -项目属性 --------- - -* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择 “Properties”。 - -* 点击 “C/C++ Build” 下的 “Environment” 属性页，选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。 - -* 再次点击 “Add...”，并在 “IDF_PATH” 中输入 ESP-IDF 所在的完整安装路径。 - -* 选择 “PATH” 环境变量，不要改变默认值。如果 Xtensa 工具链的路径尚不在 “PATH” 列表中，则应将该路径 (``something/xtensa-esp32-elf/bin``) 增加至列表，工具链的典型路径类似于 ``/home/user-name/esp/xtensa-esp32-elf/bin``。请注意您需要在附加路径前添加冒号 ``:``。Windows 用户需要将 ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` 添加到 ``PATH`` 环境变量的靠前位置（如果您将 msys32 安装到了其它目录，则需要更改对应的路径以匹配您的本地环境）。 - -* 在 macOS 平台上，增加一个 “PYTHONPATH” 环境变量，并将其设置为 ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``， 保证系统中预先安装的 Python （需安装 pyserial 模块）可以覆盖 Eclipse 内置的任何 Python。 - -* 前往 “C/C++ General” -> “Preprocessor Include Paths” 属性页面。 - - * 点击 “Providers” 选项卡。 - - * 从 “Providers” 列表中选择 “CDT Cross GCC Built-in Compiler Settings”，将 “Command to get compiler specs” 修改为 ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"`` - - * 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，将 “Compiler command pattern” 修改为 ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` - -* 前往 “C/C++ General” -> “Indexer” 属性页面。 - - * 去除 "Allow heuristic resolution of includes" 勾选。启用此选项时，Eclipse 有时无法找到正确的头文件目录。 - -点击 “C/C++ General" -> "Indexer” 属性页。 - - * 选择 “Enable project specific settings” 以启用本页上的其他设置。 - -.. note:: - - 取消选中 “Allow heuristic resolution of includes”。因为启用此选项时，有时会导致 Eclipse 无法找到正确的头文件目录。 - -点击 “C/C++ Build” -> “Behavior” 属性页。 - -* 选中 “Enable parallel build” 以启用多任务并行构建。 - -.. _eclipse-build-project: - -在 Eclipse IDE 中创建项目 --------------------------- - -在首次创建项目前，Eclipse IDE 可能会显示大量有关未定义值的错误和警告，主要原因在于项目编译过程中所需的一些源文件是在 ESP-IDF 项目创建过程中自动生成的。因此，这些错误和警告将在 ESP-IDF 项目生成完成后消失。 - -* 点击 “OK”，关闭 Eclipse IDE 中的 “Properties” 对话框。 - -* 在 Eclipse IDE 界面外，打开命令管理器。进入项目目录，并通过 ``make menuconfig`` 命令对您的 ESP-IDF 项目进行配置。现阶段，您还无法在 Eclipse 中完成本操作。 - -*如果您未进行最开始的配置步骤，ESP-IDF 将提示在命令行中进行配置 - 但由于 Eclipse 暂时不支持相关功能，因此该项目将挂起或创建失败。* - -* 返回 Eclipse IDE 界面中，选择 “Project” -> “Build” 创建您的项目。 - -**提示**：如果您已经在 Eclipse IDE 环境外创建了项目，则可能需要选择 “Project” -> “Clean before choosing Project” -> “Build”，允许 Eclipse 查看所有源文件的编译器参数，并借此确定头文件包含路径。 - -在 Eclipse IDE 中烧录项目 --------------------------- - -您可以将 ``make flash`` 目标放在 Eclipse 项目中，通过 Eclipse UI 调用 ``esptool.py`` 进行烧录： - -* 打开 “Project Explorer”，并右击您的项目（请注意右击项目本身，而非项目下的子文件，否则 Eclipse 可能会找到错误的 ``Makefile``）。 - -* 从菜单中选择 “Build Targets” -> “Create”。 - -* 输入 “flash” 为目标名称，其他选项使用默认值。 - -* 选择 “Project” -> “Build Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。 - -注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。 - -如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。 - +有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。 .. _eclipse.org: https://www.eclipse.org/ diff --git a/docs/zh_CN/get-started/establish-serial-connection.rst b/docs/zh_CN/get-started/establish-serial-connection.rst index b27c42962..0219250dd 100644 --- a/docs/zh_CN/get-started/establish-serial-connection.rst +++ b/docs/zh_CN/get-started/establish-serial-connection.rst @@ -1,47 +1,67 @@ 与 ESP32 创建串口连接 -========================= +============================================== + :link_to_translation:`en:[English]` -本章节介绍如何在 ESP32 和 PC 之间建立串口连接。 +本章节主要介绍如何创建 ESP32 和 PC 之间的串口连接。 + 连接 ESP32 和 PC -------------------- -用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，确认 ESP32 开发板上的 USB 转串口芯片（或外部串口适配器）型号，在网上搜索驱动程序并进行安装。 +用 USB 线将 ESP32 开发板连接到 PC。如果设备驱动程序没有自动安装，请先确认 ESP32 开发板上的 USB 转串口芯片（或外部转串口适配器）型号，然后在网上搜索驱动程序，并进行手动安装。 以下是乐鑫 ESP32 开发板驱动程序的链接： -* ESP32-PICO-KIT 和 ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers `_ +.. csv-table:: + :header: 开发板, USB 驱动, 备注 + :widths: 40, 20, 40 -* ESP32-WROVER-KIT 和 ESP32 Demo Board - `FTDI Virtual COM Port Drivers `_ + :ref:`ESP32-DevKitC `, `CP210x`_ + `ESP32-LyraT `_, `CP210x`_ + `ESP32-LyraTD-MSC `_, `CP210x`_ + :ref:`ESP32-PICO-KIT `, `CP210x`_ + :ref:`ESP-WROVER-KIT `, `FTDI`_ + :ref:`ESP32 Demo 板 `, `FTDI`_ + `ESP-Prog`_, `FTDI`_, 编程板 (w/o ESP32) + `ESP32-MeshKit-Sense `_, n/a, 搭配 `ESP-Prog`_ 使用 + `ESP32-Sense Kit `_, n/a, 搭配 `ESP-Prog`_ 使用 -以上驱动仅用于参考。当您将上述 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中并自动安装。 +.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers +.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm +.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board + +* CP210x: `CP210x USB 至 UART 桥 VCP 驱动程序 `_ +* FTDI: `FTDI 虚拟 COM 端口驱动程序 `_ + +以上驱动仅用于参考。一般情况下，当上述任一 ESP32 开发板与 PC 连接时，对应驱动程序应该已经被打包在操作系统中，并已经自动安装。 在 Windows 上查看端口 --------------------- -检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次显示。 +检查 Windows 设备管理器中的 COM 端口列表。断开 ESP32 与 PC 的连接，然后重新连接，查看哪个端口从列表中消失，然后再次出现。 以下为 ESP32 DevKitC 和 ESP32 WROVER KIT 串口： .. figure:: ../../_static/esp32-devkitc-in-device-manager.png :align: center - :alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager + :alt: 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 :figclass: align-center - 设备管理器中 ESP32-DevKitC 的 USB 串口转换器 + 设备管理器中 ESP32-DevKitC 的 USB 至 UART 桥 .. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png :align: center - :alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager + :alt: Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口 :figclass: align-center - Windows 设备管理器中的两个 USB-WROVER-KIT 串行端口 + Windows 设备管理器中 ESP-WROVER-KIT 的两个 USB 串行端口 -在 Linux 和 MacOS 上检查串口 + +在 Linux 和 MacOS 上查看端口 ----------------------------- -要查看 ESP32 开发板（或外部串口适配器）的串口设备名称，运行以下命令两次，第一次先拔下开发板或适配器，第二次插入开发板或适配器之后再运行命令，第二次运行指令后出现的端口即是 ESP32 对应的串口： +查看 ESP32 开发板（或外部转串口适配器）的串口设备名称，请运行两次以下命令。首先，断开开发板或适配器，第一次运行命令；然后，连接开发板或适配器，第二次运行命令。其中，第二次运行命令后出现的端口即是 ESP32 对应的串口： Linux :: @@ -51,13 +71,16 @@ MacOS :: ls /dev/cu.* +.. note:: + + 对于 MacOS 用户：若你没有看到串口，请检查你是否已按照《入门指南》安装了适用于你特定开发板的 USB/串口驱动程序。对于 MacOS High Sierra (10.13) 的用户，你可能还需要手动允许驱动程序的加载，具体可打开 ``系统偏好设置`` -> ``安全和隐私`` -> ``通用``，检查是否有信息显示：“来自开发人员的系统软件...”，其中开发人员的名称为 Silicon Labs 或 FTDI。 .. _linux-dialout-group: -在 Linux 添加用户到 ``dialout`` +在 Linux 中添加用户到 ``dialout`` ----------------------------------- -当前登录用户可以通过 USB 读写串口。在大多数 Linux 发行版中，这是通过以下命令将用户添加到 ``dialout`` 组来完成的:: +当前登录用户应当可以通过 USB 对串口进行读写操作。在多数 Linux 版本中，你都可以通过以下命令，将用户添加到 ``dialout`` 组，来获许读写权限:: sudo usermod -a -G dialout $USER @@ -65,31 +88,32 @@ MacOS :: sudo usermod -a -G uucp $USER -重新登录以确保串行端口的读写权限被启用。 +请重新登录，确保串口读写权限可以生效。 确认串口连接 ------------------------ -现在验证串口连接是可用的。您可以使用串口终端程序来执行此操作。在这个例子中，我们将使用 `PuTTY SSH Client `_ ，它有 Windows 和 Linux 等平台的版本。您也可以使用其他串口程序并设置如下的通信参数。 +现在，请使用串口终端程序，验证串口连接是否可用。在本示例中，我们将使用 `PuTTY SSH Client `_， `PuTTY SSH Client `_ 既可用于 Windows 也可用于 Linux。你也可以使用其他串口程序并设置如下的通信参数。 -运行终端，设置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下是设置串口和在 Windows 和 Linux 上传输参数（如 115200-8-1-N）的一些截屏示例。注意选择上述步骤中确认的串口进行设置。 +运行终端，配置串口：波特率 = 115200，数据位 = 8，停止位 = 1，奇偶校验 = N。以下截屏分别展示了在 Windows 和 Linux 中配置串口和上述通信参数（如 115200-8-1-N）。注意，这里一定要选择在上述步骤中确认的串口进行配置。 .. figure:: ../../_static/putty-settings-windows.png :align: center - :alt: Setting Serial Communication in PuTTY on Windows + :alt: 在 Windows 操作系统中使用 PuTTY 设置串口通信参数 :figclass: align-center - 在 Windows 上的 PuTTY 设置串口传输。 + 在 Windows 操作系统中使用 PuTTY 设置串口通信参数 .. figure:: ../../_static/putty-settings-linux.png :align: center - :alt: Setting Serial Communication in PuTTY on Linux + :alt: 在 Linux 操作系统中使用 PuTTY 设置串口通信参数 :figclass: align-center - 在 Linux 上的 PuTTY 设置串口传输。 + 在 Linux 操作系统中使用 PuTTY 设置串口通信参数 -在终端打开串口，检查是否有任何打印出来的日志。日志内容取决于加载到 ESP32 的应用程序。下图为 ESP32 的一个示例日志。 + +然后，请检查 ESP32 是否有打印日志。如有，请在终端打开串口进行查看。这里，日志内容取决于加载到 ESP32 的应用程序，下图即为一个示例。 .. highlight:: none @@ -114,17 +138,18 @@ MacOS :: ... -如果您看到一些清晰的日志，则表示串行连接正常，您可以继续安装，最后将应用程序上载到 ESP32。 +如果打印出的日志是可读的（而不是乱码），则表示串口连接正常。此时，你可以继续进行安装，并最终将应用程序上载到 ESP32。 .. note:: - 对于某些串口接线配置，在 ESP32 启动并产生串行输出之前，需要在终端程序中禁用串行 RTS ＆ DTR 引脚。这取决于串口适配器硬件本身，大多数开发板（包括所有乐鑫开发板）没有这个问题。此问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况。更多详细信息，参见 `esptool documentation`_。 + 在某些串口接线方式下，在 ESP32 启动并开始打印串口日志前，需要在终端程序中禁用串口 RTS ＆ DTR 引脚。该问题仅存在于将 RTS ＆ DTR 引脚直接连接到 EN ＆ GPIO0 引脚上的情况，绝大多数开发板（包括乐鑫所有的开发板）都没有这个问题。更多详细信息，参见 `esptool 文档`_。 .. note:: - 验证通讯正常后关闭串口终端。下一步，我们将使用另一个应用程序来上传 ESP32。此应用程序在终端打开时将无法访问串口。 + 请在验证完串口通信正常后，关闭串口终端。下一步，我们将使用另一个应用程序将新的固件上传到 ESP32。此时，如果串口被占用则无法成功。 -如您在安装用于 ESP32 开发的软件时，从 :ref:`get-started-connect` 小节跳转到了这里，请返回到 :ref:`get-started-configure` 小节继续阅读。 +如你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-connect` 跳转到了这里，请从 :ref:`get-started-configure` 继续阅读。 -.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader + +.. _esptool 文档: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 6afcc12e3..1baf28fcb 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -1,6 +1,6 @@ -******** -快速入门 -******** +******************* +快速入门（CMake） +******************* :link_to_translation:`en:[English]` @@ -36,7 +36,8 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 软件： -* 设置 **工具链**，用于编译 ESP32 **应用程序**； +* 设置 **工具链**，用于编译 ESP32 代码； +* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**； * 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本； * 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse `_。 @@ -66,12 +67,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 .. _get-started-step-by-step: 详细安装步骤 -============ +============== 请根据下方详细步骤，完成安装过程。 设置开发环境 -~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ * :ref:`get-started-setup-toolchain` * :ref:`get-started-get-esp-idf` @@ -79,19 +80,20 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 * :ref:`get-started-get-packages` 创建您的第一个工程 -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ * :ref:`get-started-start-project` * :ref:`get-started-connect` * :ref:`get-started-configure` -* :ref:`get-started-build-and-flash` -* :ref:`get-started-monitor` +* :ref:`get-started-build` +* :ref:`get-started-flash` +* :ref:`get-started-build-monitor` .. _get-started-setup-toolchain: 第一步：设置工具链 -================== +==================== 工具链指一套用于编译代码和应用程序的程序。 @@ -101,8 +103,8 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 :hidden: Windows - Linux - MacOS + Linux + MacOS +-------------------+-------------------+-------------------+ | |windows-logo| | |linux-logo| | |macos-logo| | @@ -133,12 +135,17 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 .. _get-started-get-esp-idf: 第二步：获取 ESP-IDF -===================== +=========================== 除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 `_。 +请将 ESP-IDF 下载到您的本地。 + 获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。 +Linux 和 MacOS 操作系统 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 打开终端，后运行以下命令： .. include:: /_build/inc/git-clone-bash.inc @@ -147,6 +154,23 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 +Windows 操作系统 +~~~~~~~~~~~~~~~~~~ + +.. note:: + + 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。 + +请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。 + +打开命令提示符，后运行以下命令： + +.. include:: /_build/inc/git-clone-windows.inc + +ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 + +请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 + .. include:: /_build/inc/git-clone-notes.inc .. note:: @@ -156,44 +180,45 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。 cd esp-idf git submodule update --init - .. _get-started-setup-path: 第三步：设置环境变量 -===================== +=========================== -工具链通过环境变量 ``IDF_PATH`` 获得 ESP-IDF 的目录。因此，您需要在 PC 中设置该环境变量，否则无法编译工程。 +请在您的 PC 上设置以下环境变量，否则无法编译工程。 -您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows ` 、:ref:`Linux 及 MacOS ` 操作系统的具体设置方式。 +- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。 +- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。 + +您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows ` 、:ref:`Linux 及 MacOS ` 操作系统的具体设置方式。 .. _get-started-get-packages: 第四步：安装 Python 软件包 -========================== +================================= + +ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： :: -ESP-IDF 所需 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： :: - python -m pip install --user -r $IDF_PATH/requirements.txt .. note:: - 请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： :: - - python2.7 -m pip install --user -r $IDF_PATH/requirements.txt + 请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： + ``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt`` .. _get-started-start-project: 第五步：开始创建工程 -===================== +======================= 现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下： Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -201,7 +226,7 @@ Linux 和 MacOS 操作系统 cp -r $IDF_PATH/examples/get-started/hello_world . Windows 操作系统 -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: batch @@ -215,9 +240,9 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 ESP-IDF 编译系统不支持带有空格的路径。 .. _get-started-connect: - + 第六步：连接设备 -================== +====================== 现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。 @@ -237,25 +262,33 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 .. _get-started-configure: 第七步：配置 -============= +================= 请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。 Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash cd ~/esp/hello_world - make menuconfig + idf.py menuconfig + +如果您的默认 Python 版本为 3.0 以上，可能需要运行 ``python2 idf.py`` 。 Windows 操作系统 -~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~ .. code-block:: batch cd %userprofile%\esp\hello_world - make menuconfig + idf.py menuconfig + +Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。 + +.. note:: + + 如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf`。 如果之前的步骤都正确，则会显示下面的菜单： @@ -266,8 +299,6 @@ Windows 操作系统 工程配置 — 主窗口 -进入菜单后，选择 ``Serial flasher config`` > ``Default serial port`` 配置串口（设备将通过该串口加载工程）。按回车键确认选择，点击 ``< Save >`` 保存配置，然后点击 ``< Exit >`` 退出 ``menuconfig``。 - ``menuconfig`` 工具的常见操作见下。 * ``上下箭头``：移动 @@ -275,77 +306,118 @@ Windows 操作系统 * ``ESC 键``：返回上级菜单或退出 * ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。 * ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项 -* ``英文问号`` ：调出有关高亮选项的帮助菜单 +* ``英文问号``：调出有关高亮选项的帮助菜单 * ``/ 键``：寻找配置项目 -.. note:: - - 如果您是 **Arch Linux** 用户，请前往 ``SDK tool configuration``，并将 ``Python 2 interpreter`` 的名称从 ``python`` 替换为 ``python2``。 - .. attention:: 如果您使用的是 ESP32-DevKitC（板载 ESP32-SOLO-1 模组），请在烧写示例程序前，前往 ``menuconfig`` 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。 -.. _get-started-build-and-flash: +.. _get-started-build: -第八步：编译和烧录 +第八步：编译工程 +================== + +请使用以下命令，编译烧录工程：:: + + idf.py build + +运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。 + +.. code-block:: none + + $ idf.py build + Running cmake in directory /path/to/hello_world/build + Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... + Warn about uninitialized values. + -- Found Git: /usr/bin/git (found version "2.17.0") + -- Building empty aws_iot component due to configuration + -- Component names: ... + -- Component paths: ... + + ... (more lines of build system output) + + [527/527] Generating hello-world.bin + esptool.py v2.3.1 + + Project build complete. To flash, run this command: + ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin + or run 'idf.py -p PORT flash' + +如果一切正常，编译完成后将生成 .bin 文件。 + + +.. _get-started-flash: + +第九步：烧录到设备 ==================== -请使用以下命令，编译烧录工程： :: +请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： :: - make flash + idf.py -p PORT [-b BAUD] flash -运行以上命令可以编译应用程序和所有 ESP-IDF 组件，接着生成 bootloader、分区表和应用程序二进制文件。接着，这些二进制文件将被烧录至 ESP32 开发板。 +请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect`。 -如果一切顺利，您可在烧录完成后看到类似下方的打印信息（代表加载进程）。接着，开发板将会复位，应用程序 "hello_world" 开始启动。 +您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。 -.. highlight:: none +更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。 -:: +.. note:: - esptool.py v2.0-beta2 - Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... - esptool.py v2.0-beta2 - Connecting........___ + 勾选 ``flash`` 选项将自动编译并烧录工程，因此无需再运行 ``idf.py build``。 + +.. code-block:: none + + Running esptool.py in directory [...]/esp/hello_world + Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"... + esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin + esptool.py v2.3.1 + Connecting.... + Detecting chip type... ESP32 + Chip is ESP32D0WDQ6 (revision 1) + Features: WiFi, BT, Dual Core Uploading stub... Running stub... Stub running... - Changing baud rate to 921600 + Changing baud rate to 460800 Changed. - Attaching SPI flash... Configuring flash size... - Auto-detected Flash size:4MB + Auto-detected Flash size: 4MB Flash params set to 0x0220 - Compressed 11616 bytes to 6695... - Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... - Hash of data verified. - Compressed 408096 bytes to 171625... - Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... + Compressed 22992 bytes to 13019... + Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)... Hash of data verified. Compressed 3072 bytes to 82... - Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)... Hash of data verified. - + Compressed 136672 bytes to 67544... + Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... + Hash of data verified. + Leaving... - Hard resetting... + Hard resetting via RTS pin... + +如果一切顺利，烧录完成后，开发板将会复位，应用程序 "hello_world" 开始运行。 + +.. note:: + + （目前不支持）如果您希望使用 Eclipse IDE，而非 ``idf.py``，请参考 :doc:`Eclipse 指南 `。 -如果您希望使用 Eclipse IDE，而非 ``make`` 编译系统，请参考 :doc:`Eclipse 指南 `。 +.. _get-started-build-monitor: +第十步：监视器 +================== -.. _get-started-monitor: - -第九步：监视器 -=============== - -您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。 +您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。 运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： :: - $ make monitor - MONITOR + $ idf.py -p /dev/ttyUSB0 monitor + Running idf_monitor in directory [...]/esp/hello_world/build + Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"... --- idf_monitor on /dev/ttyUSB0 115200 --- - --- Quit:Ctrl+] | Menu:Ctrl+T | Help:Ctrl+T followed by Ctrl+H --- + --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- ets Jun 8 2016 00:22:57 rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) @@ -359,7 +431,7 @@ Windows 操作系统 ... Hello world! Restarting in 10 seconds... - I (211) cpu_start:Starting scheduler on APP CPU. + I (211) cpu_start: Starting scheduler on APP CPU. Restarting in 9 seconds... Restarting in 8 seconds... Restarting in 7 seconds... @@ -378,69 +450,44 @@ Windows 操作系统 1. 退出监视器。 2. 打开 :ref:`menuconfig `， 3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。 -4. 然后，请重新 :ref:`编译和烧录 ` 应用程序。 +4. 然后，请重新 :ref:`编译和烧录 ` 应用程序。 .. note:: - 您也可以运行以下命令，一次性执行构建、烧录和监视过程： :: + 您也可以运行以下命令，一次性执行构建、烧录和监视过程： - make flash monitor + ``idf.py -p PORT flash monitor`` -此外，请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。 +此外， + +- 请前往 :doc:`IDF 监视器 <../api-guides/tools/idf-monitor>`，了解更多使用 IDF 监视器的快捷键和其他详情。 +- 请前往 :ref:`idf.py`，查看更多 ``idf.py`` 命令和选项。 **恭喜，您已完成 ESP32 的入门学习！** 现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。 - -环境变量 -========= - -用户可以在使用 ``make`` 命令时 **直接设置** 部分环境变量，而无需进入 ``make menuconfig`` 进行重新配置。这些变量包括： - -+-----------------+-----------------------------------------------------------------------+ -| 变量 | 描述与使用方式 | -+-----------------+-----------------------------------------------------------------------+ -| ``ESPPORT`` | 覆盖 ``flash`` 和 ``monitor`` 命令使用的串口。 | -+ +-----------------------------------------------------------------------+ -| | 例：``make flash ESPPORT=/dev/ttyUSB1``, ``make monitor ESPPORT=COM1``| -+-----------------+-----------------------------------------------------------------------+ -| ``ESPBAUD`` | 覆盖烧录 ESP32 时使用的串口速率。 | -+ +-----------------------------------------------------------------------+ -| | 例：``make flash ESPBAUD=9600`` | -+-----------------+-----------------------------------------------------------------------+ -| ``MONITORBAUD`` | 覆盖监控时使用的串口速率。 | -+ +-----------------------------------------------------------------------+ -| | 例：``make monitor MONITORBAUD=9600`` | -+-----------------+-----------------------------------------------------------------------+ - -.. note:: - - 您可导出环境变量（例：``export ESPPORT=/dev/ttyUSB1``）。 - 在同一会话窗口中，如果未被同步覆盖，所有 ``make`` 命令均会使用导出的环境变量值。 - - 更新 ESP-IDF -============= +================= -乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，在使用时，您也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 +乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH `。否则，工具链将无法找到 ESP-IDF。 此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 ` 章节查看。 相关文档 -========= +=========== .. toctree:: :maxdepth: 1 add-idf_path-to-profile establish-serial-connection - make-project eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch + ../get-started-legacy/index .. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ -.. _Releases page: https://github.com/espressif/esp-idf/releases \ No newline at end of file +.. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/zh_CN/get-started/linux-setup-scratch.rst b/docs/zh_CN/get-started/linux-setup-scratch.rst index 4b58f2d08..1c37b35d3 100644 --- a/docs/zh_CN/get-started/linux-setup-scratch.rst +++ b/docs/zh_CN/get-started/linux-setup-scratch.rst @@ -1,63 +1,63 @@ -********************************** +****************************************** 从零开始设置 Linux 环境下的工具链 -********************************** +****************************************** + :link_to_translation:`en:[English]` -.. note:: +除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。 - 安装工具链的标准流程可以通过阅读文档 :doc:`Linux 平台工具链的标准设置 ` 来获得，:ref:`工具链的自定义设置 ` 章节会介绍哪些情况下我们必须要重新定义工具链。 +安装准备 +===================== +编译 ESP-IDF 需要以下软件包： -安装必要的工具 -============== +- CentOS 7:: -要想使用 ESP-IDF 进行编译，您需要获取以下软件包： + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - Ubuntu 和 Debian:: - sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache + .. note:: - - 一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。 - 在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 ` 章节，通过 ``pip`` 工具来安装支持的版本。 + 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 从源代码编译工具链 -================== +================================= -- 安装依赖: +- 安装依赖： - CentOS 7:: - sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool + sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make - Ubuntu pre-16.04:: - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make - - Ubuntu 16.04:: + - Ubuntu 16.04 及以上:: - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make - Debian 9:: - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make - Arch:: TODO -新建工作目录，然后进入:: +创建工作目录，并进入该目录:: mkdir -p ~/esp cd ~/esp - -下载 ``crosstool-NG`` 然后编译: +下载并编译 ``crosstool-NG`` ： .. include:: /_build/inc/scratch-build-code.inc @@ -67,10 +67,11 @@ ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Linux 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 +编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 -下一步 -====== +后续步骤 +========== + +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 -继续设置开发环境，请前往 :ref:`获取 ESP-IDF ` 章节。 diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst index 72bcbfabc..2a05e8fea 100644 --- a/docs/zh_CN/get-started/linux-setup.rst +++ b/docs/zh_CN/get-started/linux-setup.rst @@ -1,9 +1,8 @@ -***************************** +******************************************************************* Linux 平台工具链的标准设置 -***************************** -:link_to_translation:`en:[English]` +******************************************************************* -.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 +:link_to_translation:`en:[英文]` 安装前提 ===================== @@ -12,65 +11,63 @@ Linux 平台工具链的标准设置 - CentOS 7:: - sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial python-pyelftools + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache -- Ubuntu and Debian:: +- Ubuntu 和 Debian:: - sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-click python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache .. note:: - - 一些旧的（2014年之前）Linux 发行版中使用的 ``pyserial`` 版本可能是 2.x ， ESP-IDF并不支持。 - 在这种情况下，请参考 :ref:`安装依赖的 Python 软件包 ` 章节，通过 ``pip`` 工具来安装支持的版本。 + 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 工具链的设置 -=============== +========================= .. include:: /_build/inc/download-links.inc Linux 版的 ESP32 工具链可以从 Espressif 的网站下载： -- 64-bit Linux： +- 64 位 Linux： |download_link_linux64| -- 32-bit Linux： +- 32 位 Linux： |download_link_linux32| -1. 下载完成后，将它解压到 ``~/esp`` 目录： : +1. 下载完成后，将它解压到 ``~/esp`` 目录： - - 64-bit Linux: + - for 64-bit Linux: .. include:: /_build/inc/unpack-code-linux64.inc - - 32-bit Linux: + - for 32-bit Linux: .. include:: /_build/inc/unpack-code-linux32.inc .. _setup-linux-toolchain-add-it-to-path: -2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。 +2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。 - 要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中： :: + 要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：:: - export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" + export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" - 或者你也可以给上面的命令创建一个别名。这样做的好处是，你只在需要使用它的时候才获取工具链。将下面这行代码添加到 ``~/.profile`` 文件中即可： :: + 或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可:: - alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' + alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' - 然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。 + 然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。 .. note:: - 如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile`` 。在 CentOS 环境下, ``alias`` 需要添加到 ``.bashrc`` 文件中。 + 如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。 -3. 退出并重新登录以使 ``.profile`` 更改生效。 运行以下命令来检查 ``PATH`` 设置是否正确： :: +3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确:: printenv PATH @@ -81,28 +78,40 @@ Linux 版的 ESP32 工具链可以从 Espressif 的网站下载： 除了 ``/home/user-name``，应该有具体的安装的主路径。 -权限问题 /dev/ttyUSB0 ------------------------------- -某些 Linux 版本可能在烧写 ESP32 时会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。 :ref:`可以通过将当前用户添加到拨出组来解决`。 +权限问题 /dev/ttyUSB0 +---------------------------------------------- + +使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 ` Arch Linux 用户 ----------------- +-------------------------------- -在 Arch 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。在 AUR_ 中向下兼容的库文件，可用于本地和 lib32 的配置： +在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。 + +`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置： - https://aur.archlinux.org/packages/ncurses5-compat-libs/ - https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ -在安装这些软件包之前，你可能需要将作者的公钥添加到你的钥匙圈中，上面链接中的“Comments”部分有所叙述。 +在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。 + +或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。 -或者，你也可以使用 crosstool-NG 编译一个链接 ncurses 6 的 gdb。 后续步骤 -========== +================ -要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf` 一节。 +后续开发环境设置，请参考 :ref:`get-started-get-esp-idf` 一节。 + + +相关文档 +================= + +.. toctree:: + :maxdepth: 1 + + linux-setup-scratch .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository - diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst index 1588c80c8..a5003ca94 100644 --- a/docs/zh_CN/get-started/macos-setup-scratch.rst +++ b/docs/zh_CN/get-started/macos-setup-scratch.rst @@ -1,42 +1,56 @@ -********************************** +********************************************************************* 从零开始设置 Mac OS 环境下的工具链 -********************************** -:link_to_translation:`en:[English]` +********************************************************************* -.. note:: - - 安装工具链的标准流程可以通过阅读文档 :doc:`在 MacOS 上安装 ESP32 工具链 ` 来获得， :ref:`工具链的自定义设置 ` 章节会介绍哪些情况下我们必须要重新定义工具链。 +:link_to_translation:`en:[英文]` -安装必要的工具 -===================== +软件包管理器 +====================== + +从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 `。 + +MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。 + + .. _homebrew: https://brew.sh/ + .. _MacPorts: https://www.macports.org/install.php + +请参考 :ref:`工具链自定义设置 ` 章节，查看在哪些情景下需要从头开始设置工具链。 + +准备工作 +============================ - 安装 pip:: sudo easy_install pip -.. note:: +- 安装 pyserial:: - ``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 `。 + pip install --user pyserial + +- 安装 CMake 和 Ninja 编译工具： + + - 若使用 HomeBrew，你可以运行:: + + brew install cmake ninja + + - 若使用 MacPorts，你可以运行:: + + sudo port install cmake ninja 从源代码编译工具链 -================== +======================================== -- 安装依赖: - - - 安装 MacPorts_ 或者 homebrew_ 包管理器。MacPorts 需要安装完整的 XCode 软件，但是 homebrew 只需要安装 XCode 命令行工具即可。 - - .. _homebrew: https://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php +- 相关安装： - 对于 MacPorts:: - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - 对于 homebrew:: - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make -创建大小写敏感的文件系统镜像:: +创建一个文件系统镜像（区分大小写）:: hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" @@ -49,24 +63,24 @@ mkdir -p ~/esp ln -s /Volumes/ctng ~/esp/ctng-volume -进入新创建的工作目录:: +前往新创建的目录：:: cd ~/esp/ctng-volume -下载 ``crosstool-NG`` 然后编译: +下载 ``crosstool-NG``，并开始编译： .. include:: /_build/inc/scratch-build-code.inc -编译工具链:: +编译工具链：:: ./ct-ng xtensa-esp32-elf ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 +编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 -下一步 -====== +后续步骤 +================= 继续设置开发环境，请前往 :ref:`获取 ESP-IDF ` 章节。 diff --git a/docs/zh_CN/get-started/macos-setup.rst b/docs/zh_CN/get-started/macos-setup.rst index 72596ead2..43d8a6684 100644 --- a/docs/zh_CN/get-started/macos-setup.rst +++ b/docs/zh_CN/get-started/macos-setup.rst @@ -1,54 +1,82 @@ -************************************** +****************************************************************** 在 Mac OS 上安装 ESP32 工具链 -************************************** -:link_to_translation:`en:[English]` +****************************************************************** -.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 +:link_to_translation:`en:[英文]` 安装准备 -================ +===================== + +ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 - 安装 pip:: sudo easy_install pip +- 安装 pyserial:: + + pip install --user pyserial + +- 安装 CMake 和 Ninja 编译工具： + + - 若有 HomeBrew_，你可以运行:: + + brew install cmake ninja + + - 若有 MacPorts_，你可以运行:: + + sudo port install cmake ninja + + - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 + +- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。 + .. note:: - ``pip`` 稍后将用于安装 :ref:`必要的 Python 软件包 `。 + 如在任一步骤中出现以下报错信息:: + + ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun`` + + 你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。 安装工具链 -=============== +====================== .. include:: /_build/inc/download-links.inc -Mac OS 版本的 ESP32 工具链可以从以下地址下载： +下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网： |download_link_osx| -下载压缩文件之后，解压到 ``~/esp`` 目录中: +完成下载后，请在 ``~/esp`` 目录下进行解压： .. include:: /_build/inc/unpack-code-osx.inc .. _setup-macos-toolchain-add-it-to-path: -工具链将被解压到 ``~/esp/xtensa-esp32-elf/`` 路径下。 +此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。 -在 ``~/.profile`` 文件中更新 ``PATH`` 环境变量以使用工具链。为了使 ``xtensa-esp32-elf`` 在各种终端会话中都可用，在 ``~/.profile`` 文件中加上以下指令:: +为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：:: - export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH + export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH -或者，您可以为上述命令创建一个别名。这样只有执行以下指令时工具链才能被使用。将下面的指令添加到您的 ``〜/ .profile`` 文件中:: +此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令:: alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" -当需要使用工具链时，在命令行里输入 ``get_esp32``，就可以将工具链添加到 ``PATH`` 中。 +此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。 + +注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。 + +此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确:: + + printenv PATH -下一步 -========== - -前往 :ref:`get-started-get-esp-idf` 继续配置开发环境。 +后续步骤 +================= +前往 :ref:`get-started-get-esp-idf`，完成接下来的开发环境配置。 相关文档 ================= @@ -58,3 +86,8 @@ Mac OS 版本的 ESP32 工具链可以从以下地址下载： macos-setup-scratch +.. _cmake: https://cmake.org/ +.. _ninja: https://ninja-build.org/ +.. _ccache: https://ccache.samba.org/ +.. _homebrew: https://brew.sh/ +.. _MacPorts: https://www.macports.org/install.php diff --git a/docs/zh_CN/get-started/toolchain-setup-scratch.rst b/docs/zh_CN/get-started/toolchain-setup-scratch.rst index 43a8920c1..435fe177b 100644 --- a/docs/zh_CN/get-started/toolchain-setup-scratch.rst +++ b/docs/zh_CN/get-started/toolchain-setup-scratch.rst @@ -1 +1,27 @@ -.. include:: ../../en/get-started/toolchain-setup-scratch.rst \ No newline at end of file +.. _get-started-customized-setup: + +********************************************************* +工具链自定义设置 +********************************************************* + +:link_to_translation:`en:[英文]` + +除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain`）下载二进制工具链外，你还可以自行编译工具链。 + +如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链： + +- 需要定制工具链编译配置 +- 使用其他 GCC 版本（如 4.8.5） +- 需要破解 gcc、newlib 或 libstdc++ +- 有相关兴趣或时间充裕 +- 不信任从网站下载的 bin 文件 + +如需自行编译工具链，请查看以下文档： + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + linux-setup-scratch + macos-setup-scratch + diff --git a/docs/zh_CN/get-started/windows-setup-scratch.rst b/docs/zh_CN/get-started/windows-setup-scratch.rst index 6ca82060e..56f5d7d30 100644 --- a/docs/zh_CN/get-started/windows-setup-scratch.rst +++ b/docs/zh_CN/get-started/windows-setup-scratch.rst @@ -1 +1,92 @@ -.. include:: ../../en/get-started/windows-setup-scratch.rst \ No newline at end of file +****************************************************************** +从零开始设置 Windows 环境下的工具链 +****************************************************************** + +:link_to_translation:`en:[英文]` + +本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 ` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。 + +使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。 + + +.. note:: + 基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。 + +工具 +===== + +cmake +^^^^^ + +下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。 + +当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。 + +Ninja 编译工具 +^^^^^^^^^^^^^^^^^^^^ + +.. note:: + Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。 + +从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 `ninja`_。 + +适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 `_ （或者选择你的路径中已有的目录）。 + + +Python 2.x +^^^^^^^^^^ + +下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。 + +Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。 + +Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令:: + + pip install --user pyserial + +适用于 IDF 的 MConf +^^^^^^^^^^^^^^^^^^^^^^ + +从 `kconfig-frontends 发布页面 `_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。 + +你需将此工具解压到目录，然后 `添加到你的路径 `_。 + +工具链设置 +=============== + +.. include:: /_build/inc/download-links.inc + +下载预编译的 Windows 平台工具链： + +|download_link_win32| + +解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。 + +然后，须将该目录下的子目录 ``bin`` `添加到你的路径 `_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。 + +.. note:: + + 如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。 + + +.. _add-directory-windows-path: + +添加目录到路径 +======================== + +添加任何新目录到你的 Windows Path 环境变量： + +打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。 + +双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;``。 + + +后续步骤 +================ + +要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。 + +.. _ninja: https://ninja-build.org/ +.. _Python: https://www.python.org/downloads/windows/ +.. _MSYS2: https://msys2.github.io/ + diff --git a/docs/zh_CN/get-started/windows-setup-update.rst b/docs/zh_CN/get-started/windows-setup-update.rst new file mode 100644 index 000000000..9d4fa4ff4 --- /dev/null +++ b/docs/zh_CN/get-started/windows-setup-update.rst @@ -0,0 +1,3 @@ +:orphan: + +.. Remove this file when the Chinese translation of getting started guide is updated diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index 3c02077bd..1bbb806fd 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -1,64 +1,60 @@ -*************************************** +********************************************************** Windows 平台工具链的标准设置 -*************************************** -:link_to_translation:`en:[English]` +********************************************************** -.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 +:link_to_translation:`en:[英文]` + +.. note:: + 基于 CMake 的构建系统仅支持 64 位版本 Windows。 引言 ============ -Windows 没有内置的 "make" 环境，因此如果要安装工具链，你需要一个 GNU 兼容环境。我们这里使用 MSYS2_ 来提供该环境。你不需要一直使用这个环境（你可以使用 :doc:`Eclipse ` 或其它前端工具），但是它是在后台运行的。 +ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。 -工具链的设置 -=============== - -快速设置的方法是从 dl.espressif.com 下载集成在一起的工具链和 MSYS2 压缩文件： +在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse ` 或支持 CMake 的图形化工具 IDE。 https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip -将 zip 压缩文件解压到 ``C:\`` (或其它路径，这里假设是 ``C:\``)，它会使用预先准备的环境创建一个 ``msys32`` 目录。 +ESP-IDF 工具安装器 +======================= -检出 -============ +安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下： -运行 ``C:\msys32\mingw32.exe`` 打开一个 MSYS2 的终端窗口。该窗口的环境是一个 bash shell。创建一个 ``esp`` 目录作为开发 ESP32 应用的默认地址。运行指令 :: +https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe - mkdir -p ~/esp - -输入 ``cd ~/esp`` 就进入到新创建的目录。如果没有错误信息出现则表明此步骤已完成。 +安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。 +安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。 -.. figure:: ../../_static/msys2-terminal-window.png - :align: center - :alt: MSYS2 MINGW32 shell window - :figclass: align-center +请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。 - MSYS2 终端窗口 +安装 Git +============== -后续步骤将会使用这个窗口来为 ESP32 设置开发环境。 +ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。 + +如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。 + +使用终端 +================ + +在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符： + +- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。 +- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。 +- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。 后续步骤 ========== -要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf` 一节。 - -更新环境 -======================== - -当 IDF 更新时，有时需要新的工具链，或者将新的需求添加到 Windows MSYS2 环境中。要将旧版本的预编译环境中的数据移动到新版本： - -- 把旧的 MSYS2 环境（即 ``C:\msys32``）移动/重命名为不同的目录（即 ``C:\msys32_old``）。 -- 按照前文所述步骤下载新的预编译环境。 -- 将新的 MSYS2 环境解压缩到 ``C:\msys32`` （或其他位置）。 -- 找到旧的 ``C:\msys32_old\home`` 目录并把它移到 ``C:\msys32``。 -- 如果你不再需要 ``C:\msys32_old`` 可以将它删除。 - -你可以在系统上拥有独立的不同的 MSYS2 环境，前提是在不同的目录中。 +要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。 相关文档 ================= +想要自定义安装流程的高阶用户可参照： + .. toctree:: :maxdepth: 1 @@ -66,4 +62,9 @@ https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611 .. _MSYS2: https://msys2.github.io/ - +.. _cmake: https://cmake.org/download/ +.. _ninja: https://ninja-build.org/ +.. _Python: https://www.python.org/downloads/windows/ +.. _Git for Windows: https://gitforwindows.org/ +.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/ +.. _Github Desktop: https://desktop.github.com/ diff --git a/docs/zh_CN/gnu-make-legacy.rst b/docs/zh_CN/gnu-make-legacy.rst new file mode 100644 index 000000000..c91455590 --- /dev/null +++ b/docs/zh_CN/gnu-make-legacy.rst @@ -0,0 +1,3 @@ +.. note:: Since ESP-IDF V4.0, the default build system is based on CMake. This documentation is for the legacy build system based on GNU Make. Support for this build system may be removed in future major releases. + + diff --git a/docs/zh_CN/hw-reference/get-started-devkitc-v2.rst b/docs/zh_CN/hw-reference/get-started-devkitc-v2.rst index f0ca5c62c..2cd107586 100644 --- a/docs/zh_CN/hw-reference/get-started-devkitc-v2.rst +++ b/docs/zh_CN/hw-reference/get-started-devkitc-v2.rst @@ -9,7 +9,7 @@ ESP32-DevKitC V2 入门指南 准备工作 -------- -* :ref:`ESP32-DevKitC V2 开发板 ` +* :ref:`ESP32-DevKitC V2 开发板 ` * USB A / micro USB B 数据线 * PC（Windows、Linux 或 Mac OS） @@ -27,7 +27,7 @@ ESP32-DevKitC V2 是 `乐鑫 `_ 一款基于 ESP32 的小 ESP32-DevKitC V2 开发板的主要组件、接口及控制方式见下。 -.. _get-started-esp32-devkitc-v2-board-front-cmake: +.. _get-started-esp32-devkitc-v2-board-front: .. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png :align: center @@ -71,9 +71,7 @@ ESP32-DevKitC V2 开发板 ESP32-DevKitC V2 上电前，请首先确认开发板完好无损。 -之后，请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 - -如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 +之后，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 diff --git a/docs/zh_CN/hw-reference/get-started-devkitc.rst b/docs/zh_CN/hw-reference/get-started-devkitc.rst index 5e0f160cf..f75b5f80a 100644 --- a/docs/zh_CN/hw-reference/get-started-devkitc.rst +++ b/docs/zh_CN/hw-reference/get-started-devkitc.rst @@ -9,14 +9,14 @@ ESP32-DevKitC V4 入门指南 准备工作 ----------- -* :ref:`ESP32-DevKitC V4 开发板 ` +* :ref:`ESP32-DevKitC V4 开发板 ` * USB A / micro USB B 数据线 * PC（Windows、Linux 或 Mac OS） 您可以跳过介绍部分，直接前往 `应用程序开发`_ 章节。 -.. _DevKitC-Overview-cmake: +.. _DevKitC-Overview: 概述 ---- @@ -46,7 +46,7 @@ ESP32-DevKitC V4 是 `乐鑫 `_ 一款基于 ESP32 的小 ESP32-DevKitC V4 开发板的主要组件、接口及控制方式见下。 -.. _get-started-esp32-devkitc-board-front-cmake: +.. _get-started-esp32-devkitc-board-front: .. figure:: ../../_static/esp32-devkitc-functional-overview.jpg :align: center @@ -121,10 +121,7 @@ C15（黄色）在 ESP32-DevKitC V4 开发板上的位置 ESP32-DevKitC V4 上电前，请首先确认开发板完好无损。 -之后，请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 - -如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 - +之后，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 开发板尺寸 ------------- @@ -151,4 +148,4 @@ ESP32-DevKitC 开发板尺寸 -- 仰视图 .. toctree:: :hidden: - get-started-devkitc-v2 \ No newline at end of file + get-started-devkitc-v2 diff --git a/docs/zh_CN/hw-reference/get-started-ethernet-kit.rst b/docs/zh_CN/hw-reference/get-started-ethernet-kit.rst index c96d94cee..f11f7862d 100644 --- a/docs/zh_CN/hw-reference/get-started-ethernet-kit.rst +++ b/docs/zh_CN/hw-reference/get-started-ethernet-kit.rst @@ -342,7 +342,7 @@ ESP32-Ethernet-Kit 上电前，请首先确认开发板完好无损。 正式开始开发 ^^^^^^^^^^^^^^^^^^ -现在，请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +现在，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 diff --git a/docs/zh_CN/hw-reference/get-started-pico-kit-v3.rst b/docs/zh_CN/hw-reference/get-started-pico-kit-v3.rst index 99b70fe89..a63129f83 100644 --- a/docs/zh_CN/hw-reference/get-started-pico-kit-v3.rst +++ b/docs/zh_CN/hw-reference/get-started-pico-kit-v3.rst @@ -65,9 +65,7 @@ EN 复位按键。 ESP32-PICO-KIT V3 上电前，请首先确认开发板完好无损。 -之后，请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 - -如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 +之后，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 diff --git a/docs/zh_CN/hw-reference/get-started-pico-kit.rst b/docs/zh_CN/hw-reference/get-started-pico-kit.rst index a07b5b578..10299ea2d 100644 --- a/docs/zh_CN/hw-reference/get-started-pico-kit.rst +++ b/docs/zh_CN/hw-reference/get-started-pico-kit.rst @@ -10,7 +10,7 @@ ESP32-PICO-KIT V4/V4.1 入门指南 准备工作 -------- -* :ref:`ESP32-PICO-KIT 迷你开发板 ` +* :ref:`ESP32-PICO-KIT 迷你开发板 ` * USB 2.0 线（A 型转 Micro-B 型） * PC（Windows、Linux 或 Mac OS） @@ -56,7 +56,7 @@ ESP32-PICO-KIT 开发板的主要组件和连接方式见下。 ESP32-PICO-KIT 开发板的主要组件、接口及控制方式见下。 -.. _get-started-pico-kit-v4-board-front-cmake: +.. _get-started-pico-kit-v4-board-front: .. figure:: ../../_static/esp32-pico-kit-v4.1-f-layout.jpeg :align: center @@ -106,7 +106,7 @@ EN 复位按键。 管脚说明 ---------- -下表介绍了开发板 I/O 管脚的 **名称** 和 **功能**，具体布局请见 `相关文档`_ 中的原理图。请参考 :ref:`get-started-pico-kit-v4-board-front-cmake`。 +下表介绍了开发板 I/O 管脚的 **名称** 和 **功能**，具体布局请见 `相关文档`_ 中的原理图。请参考 :ref:`get-started-pico-kit-v4-board-front`。 Header J2 @@ -115,9 +115,9 @@ Header J2 ====== ================= ====== ====================================================== 编号 名称 类型 功能 ====== ================= ====== ====================================================== -1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`（见说明 1） ` , U2CTS -2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`（见说明 1） ` , U2RTS -3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`（见说明 1） ` , U1CTS +1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`（见说明 1） ` , U2CTS +2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`（见说明 1） ` , U2RTS +3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`（见说明 1） ` , U1CTS 4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN 5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1 6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0 @@ -126,8 +126,8 @@ Header J2 9 IO5 I/O | GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK 10 IO10 I/O | GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD 11 IO9 I/O | GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD -12 RXD0 I/O | GPIO3, U0RXD :ref:`（见说明 3） ` , CLK_OUT2 -13 TXD0 I/O | GPIO1, U0TXD :ref:`（见说明 3） ` , CLK_OUT3, EMAC_RXD2 +12 RXD0 I/O | GPIO3, U0RXD :ref:`（见说明 3） ` , CLK_OUT2 +13 TXD0 I/O | GPIO1, U0TXD :ref:`（见说明 3） ` , CLK_OUT3, EMAC_RXD2 14 IO35 I | ADC1_CH7, RTC_GPIO5 15 IO34 I | ADC1_CH6, RTC_GPIO4 16 IO38 I | GPIO38, ADC1_CH2, RTC_GPIO2 @@ -144,20 +144,20 @@ Header J3 ====== ================= ====== ====================================================== No. Name Type Function ====== ================= ====== ====================================================== -1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`（见说明 1） ` , U2RXD, EMAC_CLK_OUT -2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`（见说明 1） ` , U2TXD, EMAC_CLK_OUT_180 -3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`（见说明 1） ` , U1RTS +1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`（见说明 1） ` , U2RXD, EMAC_CLK_OUT +2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`（见说明 1） ` , U2TXD, EMAC_CLK_OUT_180 +3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`（见说明 1） ` , U1RTS 4 SENSOR_VP (FSVP) I | GPIO36, ADC1_CH0, RTC_GPIO0 5 SENSOR_VN (FSVN) I | GPIO39, ADC1_CH3, RTC_GPIO3 6 IO25 I/O | GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0 7 IO26 I/O | GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1 -8 IO32 I/O | 32K_XP :ref:`（见说明 2a） ` , ADC1_CH4, TOUCH9, RTC_GPIO9 -9 IO33 I/O | 32K_XN :ref:`（见说明 2b） ` , ADC1_CH5, TOUCH8, RTC_GPIO8 +8 IO32 I/O | 32K_XP :ref:`（见说明 2a） ` , ADC1_CH4, TOUCH9, RTC_GPIO9 +9 IO33 I/O | 32K_XN :ref:`（见说明 2b） ` , ADC1_CH5, TOUCH8, RTC_GPIO8 10 IO27 I/O | GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17 | EMAC_RX_DV 11 IO14 I/O | ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK, | HS2_CLK, SD_CLK, EMAC_TXD2 -12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`（见说明 4） ` , HSPIQ, +12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`（见说明 4） ` , HSPIQ, | HS2_DATA2, SD_DATA2, EMAC_TXD3 13 IO13 I/O | ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID, | HS2_DATA3, SD_DATA3, EMAC_RX_ER @@ -175,7 +175,7 @@ No. Name Type Function ====== ================= ====== ====================================================== -.. _get-started-pico-kit-v4-pin-notes-cmake: +.. _get-started-pico-kit-v4-pin-notes: 有关上表的说明： @@ -190,9 +190,7 @@ No. Name Type Function ESP32-PICO-KIT 上电前，请首先确认开发板完好无损。 -之后，请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 - -如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 +之后，请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 开发板尺寸 diff --git a/docs/zh_CN/hw-reference/get-started-wrover-kit-v2.rst b/docs/zh_CN/hw-reference/get-started-wrover-kit-v2.rst index 1dcce65b9..c93c6f783 100644 --- a/docs/zh_CN/hw-reference/get-started-wrover-kit-v2.rst +++ b/docs/zh_CN/hw-reference/get-started-wrover-kit-v2.rst @@ -52,7 +52,7 @@ ESP-WROVER-KIT 开发板的主要组件和连接方式如下图所示。 ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 -.. _get-started-esp-wrover-kit-v2-board-front-cmake: +.. _get-started-esp-wrover-kit-v2-board-front: .. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png :align: center @@ -61,7 +61,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 ESP-WROVER-KIT 开发板布局 -- 俯视图 -.. _get-started-esp-wrover-kit-v2-board-back-cmake: +.. _get-started-esp-wrover-kit-v2-board-back: .. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png :align: center @@ -113,11 +113,11 @@ I/O 板上模组的所有管脚均已引出至开发板的排 MicroSD 卡槽 MicroSD 卡槽，可扩充存储空间：当 ESP32 进入下载模式时，GPIO2 不可处于高电平。然而，为了使能 MicroSD 卡功能，需为 GPIO2 增加一个上拉电阻。默认情况下，GPIO2 和上拉电阻 R153 处于断开状态。为了使能 MicroSD 卡，请按照 `设置选项`_ 章节的要求，连接 JP1 连接器。 -LCD 显示屏 支持贴装一款 3.2” 的 SPI（标准四线串行外设接口）LCD 显示器，请见 :ref:`get-started-esp-wrover-kit-v2-board-back-cmake`。 +LCD 显示屏 支持贴装一款 3.2” 的 SPI（标准四线串行外设接口）LCD 显示器，请见 :ref:`get-started-esp-wrover-kit-v2-board-back`。 ==================== ====================================================================================================================================================================================================================================================================================================================================== -.. _get-started-esp-wrover-kit-v2-setup-options-cmake: +.. _get-started-esp-wrover-kit-v2-setup-options: 设置选项 ------------- @@ -137,7 +137,7 @@ JP14 |jp14| 使能 RTS/CTS 串口流控 ======= ================ ===================================================================================== -.. _get-started-esp-wrover-kit-v2-start-development-cmake: +.. _get-started-esp-wrover-kit-v2-start-development: 应用程序开发 ----------------------------- @@ -167,9 +167,7 @@ USB 供电 使能 UART 通信 正式开始开发 ^^^^^^^^^^^^^^^^^^ -请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 - -如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 +请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 @@ -191,4 +189,4 @@ USB 供电 使能 UART 通信 .. |jp11-tx-rx| image:: ../../_static/wrover-jp11-tx-rx.png .. |jp14| image:: ../../_static/wrover-jp14.png -.. _ESP-WROVER-KIT V2 原理图: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf \ No newline at end of file +.. _ESP-WROVER-KIT V2 原理图: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf diff --git a/docs/zh_CN/hw-reference/get-started-wrover-kit-v3.rst b/docs/zh_CN/hw-reference/get-started-wrover-kit-v3.rst index 57a72931b..0bf134939 100644 --- a/docs/zh_CN/hw-reference/get-started-wrover-kit-v3.rst +++ b/docs/zh_CN/hw-reference/get-started-wrover-kit-v3.rst @@ -8,7 +8,7 @@ ESP-WROVER-KIT V3 入门指南 准备工作 ------------- -* :ref:`ESP-WROVER-KIT V3 开发板 ` +* :ref:`ESP-WROVER-KIT V3 开发板 ` * USB 数据线（A 转 Micro-B） * PC（Windows、Linux 或 macOS） @@ -52,7 +52,7 @@ ESP-WROVER-KIT 开发板的主要组件和连接方式如下图所示。 ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 -.. _get-started-esp-wrover-kit-v3-board-front-cmake: +.. _get-started-esp-wrover-kit-v3-board-front: .. figure:: ../../_static/esp-wrover-kit-v3-layout-front.jpg :align: center @@ -61,7 +61,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 ESP-WROVER-KIT 开发板布局 -- 俯视图 -.. _get-started-esp-wrover-kit-v3-board-back-cmake: +.. _get-started-esp-wrover-kit-v3-board-back: .. figure:: ../../_static/esp-wrover-kit-v3-layout-back.jpg :align: center @@ -115,11 +115,11 @@ I/O 板上模组的所有管脚均已引出至开发板的 MicroSD 卡槽 适用于需要扩充数据存储空间或进行备份的应用开发场景。 -LCD 显示屏 支持贴装一款 3.2” 的 SPI（标准四线串行外设接口）LCD 显示器，请见 :ref:`get-started-esp-wrover-kit-v3-board-back-cmake`。 +LCD 显示屏 支持贴装一款 3.2” 的 SPI（标准四线串行外设接口）LCD 显示器，请见 :ref:`get-started-esp-wrover-kit-v3-board-back`。 ==================== ====================================================================================================================================================================================================================================================================================================================================== -.. _get-started-esp-wrover-kit-v3-setup-options-cmake: +.. _get-started-esp-wrover-kit-v3-setup-options: 设置选项 ------------- @@ -175,17 +175,17 @@ JTAG，MicroSD IO15 5V 说明： -* NC/XTAL - :ref:`32.768 kHz Oscillator ` -* JTAG - :ref:`JTAG / JP8 ` +* NC/XTAL - :ref:`32.768 kHz Oscillator ` +* JTAG - :ref:`JTAG / JP8 ` * Boot - Boot 按键 / SW2 -* 摄像头 - :ref:`摄像头 / JP4 ` -* LED - :ref:`RGB LED ` -* MicroSD - :ref:`MicroSD Card / J4 ` -* LCD - :ref:`LCD / U5 ` +* 摄像头 - :ref:`摄像头 / JP4 ` +* LED - :ref:`RGB LED ` +* MicroSD - :ref:`MicroSD Card / J4 ` +* LCD - :ref:`LCD / U5 ` * PSRAM - 仅适用于选贴 ESP32-WROVER 的情况。 -.. _get-started-esp-wrover-kit-v3-xtal-cmake: +.. _get-started-esp-wrover-kit-v3-xtal: 32.768 kHz 晶振 ^^^^^^^^^^^^^^^^^^^^^ @@ -202,7 +202,7 @@ JTAG，MicroSD IO15 5V 默认情况下，管脚 GPIO32 和 GPIO33 已连接至晶振。因此，为了保证信号的完整性，这两个管脚并未连接至 JP1 I/O 连接器。用户可通过将 R11/R23 处的 0 欧电阻移至 R12/R24 处，以将 GP1O32 和 GPIO33 的连接从晶振移至 JP1。 -.. _get-started-esp-wrover-kit-v3-spi-flash-header-cmake: +.. _get-started-esp-wrover-kit-v3-spi-flash-header: SPI Flash / JP13 ^^^^^^^^^^^^^^^^ @@ -224,7 +224,7 @@ SPI Flash / JP13 -.. _get-started-esp-wrover-kit-v3-jtag-header-cmake: +.. _get-started-esp-wrover-kit-v3-jtag-header: JTAG / JP8 ^^^^^^^^^^ @@ -240,7 +240,7 @@ JTAG / JP8 ==== ============== ============= -.. _get-started-esp-wrover-kit-v3-camera-header-cmake: +.. _get-started-esp-wrover-kit-v3-camera-header: 摄像头 / JP4 ^^^^^^^^^^^^ @@ -271,7 +271,7 @@ JTAG / JP8 * D0 到 D7 为摄像头的数据总线 -.. _get-started-esp-wrover-kit-v3-rgb-led-connections-cmake: +.. _get-started-esp-wrover-kit-v3-rgb-led-connections: RGB LED ^^^^^^^ @@ -285,7 +285,7 @@ RGB LED ==== ========== ========= -.. _get-started-esp-wrover-kit-v3-microsd-card-slot-cmake: +.. _get-started-esp-wrover-kit-v3-microsd-card-slot: MicroSD 卡 ^^^^^^^^^^^^ @@ -303,7 +303,7 @@ MicroSD 卡 ==== ============== =============== -.. _get-started-esp-wrover-kit-v3-lcd-connector-cmake: +.. _get-started-esp-wrover-kit-v3-lcd-connector: LCD / U5 ^^^^^^^^ @@ -321,7 +321,7 @@ LCD / U5 ==== ============== =============== -.. _get-started-esp-wrover-kit-v3-start-development-cmake: +.. _get-started-esp-wrover-kit-v3-start-development: 应用程序开发 ----------------------------- @@ -351,9 +351,7 @@ USB 供电 使能 UART 通信 正式开始开发 ^^^^^^^^^^^^^^^^^^ -请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 - -如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 +请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 相关文档 diff --git a/docs/zh_CN/hw-reference/get-started-wrover-kit.rst b/docs/zh_CN/hw-reference/get-started-wrover-kit.rst index b08547841..98ffae468 100644 --- a/docs/zh_CN/hw-reference/get-started-wrover-kit.rst +++ b/docs/zh_CN/hw-reference/get-started-wrover-kit.rst @@ -8,7 +8,7 @@ ESP-WROVER-KIT V4.1 入门指南 准备工作 ------------- -* :ref:`ESP-WROVER-KIT V4.1 开发板 ` +* :ref:`ESP-WROVER-KIT V4.1 开发板 ` * USB 数据线（A 转 Micro-B） * PC（Windows、Linux 或 macOS） @@ -53,7 +53,7 @@ ESP-WROVER-KIT 开发板的主要组件和连接方式如下图所示。 ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 -.. _get-started-esp-wrover-kit-v4.1-board-front-cmake: +.. _get-started-esp-wrover-kit-v4.1-board-front: .. figure:: ../../_static/esp-wrover-kit-v4.1-layout-front.png :align: center @@ -62,7 +62,7 @@ ESP-WROVER-KIT 开发板的主要组件、接口及控制方式见下。 ESP-WROVER-KIT 开发板布局 -- 俯视图 -.. _get-started-esp-wrover-kit-v4.1-board-back-cmake: +.. _get-started-esp-wrover-kit-v4.1-board-back: .. figure:: ../../_static/esp-wrover-kit-v4.1-layout-back.png :align: center @@ -120,11 +120,11 @@ I/O 连接器 板上模组的所有管脚均已引出至开发板 MicroSD 卡槽 适用于需要扩充数据存储空间或进行备份的应用开发场景。 -LCD 显示屏 支持贴装一款 3.2” 的 SPI（标准四线串行外设接口）LCD 显示器，请见 :ref:`get-started-esp-wrover-kit-v4.1-board-back-cmake`。 +LCD 显示屏 支持贴装一款 3.2” 的 SPI（标准四线串行外设接口）LCD 显示器，请见 :ref:`get-started-esp-wrover-kit-v4.1-board-back`。 ==================== ====================================================================================================================================================================================================================================================================================================================================== -.. _get-started-esp-wrover-kit-v4.1-setup-options-cmake: +.. _get-started-esp-wrover-kit-v4.1-setup-options: 设置选项 ------------- @@ -180,17 +180,17 @@ JTAG，MicroSD IO15 5V 说明： -* NC/XTAL - :ref:`32.768 kHz 晶振 ` -* JTAG - :ref:`JTAG / JP8 ` +* NC/XTAL - :ref:`32.768 kHz 晶振 ` +* JTAG - :ref:`JTAG / JP8 ` * Boot - Boot 按键 / SW2 -* 摄像头 - :ref:`摄像头 / JP4 ` -* LED - :ref:`RGB LED ` -* MicroSD - :ref:`MicroSD Card / J4 ` -* LCD - :ref:`LCD / U5 ` +* 摄像头 - :ref:`摄像头 / JP4 ` +* LED - :ref:`RGB LED ` +* MicroSD - :ref:`MicroSD Card / J4 ` +* LCD - :ref:`LCD / U5 ` * PSRAM - ESP32-WROVER-B 的 PSRAM -.. _get-started-esp-wrover-kit-v4.1-xtal-cmake: +.. _get-started-esp-wrover-kit-v4.1-xtal: 32.768 kHz 晶振 ^^^^^^^^^^^^^^^^^^^^^ @@ -207,7 +207,7 @@ JTAG，MicroSD IO15 5V 默认情况下，管脚 GPIO32 和 GPIO33 已连接至晶振。因此，为了保证信号的完整性，这两个管脚并未连接至 JP1 I/O 连接器。用户可通过将 R11/R23 处的 0 欧电阻移至 R12/R24 处，以将 GP1O32 和 GPIO33 的连接从晶振移至 JP1。 -.. _get-started-esp-wrover-kit-v4.1-spi-flash-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-spi-flash-header: SPI Flash / JP2 ^^^^^^^^^^^^^^^ @@ -229,7 +229,7 @@ SPI Flash / JP2 -.. _get-started-esp-wrover-kit-v4.1-jtag-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-jtag-header: JTAG / JP2 ^^^^^^^^^^ @@ -245,7 +245,7 @@ JTAG / JP2 ==== ============== ============= -.. _get-started-esp-wrover-kit-v4.1-camera-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-camera-header: 摄像头 / JP4 ^^^^^^^^^^^^ @@ -276,7 +276,7 @@ JTAG / JP2 * D0 到 D7 为摄像头的数据总线 -.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections-cmake: +.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections: RGB LED ^^^^^^^ @@ -290,7 +290,7 @@ RGB LED ==== ========== ========= -.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot-cmake: +.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot: MicroSD 卡 ^^^^^^^^^^^^ @@ -308,7 +308,7 @@ MicroSD 卡 ==== ============== =============== -.. _get-started-esp-wrover-kit-v4.1-lcd-connector-cmake: +.. _get-started-esp-wrover-kit-v4.1-lcd-connector: LCD / U5 ^^^^^^^^ @@ -326,7 +326,7 @@ LCD / U5 ==== ============== =============== -.. _get-started-esp-wrover-kit-start-development-cmake: +.. _get-started-esp-wrover-kit-start-development: 应用程序开发 ----------------------------- @@ -356,7 +356,7 @@ USB 供电 使能 UART 通信 正式开始开发 ^^^^^^^^^^^^^^^^^^ -请前往 :doc:`../get-started-cmake/index` 中的 :ref:`get-started-step-by-step-cmake` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 +请前往 :doc:`../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 如需使用较早 GNU Make 编译系统，则请参考 :ref:`get-started-step-by-step` 章节。 @@ -382,4 +382,4 @@ USB 供电 使能 UART 通信 :hidden: get-started-wrover-kit-v3.rst - get-started-wrover-kit-v2.rst \ No newline at end of file + get-started-wrover-kit-v2.rst diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst index 438e8dd55..dfdd2da23 100644 --- a/docs/zh_CN/index.rst +++ b/docs/zh_CN/index.rst @@ -40,7 +40,6 @@ ESP-IDF 编程指南 :hidden: 快速入门 - 快速入门 (CMake 预览版本) API 参考 H/W 参考 API 指南 diff --git a/examples/README.md b/examples/README.md index af04945bf..e5b4a0c4f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -25,9 +25,9 @@ Building an example is the same as building any other project: * Follow the Getting Started instructions which include building the "Hello World" example. * Change into the directory of the new example you'd like to build. -* `make menuconfig` to configure the example. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use). +* Run `idf.py menuconfig` to open the project configuration menu. Most examples have a project-specific "Example Configuration" section here (for example, to set the WiFi SSID & password to use). * `make` to build the example. -* Follow the printed instructions to flash, or run `make flash`. +* Follow the printed instructions to flash, or run `idf.py flash`. # Copying Examples diff --git a/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md b/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md index df698cf90..04b09711b 100644 --- a/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md +++ b/examples/bluetooth/bluedroid/ble/ble_ibeacon/README.md @@ -21,10 +21,10 @@ Which demo will be run depends on the menuconfig, developers can set it in `iBea The default mode is iBeacon Sender. ### Menuconfig -Before compiling the demo，developers also need to configure the menuconfig: +Before compiling the demo，developers also need to configure the project: ```c -make menuconfig +idf.py menuconfig ``` And then enter `Component config->Bluetooth->Bluedroid Enable` @@ -49,7 +49,7 @@ switch (scan_result->scan_rst.search_evt) { Build each project and flash it to the board, then run monitor tool to view serial output: ``` -make -j4 flash monitor +idp.py -p PORT flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) @@ -110,4 +110,4 @@ I (329203) IBEACON_DEMO: ----------iBeacon Found---------- I (329203) IBEACON_DEMO: Device address:: 30 ae a4 00 42 82 I (329203) IBEACON_DEMO: Proximity UUID:: fd a5 06 93 a4 e2 4f b1 af cf c6 eb 07 64 78 25 ``` - \ No newline at end of file + diff --git a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md index 48b6b475b..d38c4ca5e 100644 --- a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md +++ b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_client/README.md @@ -4,10 +4,10 @@ ESP-IDF BLE throughput GATT CLIENT demo This is the demo used to test the BLE throughput, this demo should used with throughput server demo together. The throughput of BLE can up to 720-767 Kbps between to ESP32 board. Note: -1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (make menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log. +1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (idf.py menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log. 2. We can only test notify or write throughput at the same time, this demo default to test the notify throughput, if want to test the write throughput, -please set: make menuconfig --> Component config --> Example 'GATT CLIENT THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option +please set: idf.py menuconfig --> Component config --> Example 'GATT CLIENT THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option 3. This demo only test unidirectional throughput, if you want to test the bidirectional throughput please change the demo by yourself. -4. Should change the CPU frequency to 160MHZ or 240MHz in the make menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (240 MHz or 160 MHz). -5. Should change the bluetooth controller and Bluedroid run in different Core in the make menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)). +4. Should change the CPU frequency to 160MHZ or 240MHz in the idf.py menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (240 MHz or 160 MHz). +5. Should change the bluetooth controller and Bluedroid run in different Core in the idf.py menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)). 6. In order to maximize throughput, please test in a clean environment without many BLE devices working and both test devices are ESP32. diff --git a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md index 47c86410d..1dc21211c 100644 --- a/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md +++ b/examples/bluetooth/bluedroid/ble/ble_throughput/throughput_server/README.md @@ -4,11 +4,11 @@ ESP-IDF BLE throughput GATT SERVER demo This is the demo used to test the BLE throughput, this demo should used with throughput client demo together. The throughput of BLE can up to 720-767 Kbps between to ESP32 board. Note: -1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (make menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log; +1. In order to maximize throughput, we need to set the uart print baud rate at 921600 or more (idf.py menuconfig --> Component config --> ESP32-specific --> UART console baud rate --> 921600(or 1500000)) and don't print too much log; 2. We can only test notify or write throughput at the same time, this demo default to test the notify throughput, if want to test the write throughput, -please set: make menuconfig --> Component config --> Example 'GATT SERVER THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option +please set: idf.py menuconfig --> Component config --> Example 'GATT SERVER THROUGHPUT' Config ---> then select the 'test the gattc write throughput' option 3. This demo only test unidirectional throughput, if you want to test the bidirectional throughput please change the demo by yourself. -4. Should change the CPU frequency to 160MHz or 240MHz in the make menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (160MHz or 240 MHz) -5. Should change the bluetooth controller and Bluedroid run in different Core in the make menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)) +4. Should change the CPU frequency to 160MHz or 240MHz in the idf.py menuconfig --> Component config ---> ESP32-specific ---> CPU frequency (160MHz or 240 MHz) +5. Should change the bluetooth controller and Bluedroid run in different Core in the idf.py menuconfig --> Component config ---> Bluetooth ---> The cpu core which bluetooth controller run (Core 0 (PRO CPU)) & Bluedroid Enable ---> The cpu core which Bluedroid run (Core 1 (APP CPU)) 6. In order to maximize throughput, please test in a clean environment without many BLE devices working and both test devices are ESP32. diff --git a/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md b/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md index 9a3c5d611..7d0889ecc 100644 --- a/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md +++ b/examples/bluetooth/bluedroid/classic_bt/a2dp_sink/README.md @@ -28,11 +28,9 @@ If the internal DAC is selected, analog audio will be available on GPIO25 and GP ### Configure the project ``` -make menuconfig +idf.py menuconfig ``` -* Set serial port under Serial Flasher Options. - * Set the use of external I2S codec or internal DAC for audio output, and configure the output PINs under A2DP Example Configuration * Enable Classic Bluetooth and A2DP under Component config --> Bluetooth --> Bluedroid Enable @@ -42,7 +40,7 @@ make menuconfig Build the project and flash it to the board, then run monitor tool to view serial output. ``` -make -j4 flash monitor +idf.py flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) @@ -72,4 +70,4 @@ Also, the sound will be heard if a loudspeaker is connected and possible externa ## Troubleshooting * For current stage, the supported audio codec in ESP32 A2DP is SBC. SBC data stream is transmitted to A2DP sink and then decoded into PCM samples as output. The PCM data format is normally of 44.1kHz sampling rate, two-channel 16-bit sample stream. Other decoder configurations in ESP32 A2DP sink is supported but need additional modifications of protocol stack settings. -* As a usage limitation, ESP32 A2DP sink can support at most one connection with remote A2DP source devices. Also, A2DP sink cannot be used together with A2DP source at the same time, but can be used with other profiles such as SPP and HFP. \ No newline at end of file +* As a usage limitation, ESP32 A2DP sink can support at most one connection with remote A2DP source devices. Also, A2DP sink cannot be used together with A2DP source at the same time, but can be used with other profiles such as SPP and HFP. diff --git a/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md b/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md index 4e9586ce9..05e0594db 100644 --- a/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md +++ b/examples/bluetooth/bluedroid/classic_bt/a2dp_source/README.md @@ -14,11 +14,9 @@ This example is able to run on any commonly available ESP32 development board. A ### Configure the project ``` -make menuconfig +idf.py menuconfig ``` -* Set serial port under Serial Flasher Options. - * Enable Classic Bluetooth and A2DP under Component config --> Bluetooth --> Bluedroid Enable ### Build and Flash @@ -26,7 +24,7 @@ make menuconfig Build the project and flash it to the board, then run monitor tool to view serial output. ``` -make -j4 flash monitor +idf.py -p PORT flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst index 29db5e73c..d5c857344 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_discovery/README.rst @@ -6,7 +6,7 @@ Demo of Classic Bluetooth Device and Service Discovery This is the demo for user to use ESP_APIs to perform inquiry to search for a target device and then performs service search via SDP. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and do not choose "Release DRAM from Classic BT controller" 4. choose your options. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst index b0a865e41..d33e35367 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_acceptor/README.rst @@ -6,11 +6,11 @@ Demo of SPP acceptor role This is the demo for user to use ESP_APIs to create a SPP acceptor. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. Then set SPP_SHOW_MODE as SPP_SHOW_DATA or SPP_SHOW_SPEED in code(should be same with bt_spp_initator). -After the program started, bt_spp_initator will connect it and send data. \ No newline at end of file +After the program started, bt_spp_initator will connect it and send data. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst index 4d298e18f..07bf513a1 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_initiator/README.rst @@ -6,11 +6,11 @@ Demo of SPP initator role This is the demo for user to use ESP_APIs to create a SPP initator. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. Then set SPP_SHOW_MODE as SPP_SHOW_DATA or SPP_SHOW_SPEED in code(should be same with bt_spp_acceptor). -After the program started, It will connect to bt_spp_acceptor and send data. \ No newline at end of file +After the program started, It will connect to bt_spp_acceptor and send data. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst index 76571c45e..b45593eb6 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_acceptor/README.rst @@ -6,9 +6,9 @@ Demo of SPP acceptor role This is the demo for user to use ESP_APIs to create a SPP acceptor. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. -After the program started, bt_spp_vfs_initator will connect it and send data. \ No newline at end of file +After the program started, bt_spp_vfs_initator will connect it and send data. diff --git a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst index efb2513d9..38d9804b9 100644 --- a/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst +++ b/examples/bluetooth/bluedroid/classic_bt/bt_spp_vfs_initiator/README.rst @@ -6,9 +6,9 @@ Demo of SPP initator role This is the demo for user to use ESP_APIs to create a SPP initator. Options choose step: - 1. make menuconfig. + 1. idf.py menuconfig. 2. enter menuconfig "Component config", choose "Bluetooth" 3. enter menu Bluetooth, choose "Classic Bluetooth" and "SPP Profile" 4. choose your options. -After the program started, It will connect to bt_spp_vfs_acceptor and send data. \ No newline at end of file +After the program started, It will connect to bt_spp_vfs_acceptor and send data. diff --git a/examples/build_system/cmake/idf_as_lib/README.md b/examples/build_system/cmake/idf_as_lib/README.md index eda7ac0b4..4ba61e0bd 100644 --- a/examples/build_system/cmake/idf_as_lib/README.md +++ b/examples/build_system/cmake/idf_as_lib/README.md @@ -67,4 +67,4 @@ or --- -There is a discussion on using ESP-IDF in custom CMake projects in the programming guide under `API Guides` -> `Build System (CMake)` -> `Using ESP-IDF in Custom CMake Projects` +There is a discussion on using ESP-IDF in custom CMake projects in the programming guide under `API Guides` -> `Build System` -> `Using ESP-IDF in Custom CMake Projects` diff --git a/examples/build_system/cmake/import_lib/README.md b/examples/build_system/cmake/import_lib/README.md index e24090a87..c6071c8db 100644 --- a/examples/build_system/cmake/import_lib/README.md +++ b/examples/build_system/cmake/import_lib/README.md @@ -33,4 +33,4 @@ I (677) example: Example end ``` --- -There is a discussion on importing third-party CMake libraries in the programming guide under `API Guides` -> `Build System (CMake)` -> `Using Third-Party CMake Projects with Components` +There is a discussion on importing third-party CMake libraries in the programming guide under `API Guides` -> `Build System` -> `Using Third-Party CMake Projects with Components` diff --git a/examples/ethernet/eth2ap/README.md b/examples/ethernet/eth2ap/README.md index e2b3e0321..16a43d6d3 100644 --- a/examples/ethernet/eth2ap/README.md +++ b/examples/ethernet/eth2ap/README.md @@ -20,7 +20,7 @@ To run this example, it's recommended that you have an official ESP32 Ethernet d ### Project configuration in menuconfig -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you' are using CMake based build system. +Open the project configuration menu (`idf.py menuconfig`). 1. In the `Example Configuration` menu: * Set the SSID and password for Wi-Fi ap interface under `Wi-Fi SSID` and `Wi-Fi Password`. @@ -59,7 +59,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -To build and flash the example, enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +To build and flash the example, enter `idf.py -p PORT flash monitor`. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/get-started/blink/main/blink.c b/examples/get-started/blink/main/blink.c index 20a0b94eb..9c58645f9 100644 --- a/examples/get-started/blink/main/blink.c +++ b/examples/get-started/blink/main/blink.c @@ -12,7 +12,7 @@ #include "driver/gpio.h" #include "sdkconfig.h" -/* Can run 'make menuconfig' to choose the GPIO to blink, +/* Can use project configuration menu (idf.py menuconfig) to choose the GPIO to blink, or you can edit the following line and set a number here. */ #define BLINK_GPIO CONFIG_BLINK_GPIO diff --git a/examples/mesh/internal_communication/README.md b/examples/mesh/internal_communication/README.md index 4131bef5a..3c97dc427 100644 --- a/examples/mesh/internal_communication/README.md +++ b/examples/mesh/internal_communication/README.md @@ -16,7 +16,7 @@ Features Demonstrated - other nodes receive -Run `make menuconfig` to configure the mesh network channel, router SSID, router password and mesh softAP settings. +Open project configuration menu (`idf.py menuconfig`) to configure the mesh network channel, router SSID, router password and mesh softAP settings. When the mesh network is established and if you happen to run this example on ESP-WROVER-KIT boards, the RGB light indicator will show you on which layer devices are. The pink reprents root; the yellow reprents layer 2; the red reprents layer 3; the blue reprents layer 4; the green reprents layer 5; the white reprents layer greater than 5. diff --git a/examples/mesh/manual_networking/README.md b/examples/mesh/manual_networking/README.md index 8615dbd6d..9b3ecd58c 100644 --- a/examples/mesh/manual_networking/README.md +++ b/examples/mesh/manual_networking/README.md @@ -7,7 +7,7 @@ This example demonstrates how to scan a list of parent candidates, choose an app If no parent is found through this scan, enable the self-organized function to let the ESP-MESH handle it by itself. -Run `make menuconfig` to configure the mesh network channel, router SSID, router password and mesh softAP settings. +Open project configuration menu (`idf.py menuconfig`) to configure the mesh network channel, router SSID, router password and mesh softAP settings. When the mesh network is established and if you happen to run this example on ESP-WROVER-KIT boards, the RGB light indicator will show you on which layer devices are. The pink reprents root; the yellow reprents layer 2; the red reprents layer 3; the blue reprents layer 4; the green reprents layer 5; the white reprents layer greater than 5. diff --git a/examples/peripherals/adc/README.md b/examples/peripherals/adc/README.md index 657f01a1b..47f58c94b 100644 --- a/examples/peripherals/adc/README.md +++ b/examples/peripherals/adc/README.md @@ -48,7 +48,7 @@ Raw: 18 Voltage: 79mV * program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/adc2/README.md b/examples/peripherals/adc2/README.md index 1d7ba206a..32b94f68e 100644 --- a/examples/peripherals/adc2/README.md +++ b/examples/peripherals/adc2/README.md @@ -59,7 +59,7 @@ start conversion. * program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/i2c/i2c_self_test/README.md b/examples/peripherals/i2c/i2c_self_test/README.md index 499b35e3c..66f64c2ff 100644 --- a/examples/peripherals/i2c/i2c_self_test/README.md +++ b/examples/peripherals/i2c/i2c_self_test/README.md @@ -43,7 +43,7 @@ To run this example, you should have one ESP32 dev board (e.g. ESP32-WROVER Kit) ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - In the `I2C Master` submenu, you can set the pin number of SDA/SCL according to your board. Also you can modify the I2C port number and freauency of the master. - In the `I2C Slave` submenu, you can set the pin number of SDA/SCL according to your board. Also you can modify the I2C port number and address of the slave. @@ -52,7 +52,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you' are using CMake based build system. +Enter `idf.py -p PORT flash monitor` to build, flash and monitor the project. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/peripherals/i2c/i2c_tools/README.md b/examples/peripherals/i2c/i2c_tools/README.md index ca150d838..40d6a2b69 100644 --- a/examples/peripherals/i2c/i2c_tools/README.md +++ b/examples/peripherals/i2c/i2c_tools/README.md @@ -33,7 +33,7 @@ To run this example, you should have one ESP32 dev board (e.g. ESP32-WROVER Kit) ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - You can choose whether or not to save command history into flash in `Store command history in flash` option. - You can set the maximum number of command line arguments under `Maximum number of command line arguments` option. @@ -41,7 +41,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/peripherals/i2s/README.md b/examples/peripherals/i2s/README.md index 8f16374f1..a02f3e5e6 100644 --- a/examples/peripherals/i2s/README.md +++ b/examples/peripherals/i2s/README.md @@ -61,7 +61,7 @@ If you have a logic analyzer, you can use a logic analyzer to grab online data. * Program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/i2s_adc_dac/README.md b/examples/peripherals/i2s_adc_dac/README.md index 2d3b05bd9..7d43ef845 100644 --- a/examples/peripherals/i2s_adc_dac/README.md +++ b/examples/peripherals/i2s_adc_dac/README.md @@ -85,7 +85,7 @@ I2S: PLL_D2: Req RATE: 16000, real rate: 1004.000, BITS: 16, CLKM: 83, BCK: 60, * Program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/ledc/README.md b/examples/peripherals/ledc/README.md index dc8a25c2a..c66fa19dd 100644 --- a/examples/peripherals/ledc/README.md +++ b/examples/peripherals/ledc/README.md @@ -63,7 +63,7 @@ you can also see the following output log on the serial monitor: * Programming fail - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/pcnt/README.md b/examples/peripherals/pcnt/README.md index 4ab5395eb..6e0beb6c0 100644 --- a/examples/peripherals/pcnt/README.md +++ b/examples/peripherals/pcnt/README.md @@ -68,7 +68,7 @@ Current counter value :-1 * program upload failure - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there are any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there are any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/rmt_nec_tx_rx/README.md b/examples/peripherals/rmt_nec_tx_rx/README.md index 85f861fdb..073859111 100644 --- a/examples/peripherals/rmt_nec_tx_rx/README.md +++ b/examples/peripherals/rmt_nec_tx_rx/README.md @@ -74,7 +74,7 @@ NEC: RMT RCV --- addr: 0xda25 cmd: 0xeb14 * Programming fail - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there is any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there is any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/rmt_tx/README.md b/examples/peripherals/rmt_tx/README.md index 3b1cf4a43..6b7f1ff17 100644 --- a/examples/peripherals/rmt_tx/README.md +++ b/examples/peripherals/rmt_tx/README.md @@ -61,7 +61,7 @@ RMT Tx: Sample transmission complete * Programming fail - * Hardware connection is not correct: run `make monitor`, and reboot your board to see if there is any output logs. + * Hardware connection is not correct: run `idf.py monitor`, and reboot your board to see if there is any output logs. * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. For any technical queries, please open an [issue] (https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon. diff --git a/examples/peripherals/uart/nmea0183_parser/README.md b/examples/peripherals/uart/nmea0183_parser/README.md index 6a9ce7859..105c6a626 100644 --- a/examples/peripherals/uart/nmea0183_parser/README.md +++ b/examples/peripherals/uart/nmea0183_parser/README.md @@ -39,7 +39,7 @@ To run this example, you need an ESP32 dev board (e.g. ESP32-WROVER Kit) or ESP3 ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - Set the size of ring buffer used by uart driver in `NMEA Parser Ring Buffer Size` option. - Set the stack size of the NMEA Parser task in `NMEA Parser Task Stack Size` option. @@ -48,7 +48,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/protocols/README.md b/examples/protocols/README.md index 0ab0a7628..3e8570622 100644 --- a/examples/protocols/README.md +++ b/examples/protocols/README.md @@ -14,7 +14,7 @@ The simple `example_connect()` function does not handle timeouts, does not grace ### Configuring the Example -To configure the example to use Wi-Fi or Ethernet connection, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) and navigate to "Example Connection Configuration" menu. Select either "Wi-Fi" or "Ethernet" in the "Connect using" choice. +To configure the example to use Wi-Fi or Ethernet connection, open the project configuration menu (`idf.py menuconfig`) and navigate to "Example Connection Configuration" menu. Select either "Wi-Fi" or "Ethernet" in the "Connect using" choice. When connecting using Wi-Fi, enter SSID and password of your Wi-Fi access point into the corresponding fields. If connecting to an open Wi-Fi network, keep the password field empty. diff --git a/examples/protocols/asio/chat_client/README.md b/examples/protocols/asio/chat_client/README.md index 951afad53..edc4c7189 100644 --- a/examples/protocols/asio/chat_client/README.md +++ b/examples/protocols/asio/chat_client/README.md @@ -5,15 +5,15 @@ Simple Asio chat client using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio chat client connects to the corresponding server whose port number and IP are defined through `make menuconfig`. -- Chat client receives all messages from other chat clients, also it sends message received from stdin using `make monitor`. +- Asio chat client connects to the corresponding server whose port number and IP are defined through the project configuration menu. +- Chat client receives all messages from other chat clients, also it sends message received from stdin using `idf.py monitor`. ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server IP address and port number in menuconfig, "Example configuration". - Start chat server either on host machine or as another ESP device running chat_server example. -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet. - Receive and send messages to/from other clients on stdin/stdout via serial terminal. diff --git a/examples/protocols/asio/chat_server/README.md b/examples/protocols/asio/chat_server/README.md index e043cba32..ec8b3e76e 100644 --- a/examples/protocols/asio/chat_server/README.md +++ b/examples/protocols/asio/chat_server/README.md @@ -5,14 +5,14 @@ Simple Asio chat server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio chat server is started on port number defined through `make menuconfig`. +- Asio chat server is started on port number defined through the project configuration. - Chat server echoes a message (received from any client) to all connected clients. ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - Connect to the server using multiple clients, for example using any option below. - build and run asi chat client on your host machine diff --git a/examples/protocols/asio/tcp_echo_server/README.md b/examples/protocols/asio/tcp_echo_server/README.md index f672027ef..b2443a245 100644 --- a/examples/protocols/asio/tcp_echo_server/README.md +++ b/examples/protocols/asio/tcp_echo_server/README.md @@ -5,14 +5,14 @@ Simple Asio TCP echo server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio TCP server is started on port number defined through `make menuconfig`. +- Asio TCP server is started on port number defined through the project configuration. - Server receives and echoes back messages transmitted from client. ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - You can now send a TCP message and check it is repeated, for example using netcat `nc IP PORT`. diff --git a/examples/protocols/asio/udp_echo_server/README.md b/examples/protocols/asio/udp_echo_server/README.md index cc69fee08..cc8a67e66 100644 --- a/examples/protocols/asio/udp_echo_server/README.md +++ b/examples/protocols/asio/udp_echo_server/README.md @@ -5,14 +5,14 @@ Simple Asio UDP echo server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. -- Asio UDP server is started on port number defined through `make menuconfig` +- Asio UDP server is started on port number defined through the project configuration - Server receives and echoes back messages transmitted from client ## Running the example -- Run `make menuconfig` to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +- Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". -- Run `make flash monitor` to build and upload the example to your board and connect to it's serial terminal. +- Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - You can now send a UDP message and check it is repeated, for example using netcat `nc -u IP PORT`. diff --git a/examples/protocols/coap_client/main/coap_client_example_main.c b/examples/protocols/coap_client/main/coap_client_example_main.c index 38761267f..921541aef 100644 --- a/examples/protocols/coap_client/main/coap_client_example_main.c +++ b/examples/protocols/coap_client/main/coap_client_example_main.c @@ -31,7 +31,7 @@ #define COAP_LOGGING_LEVEL 0 /* The examples use uri "coap://californium.eclipse.org" that - you can set via 'make menuconfig'. + you can set via the project configuration (idf.py menuconfig) If you'd rather not, just change the below entries to strings with the config you want - ie #define COAP_DEFAULT_DEMO_URI "coap://californium.eclipse.org" diff --git a/examples/protocols/http_server/file_serving/README.md b/examples/protocols/http_server/file_serving/README.md index 241e0808c..475cd7b0c 100644 --- a/examples/protocols/http_server/file_serving/README.md +++ b/examples/protocols/http_server/file_serving/README.md @@ -21,13 +21,13 @@ File server implementation can be found under `main/file_server.c` which uses SP ## Usage -* Configure the project using `make menuconfig` and goto `Example Configuration` -> +* Open the project configuration menu (`idf.py menuconfig`) go to `Example Configuration` -> 1. WIFI SSID: WIFI network to which your PC is also connected to. 2. WIFI Password: WIFI password * In order to test the file server demo : - 1. compile and burn the firmware `make flash` - 2. run `make monitor` and note down the IP assigned to your ESP module. The default port is 80 + 1. compile and burn the firmware `idf.py -p PORT flash` + 2. run `idf.py monitor` and note down the IP assigned to your ESP module. The default port is 80 3. test the example interactively on a web browser (assuming IP is 192.168.43.130): 1. open path `http://192.168.43.130/` or `http://192.168.43.130/index.html` to see an HTML web page with list of files on the server (initially empty) 2. use the file upload form on the webpage to select and upload a file to the server diff --git a/examples/protocols/http_server/persistent_sockets/README.md b/examples/protocols/http_server/persistent_sockets/README.md index ded2cfd6c..24c82a18a 100644 --- a/examples/protocols/http_server/persistent_sockets/README.md +++ b/examples/protocols/http_server/persistent_sockets/README.md @@ -3,11 +3,11 @@ The Example consists of HTTPD server persistent sockets demo. This sort of persistency enables the server to have independent sessions/contexts per client. -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +* Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * In order to test the HTTPD server persistent sockets demo : - 1. compile and burn the firmware "make flash" - 2. run "make monitor" and note down the IP assigned to your ESP module. The default port is 80 + 1. compile and burn the firmware `idf.py -p PORT flash` + 2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80 3. run the test script "python2 scripts/adder.py \ \ \" * the provided test script sends (POST) numbers from 1 to N to the server which has a URI POST handler for adding these numbers into an accumulator that is valid throughout the lifetime of the connection socket, hence persistent * the script does a GET before closing and displays the final value of the accumulator diff --git a/examples/protocols/http_server/restful_server/README.md b/examples/protocols/http_server/restful_server/README.md index 0a2ad7d87..9923d4232 100644 --- a/examples/protocols/http_server/restful_server/README.md +++ b/examples/protocols/http_server/restful_server/README.md @@ -57,7 +57,7 @@ Only if you deploy the website to SD card, then the following pin connection is ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. +Open the project configuration menu (`idf.py menuconfig`). In the `Example Connection Configuration` menu: @@ -88,7 +88,7 @@ npm run build After a while, you will see a `dist` directory which contains all the website files (e.g. html, js, css, images). -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/protocols/http_server/simple/README.md b/examples/protocols/http_server/simple/README.md index 969c03836..d9e9207fb 100644 --- a/examples/protocols/http_server/simple/README.md +++ b/examples/protocols/http_server/simple/README.md @@ -4,11 +4,11 @@ The Example consists of HTTPD server demo with demostration of URI handling : 1. URI \hello for GET command returns "Hello World!" message 2. URI \echo for POST command echoes back the POSTed message -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. +* Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * In order to test the HTTPD server persistent sockets demo : - 1. compile and burn the firmware "make flash" - 2. run "make monitor" and note down the IP assigned to your ESP module. The default port is 80 + 1. compile and burn the firmware `idf.py -p PORT flash` + 2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80 3. test the example : * run the test script : "python2 scripts/client.py \ \ \" * the provided test script first does a GET \hello and displays the response diff --git a/examples/protocols/https_server/README.md b/examples/protocols/https_server/README.md index be0ed0d58..088819d2c 100644 --- a/examples/protocols/https_server/README.md +++ b/examples/protocols/https_server/README.md @@ -4,7 +4,7 @@ This example creates a SSL server that returns a simple HTML page when you visit See the `esp_https_server` component documentation for details. -Before using the example, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. +Before using the example, open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. ## Certificates diff --git a/examples/protocols/mdns/README.md b/examples/protocols/mdns/README.md index 2c3516764..2392699b6 100644 --- a/examples/protocols/mdns/README.md +++ b/examples/protocols/mdns/README.md @@ -4,15 +4,15 @@ Shows how to use mDNS to advertise lookup services and hosts ## Example workflow -- mDNS is initialized with host name and instance name defined through `make menuconfig` and `_http._tcp` service is added to be advertised -- WiFi STA is started and trying to connect to the access point defined through `make menuconfig` +- mDNS is initialized with host name and instance name defined through the project configuration and `_http._tcp` service is added to be advertised +- WiFi STA is started and trying to connect to the access point defined through the project configuration - The system event handler is used to pass the network events to mDNS so the service is aware when the interface comes up or down - GPIO0 (BOOT Button) is initialized as pulled-up input that can be monitored for button press - Example task is started to check if the button is pressed so it can execute the mDNS queries defined ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/publish_test/README.md b/examples/protocols/mqtt/publish_test/README.md index bdc2bc879..d3db83641 100644 --- a/examples/protocols/mqtt/publish_test/README.md +++ b/examples/protocols/mqtt/publish_test/README.md @@ -22,7 +22,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. * Set brokers for all 4 transports (TCP, SSL, WS, WSS), also set certificate if needed diff --git a/examples/protocols/mqtt/ssl/README.md b/examples/protocols/mqtt/ssl/README.md index 929257d40..5925c4001 100644 --- a/examples/protocols/mqtt/ssl/README.md +++ b/examples/protocols/mqtt/ssl/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/ssl_mutual_auth/README.md b/examples/protocols/mqtt/ssl_mutual_auth/README.md index 763e2671a..9b20b37ca 100644 --- a/examples/protocols/mqtt/ssl_mutual_auth/README.md +++ b/examples/protocols/mqtt/ssl_mutual_auth/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/tcp/README.md b/examples/protocols/mqtt/tcp/README.md index aea663094..7247a7a22 100644 --- a/examples/protocols/mqtt/tcp/README.md +++ b/examples/protocols/mqtt/tcp/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/ws/README.md b/examples/protocols/mqtt/ws/README.md index efe2efcb3..236521f90 100644 --- a/examples/protocols/mqtt/ws/README.md +++ b/examples/protocols/mqtt/ws/README.md @@ -14,7 +14,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/mqtt/wss/README.md b/examples/protocols/mqtt/wss/README.md index 9433986a5..453d52f70 100644 --- a/examples/protocols/mqtt/wss/README.md +++ b/examples/protocols/mqtt/wss/README.md @@ -13,7 +13,7 @@ This example can be executed on any ESP32 board, the only required interface is ### Configure the project -* Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system) +* Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. diff --git a/examples/protocols/openssl_client/README.md b/examples/protocols/openssl_client/README.md index 07be75719..272060a60 100644 --- a/examples/protocols/openssl_client/README.md +++ b/examples/protocols/openssl_client/README.md @@ -2,7 +2,7 @@ The Example contains of OpenSSL client demo. -To configure the project, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`): * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. diff --git a/examples/protocols/openssl_client/main/openssl_client_example.h b/examples/protocols/openssl_client/main/openssl_client_example.h index 8d1645164..206d9a91b 100644 --- a/examples/protocols/openssl_client/main/openssl_client_example.h +++ b/examples/protocols/openssl_client/main/openssl_client_example.h @@ -11,7 +11,7 @@ #define _OPENSSL_EXAMPLE_H_ /* The examples use domain of "www.baidu.com" and port number of 433 that - you can set via 'make menuconfig'. + you can set via the project configuration menu. If you'd rather not, just change the below entries to strings with the config you want - ie #define OPENSSL_EXAMPLE_TARGET_NAME "www.baidu.com" diff --git a/examples/protocols/openssl_server/README.md b/examples/protocols/openssl_server/README.md index 6d4506e93..d30439703 100644 --- a/examples/protocols/openssl_server/README.md +++ b/examples/protocols/openssl_server/README.md @@ -2,7 +2,7 @@ The Example contains of OpenSSL server demo. -To configure the project, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`): * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. diff --git a/examples/protocols/pppos_client/README.md b/examples/protocols/pppos_client/README.md index bcfb8e503..a449a261c 100644 --- a/examples/protocols/pppos_client/README.md +++ b/examples/protocols/pppos_client/README.md @@ -32,7 +32,7 @@ You can also try other modules as long as they embedded PPP protocol. ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - Choose the modem module in `Choose supported modem device(DCE)` option, currently we only support BG96 and SIM800L. - Set the access point name in `Set Access Point Name(APN)` option, which should depend on the operator of your SIM card. @@ -44,7 +44,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. +Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/protocols/sntp/README.md b/examples/protocols/sntp/README.md index 1c3671f3f..9a7078c47 100644 --- a/examples/protocols/sntp/README.md +++ b/examples/protocols/sntp/README.md @@ -4,7 +4,7 @@ This example demonstrates the use of LwIP SNTP module to obtain time from Intern ## Configuring the Example -To configure the project, run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`): * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../README.md) for more details. diff --git a/examples/protocols/sockets/udp_multicast/README.md b/examples/protocols/sockets/udp_multicast/README.md index 7bc066db0..649bd6119 100644 --- a/examples/protocols/sockets/udp_multicast/README.md +++ b/examples/protocols/sockets/udp_multicast/README.md @@ -12,7 +12,7 @@ The behaviour of the example is: ## Configuration -Run `make menuconfig` (or `idf.py menuconfig` if using CMake build system). +Open the project configuration menu (`idf.py menuconfig`). Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. diff --git a/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c b/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c index ee6878897..ea438991a 100644 --- a/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c +++ b/examples/protocols/sockets/udp_multicast/main/udp_multicast_example_main.c @@ -25,7 +25,7 @@ #include /* The examples use simple configuration that you can set via - 'make menuconfig'. + project configuration. If you'd rather not, just change the below entries to strings with the config you want - ie #define UDP_PORT 3333 diff --git a/examples/storage/nvs_rw_blob/README.md b/examples/storage/nvs_rw_blob/README.md index 90a8f8bfa..620edd85e 100644 --- a/examples/storage/nvs_rw_blob/README.md +++ b/examples/storage/nvs_rw_blob/README.md @@ -19,22 +19,10 @@ If not done already, consider checking simpler example *storage/nvs_rw_value*, t This example can be run on most common development boards which have an active button connected to GPIO0. On most boards, this button is labeled as "Boot". When pressed, the button connects GPIO0 to ground. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` @@ -75,5 +63,5 @@ Run time: 2: 5860 ``` -To reset the counter and run time array, erase the contents of flash memory using `make erase_flash` (or `idf.py erase_flash`, if using CMake build system), then upload the program again as described above. +To reset the counter and run time array, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above. diff --git a/examples/storage/nvs_rw_value/README.md b/examples/storage/nvs_rw_value/README.md index 87d3405d4..df725b0e0 100644 --- a/examples/storage/nvs_rw_value/README.md +++ b/examples/storage/nvs_rw_value/README.md @@ -18,22 +18,10 @@ Check another example *storage/nvs_rw_blob*, which shows how to read and write v This example does not require any special hardware, and can be run on any common development board. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` @@ -90,5 +78,5 @@ Restarting now. Restart counter will increment on each run. -To reset the counter, erase the contents of flash memory using `make erase_flash` (or `idf.py erase_flash`, if using CMake build system), then upload the program again as described above. +To reset the counter, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above. diff --git a/examples/storage/sd_card/README.md b/examples/storage/sd_card/README.md index 09fb2c0cd..8901c343e 100644 --- a/examples/storage/sd_card/README.md +++ b/examples/storage/sd_card/README.md @@ -68,12 +68,6 @@ This command will burn the `XPD_SDIO_TIEH`, `XPD_SDIO_FORCE`, and `XPD_SDIO_REG` ## How to use example -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - SD card can be used in various modes. See below on choosing the mode to be used. ### 4-line and 1-line SD modes @@ -96,16 +90,12 @@ By default, the example uses SDMMC Host peripheral to access the card using SD p Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` +(Replace PORT with serial port name.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. diff --git a/examples/storage/semihost_vfs/README.md b/examples/storage/semihost_vfs/README.md index 4728f0866..d25ed1ab4 100644 --- a/examples/storage/semihost_vfs/README.md +++ b/examples/storage/semihost_vfs/README.md @@ -25,21 +25,9 @@ bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -c ' ``` This command also configures OpenOCD to expose example project `data` subdirectory to the target's semihosting VFS driver. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash -Build the project and flash it to the board, then run monitor tool to view serial output: - -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): +Replace PORT with serial port name: ``` idf.py -p PORT flash monitor diff --git a/examples/storage/spiffs/README.md b/examples/storage/spiffs/README.md index aacced044..d56883956 100644 --- a/examples/storage/spiffs/README.md +++ b/examples/storage/spiffs/README.md @@ -20,21 +20,9 @@ SPIFFS partition size is set in partitions_example.csv file. See [Partition Tabl This example does not require any special hardware, and can be run on any common development board. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash -Build the project and flash it to the board, then run monitor tool to view serial output: - -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): +Replace PORT with serial port name: ``` idf.py -p PORT flash monitor @@ -60,4 +48,4 @@ I (19584) example: Read from file: 'Hello World!' I (19584) example: SPIFFS unmounted ``` -To erase the contents of SPIFFS partition, run `make erase_flash` command (or `idf.py erase_flash`, if using CMake build system). Then upload the example again as described above. +To erase the contents of SPIFFS partition, run `idf.py erase_flash` command. Then upload the example again as described above. diff --git a/examples/storage/spiffsgen/README.md b/examples/storage/spiffsgen/README.md index fcacb6bbd..1176d343d 100644 --- a/examples/storage/spiffsgen/README.md +++ b/examples/storage/spiffsgen/README.md @@ -4,7 +4,7 @@ This example demonstrates how to use the SPIFFS image generation tool [spiffsgen.py](../../../components/spiffs/spiffsgen.py) to automatically create a SPIFFS filesystem image from the contents of a host folder during build, with an option of -automatically flashing the created image on invocation of `idf.py flash` or `make flash`. +automatically flashing the created image on invocation of `idf.py flash`. For more information, see description of `spiffsgen.py` on the ESP-IDF Programming Guide under API Reference > Storage > SPIFFS Filesystem. The following gives an overview of the example: @@ -14,10 +14,10 @@ The following gives an overview of the example: 2. The function `spiffs_create_partition_image` is used to specify that a SPIFFS image should be created during build for the `storage` partition. For CMake, it is called from [the main component's CMakeLists.txt](./main/CMakeLists.txt); for Make, from the [project Makefile](./Makefile). `FLASH_IN_PROJECT` specifies that the created image -should be flashed on invocation of `idf.py flash` or `make flash` together with app, bootloader, partition table, etc. +should be flashed on invocation of `idf.py flash` together with app, bootloader, partition table, etc. For both build systems, the image is created on the example's build directory with the output filename `storage.bin`. -3. Upon invocation of `idf.py flash monitor` or `make flash monitor`, application loads and +3. Upon invocation of `idf.py flash monitor`, application loads and finds there is already a valid SPIFFS filesystem in the `storage` partition with files same as those in `spiffs_image` directory. The application is then able to read those files. @@ -56,4 +56,4 @@ I (330) example: Computed MD5 hash of alice.txt: deeb71f585cbb3ae5f7976d5127faf2 I (330) example: SPIFFS unmounted ``` -The logic of the example is contained in a [single source file](./main/spiffsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above. \ No newline at end of file +The logic of the example is contained in a [single source file](./main/spiffsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above. diff --git a/examples/storage/wear_levelling/README.md b/examples/storage/wear_levelling/README.md index 9bf11ded4..9578e1644 100644 --- a/examples/storage/wear_levelling/README.md +++ b/examples/storage/wear_levelling/README.md @@ -20,26 +20,16 @@ Wear levelling partition size is set in partitions_example.csv file. See [Partit This example does not require any special hardware, and can be run on any common development board. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash Build the project and flash it to the board, then run monitor tool to view serial output: -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` +(Replace PORT with serial port name.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. @@ -61,4 +51,4 @@ I (920) example: Unmounting FAT filesystem I (1000) example: Done ``` -To erase the contents of wear levelling partition, run `make erase_flash` command (or `idf.py erase_flash`, if using CMake build system). Then upload the example again as described above. +To erase the contents of wear levelling partition, run `idf.py erase_flash` command. Then upload the example again as described above. diff --git a/examples/system/app_trace_to_host/README.md b/examples/system/app_trace_to_host/README.md index 1abb8bde6..aa5786242 100644 --- a/examples/system/app_trace_to_host/README.md +++ b/examples/system/app_trace_to_host/README.md @@ -99,7 +99,7 @@ To run this example, you need an ESP32 dev board (e.g. [ESP-WROVER-KIT](https:// ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - By default, the DAC will generate 130 Hz signal within 0V..3.1V. To get 50Hz, you need to set non-standard driver of RTC 8MHz clock to lower minimum CW (Cosine Waveform) generator's frequency in `Set custom RTC 8 MHz clock divider to lower CW frequency`. @@ -107,7 +107,7 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build, Flash and Run -1. Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. (To exit the serial monitor, type ``Ctrl-]``.) +1. Run `idf.py -p PORT flash monitor` to build and flash the project.. (To exit the serial monitor, type ``Ctrl-]``.) See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects. 2. In the telnet session window, run the following command. This command will collect 9000 bytes of log data and save them to `adc.log` file in `~/esp/openocd-esp32` folder. diff --git a/examples/system/cpp_exceptions/README.md b/examples/system/cpp_exceptions/README.md index 2056379ed..0589d885d 100644 --- a/examples/system/cpp_exceptions/README.md +++ b/examples/system/cpp_exceptions/README.md @@ -12,17 +12,13 @@ Example source code declares a class which can throw exception from the construc ## How to use example -### Configure the project - -Run `make menuconfig` and set serial port under Serial Flasher Options. - ### Build and Flash -Build the project and flash it to the board, then run monitor tool to view serial output: +``` +idf.py -p PORT flash monitor +``` -``` -make -j4 flash monitor -``` +(Replace PORT with the name of the serial port.) (To exit the serial monitor, type ``Ctrl-]``.) diff --git a/examples/system/gcov/main/gcov_example.c b/examples/system/gcov/main/gcov_example.c index 1cfa9ea53..e6d745768 100644 --- a/examples/system/gcov/main/gcov_example.c +++ b/examples/system/gcov/main/gcov_example.c @@ -13,8 +13,8 @@ #include "esp_app_trace.h" #include "sdkconfig.h" -/* Can run 'make menuconfig' to choose the GPIO to blink, - or you can edit the following line and set a number here. +/* Can use project configuration menu (idf.py menuconfig) to choose the GPIO + to blink, or you can edit the following line and set a number here. */ #define BLINK_GPIO CONFIG_BLINK_GPIO diff --git a/examples/system/light_sleep/README.md b/examples/system/light_sleep/README.md index 2fa545dae..bdc107cf4 100644 --- a/examples/system/light_sleep/README.md +++ b/examples/system/light_sleep/README.md @@ -17,18 +17,16 @@ The example also prints time spent in light sleep mode to illustrate that timeke This example can be used with any ESP32 development board. Most boards have a button attached to GPIO0, often labelled "BOOT". If the board does not have such button, an external button can be connected, along with a 10k pull-up resistor, and a 100nF capacitor to ground for debouncing. -### Configure the Project - -Run `make menuconfig` and set serial port under Serial Flasher Options. - ### Build and Flash Build the project and flash it to the board, then run monitor tool to view serial output: ``` -make -j4 flash monitor +idf.py -p PORT flash monitor ``` +(Replace PORT with the name of the serial port to use.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. diff --git a/examples/system/ota/README.md b/examples/system/ota/README.md index f9baa4c4b..0baf9d048 100644 --- a/examples/system/ota/README.md +++ b/examples/system/ota/README.md @@ -27,7 +27,7 @@ To run the OTA examples, you need an ESP32 dev board (e.g. ESP32-WROVER Kit) or ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. +Open the project configuration menu (`idf.py menuconfig`). In the `Example Connection Configuration` menu: @@ -44,7 +44,7 @@ In the `Example Configuration` menu: ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you are using CMake based build system. This command will find if partition table has ota_data partition (as in our case) then ota_data will erase to initial. It allows to run the newly loaded app from a factory partition. +Run `idf.py -p PORT flash monitor` to build and flash the project.. This command will find if partition table has ota_data partition (as in our case) then ota_data will erase to initial. It allows to run the newly loaded app from a factory partition. (To exit the serial monitor, type ``Ctrl-]``.) @@ -85,7 +85,7 @@ When the example starts up, it will print "Starting OTA example" to the console 3. Write the image to flash, and configure the next boot from this image. 4. Reboot -If you want to rollback to factory app (or the first OTA partition when the factory partition do not exist) after the upgrade, then run the command `make erase_otadata` or `idf.py erase_otadata`. It can erase the ota_data partition to initial state. +If you want to rollback to factory app (or the first OTA partition when the factory partition do not exist) after the upgrade, then run the command `idf.py erase_otadata`. It can erase the ota_data partition to initial state. **Notes:** This assumes that the partition table of this project is the one that is on the device. @@ -127,4 +127,4 @@ In ``native_ota_example``, ``$PROJECT_PATH/version.txt`` is used to define the v If you see this error then check that the configured (and actual) flash size is large enough for the partitions in the partition table. The default "two OTA slots" partition table only works with 4MB flash size. To use OTA with smaller flash sizes, create a custom partition table CSV (look in components/partition_table) and configure it in menuconfig. -If changing partition layout, it is usually wise to run "make erase_flash" between steps. +If changing partition layout, it is usually wise to run "idf.py erase_flash" between steps. diff --git a/examples/system/sysview_tracing_heap_log/README.md b/examples/system/sysview_tracing_heap_log/README.md index 8d3931164..8e4dfad63 100644 --- a/examples/system/sysview_tracing_heap_log/README.md +++ b/examples/system/sysview_tracing_heap_log/README.md @@ -19,26 +19,14 @@ when program hits breakpoint at `heap_trace_start`. Trace data will be saved to 3. [SEGGER SystemView tool](https://www.segger.com/products/development-tools/systemview/). By default SystemView shows only numeric values of IDs and parameters for IDF's heap messages in `Events` view. To make them pretty-looking you need to copy `SYSVIEW_FreeRTOS.txt` from the project's root directory to SystemView installation one. -### Configure the project - -If using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options. - -If using CMake based build system, no configuration is required. - ### Build and flash -Build the project and flash it to the board, then run monitor tool to view serial output: - -``` -make -j4 flash monitor -``` - -Or, for CMake based build system (replace PORT with serial port name): - ``` idf.py -p PORT flash monitor ``` +(Replace PORT with serial port name.) + (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. @@ -161,4 +149,4 @@ Processed 14 heap events. /home/user/projects/esp/esp-idf/components/freertos/port.c:355 (discriminator 1) Found 10 leaked bytes in 4 blocks. -``` \ No newline at end of file +``` diff --git a/examples/system/unit_test/README.md b/examples/system/unit_test/README.md index acea22d5c..fbba3cf42 100644 --- a/examples/system/unit_test/README.md +++ b/examples/system/unit_test/README.md @@ -55,9 +55,7 @@ This example doesn't require any special hardware, and can run on any ESP32 deve As explained above, this example contains two projects: application project and test project. -When using Make based build system, run `make menuconfig` and set serial port under Serial Flasher Options, in each of these projects. - -For the test project, you can explore a few options related to Unity under Component Config, Unity unit testing library. +For the test project, you can open the project configuration menu (`idf.py menuconfig`) and explore a few options related to Unity under Component Config, Unity unit testing library. ### Build and flash @@ -65,12 +63,12 @@ As explained above, this example contains two projects: application project and 1. Application project calls an API defined in the component, and displays the results. It is not of much value to run. Application project is provided mainly to illustrate the layout of all the files. If you decide to run this project, the procedure is: - * Run `make -j4 flash monitor` in the current directory (`unit_test`), or `idf.py -p PORT flash monitor` if you are using CMake build system. + * Run `idf.py -p PORT flash monitor` in the current directory (`unit_test`). * Observe the output: a list of random numbers and their mean value. 2. Test project is responsible for running the tests. - * Enter `test` directory (`unit_test/test`), and run `make -j4 flash monitor`, or `idf.py -p PORT flash monitor` if you are using CMake build system. + * Enter `test` directory (`unit_test/test`), and run `idf.py -p PORT flash monitor`. * Observe the output: results of test case execution. diff --git a/examples/wifi/getting_started/softAP/main/softap_example_main.c b/examples/wifi/getting_started/softAP/main/softap_example_main.c index 515e3618e..010289554 100644 --- a/examples/wifi/getting_started/softAP/main/softap_example_main.c +++ b/examples/wifi/getting_started/softAP/main/softap_example_main.c @@ -18,7 +18,7 @@ #include "lwip/err.h" #include "lwip/sys.h" -/* The examples use WiFi configuration that you can set via 'make menuconfig'. +/* The examples use WiFi configuration that you can set via project configuration menu. If you'd rather not, just change the below entries to strings with the config you want - ie #define EXAMPLE_WIFI_SSID "mywifissid" diff --git a/examples/wifi/getting_started/station/main/station_example_main.c b/examples/wifi/getting_started/station/main/station_example_main.c index 917f53cdb..ae6101f2d 100644 --- a/examples/wifi/getting_started/station/main/station_example_main.c +++ b/examples/wifi/getting_started/station/main/station_example_main.c @@ -19,7 +19,7 @@ #include "lwip/err.h" #include "lwip/sys.h" -/* The examples use WiFi configuration that you can set via 'make menuconfig'. +/* The examples use WiFi configuration that you can set via project configuration menu If you'd rather not, just change the below entries to strings with the config you want - ie #define EXAMPLE_WIFI_SSID "mywifissid" diff --git a/examples/wifi/scan/main/scan.c b/examples/wifi/scan/main/scan.c index 9607d6114..f5b0d29fd 100644 --- a/examples/wifi/scan/main/scan.c +++ b/examples/wifi/scan/main/scan.c @@ -28,7 +28,7 @@ #include "esp_event.h" #include "nvs_flash.h" -/*Set the SSID and Password via "make menuconfig"*/ +/* Set the SSID and Password via project configuration, or can set directly here */ #define DEFAULT_SSID CONFIG_EXAMPLE_WIFI_SSID #define DEFAULT_PWD CONFIG_EXAMPLE_WIFI_PASSWORD diff --git a/examples/wifi/simple_sniffer/README.md b/examples/wifi/simple_sniffer/README.md index bf3863250..7c8ba2d4a 100644 --- a/examples/wifi/simple_sniffer/README.md +++ b/examples/wifi/simple_sniffer/README.md @@ -19,7 +19,7 @@ If you want to send packets to host, make sure to connect ESP32 to some kind of ### Configure the project -Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu. +Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu. - Check `Store command history in flash` if you want to save command history into flash (recommend). - Select where to save the pcap file in `Select destination to store pcap file` menu item. @@ -33,7 +33,11 @@ Enter `make menuconfig` if you are using GNU Make based build system or enter `i ### Build and Flash -Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you' are using CMake based build system. +``` +idf.py -p PORT flash monitor +``` + +(Replace PORT with name of the serial port.) (To exit the serial monitor, type ``Ctrl-]``.) @@ -114,7 +118,7 @@ I (248800) example: Card unmounted ### Steps for sending packets to host via JTAG interface 1. Select `JTAG (App Trace)` as the destination of pcap files. -2. Build & Flash with `idf.py build flash` or `make flash`. +2. Build & Flash with `idf.py -p PORT flash` 3. Connect JTAG, run OpenOCD (for more information about how-to please refer to [JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html)). 4. Telnet to localhost with 4444 port: `telnet localhost 4444`. 5. In the telnet session, run command like `esp32 apptrace start file://sniffer-esp32.pcap 1 -1 20` (more information about this command, please refer to [apptrace command](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#openocd-application-level-tracing-commands)). diff --git a/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c b/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c index e2127d84b..232065c4b 100644 --- a/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c +++ b/examples/wifi/wpa2_enterprise/main/wpa2_enterprise_main.c @@ -30,12 +30,12 @@ #include "tcpip_adapter.h" /* The examples use simple WiFi configuration that you can set via - 'make menuconfig'. + project configuration menu. If you'd rather not, just change the below entries to strings with the config you want - ie #define EXAMPLE_WIFI_SSID "mywifissid" - You can choose EAP method via 'make menuconfig' according to the + You can choose EAP method via project configuration according to the configuration of AP. */ #define EXAMPLE_WIFI_SSID CONFIG_EXAMPLE_WIFI_SSID diff --git a/examples/wifi/wps/main/wps.c b/examples/wifi/wps/main/wps.c index 62465e2de..5ac103b7f 100644 --- a/examples/wifi/wps/main/wps.c +++ b/examples/wifi/wps/main/wps.c @@ -29,7 +29,7 @@ #include "nvs_flash.h" -/*set wps mode via "make menuconfig"*/ +/*set wps mode via project configuration */ #if CONFIG_EXAMPLE_WPS_TYPE_PBC #define WPS_MODE WPS_TYPE_PBC #elif CONFIG_EXAMPLE_WPS_TYPE_PIN diff --git a/tools/esp_app_trace/test/sysview/blink.c b/tools/esp_app_trace/test/sysview/blink.c index ecbdf6449..baa345be4 100644 --- a/tools/esp_app_trace/test/sysview/blink.c +++ b/tools/esp_app_trace/test/sysview/blink.c @@ -13,8 +13,8 @@ #include "sdkconfig.h" #include "esp_heap_trace.h" -/* Can run 'make menuconfig' to choose the GPIO to blink, - or you can edit the following line and set a number here. +/* Can use project configuration menu (idf.py menuconfig) to choose the GPIO + to blink or you can edit the following line and set a number here. */ #define BLINK_GPIO CONFIG_BLINK_GPIO diff --git a/tools/idf_monitor.py b/tools/idf_monitor.py index 4700980b0..f68020613 100755 --- a/tools/idf_monitor.py +++ b/tools/idf_monitor.py @@ -3,8 +3,8 @@ # esp-idf serial output monitor tool. Does some helpful things: # - Looks up hex addresses in ELF file with addr2line # - Reset ESP32 via serial RTS line (Ctrl-T Ctrl-R) -# - Run "make (or idf.py) flash" (Ctrl-T Ctrl-F) -# - Run "make (or idf.py) app-flash" (Ctrl-T Ctrl-A) +# - Run flash build target to rebuild and flash entire project (Ctrl-T Ctrl-F) +# - Run app-flash build target to rebuild and flash app only (Ctrl-T Ctrl-A) # - If gdbstub output is detected, gdb is automatically loaded # # Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD diff --git a/tools/unit-test-app/README.md b/tools/unit-test-app/README.md index 23ce65289..349a09eb0 100644 --- a/tools/unit-test-app/README.md +++ b/tools/unit-test-app/README.md @@ -4,16 +4,6 @@ ESP-IDF unit tests are run using Unit Test App. The app can be built with the un # Building Unit Test App -## GNU Make - -* Follow the setup instructions in the top-level esp-idf README. -* Set IDF_PATH environment variable to point to the path to the esp-idf top-level directory. -* Change into `tools/unit-test-app` directory -* `make menuconfig` to configure the Unit Test App. -* `make TEST_COMPONENTS=` with `TEST_COMPONENTS` set to names of the components to be included in the test app. Or `make TESTS_ALL=1` to build the test app with all the tests for components having `test` subdirectory. -* Follow the printed instructions to flash, or run `make flash`. -* Unit test have a few preset sdkconfigs. It provides command `make ut-clean-config_name` and `make ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `make ut-build-default TESTS_ALL=1` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder. - ## CMake * Follow the setup instructions in the top-level esp-idf README. @@ -24,11 +14,21 @@ ESP-IDF unit tests are run using Unit Test App. The app can be built with the un * Follow the printed instructions to flash, or run `idf.py -p PORT flash`. * Unit test have a few preset sdkconfigs. It provides command `idf.py ut-clean-config_name` and `idf.py ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `idf.py -T all ut-build-default` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder. +## Legacy GNU Make + +* Follow the setup instructions in the top-level esp-idf README. +* Set IDF_PATH environment variable to point to the path to the esp-idf top-level directory. +* Change into `tools/unit-test-app` directory +* `make menuconfig` to configure the Unit Test App. +* `make TEST_COMPONENTS=` with `TEST_COMPONENTS` set to names of the components to be included in the test app. Or `make TESTS_ALL=1` to build the test app with all the tests for components having `test` subdirectory. +* Follow the printed instructions to flash, or run `make flash`. +* Unit test have a few preset sdkconfigs. It provides command `make ut-clean-config_name` and `make ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `make ut-build-default TESTS_ALL=1` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder. + # Flash Size -The unit test partition table assumes a 4MB flash size. When testing `TESTS_ALL=1` (Make) or `-T all` (CMake), this additional factory app partition size is required. +The unit test partition table assumes a 4MB flash size. When testing `-T all` or `TESTS_ALL=1` (Legacy GNU Make) or, this additional factory app partition size is required. -If building unit tests to run on a smaller flash size, edit `partition_table_unit_tests_app.csv` and use `TEST_COMPONENTS=` (Make) or `-T ...` (CMake) instead of `TESTS_ALL` or `-T all` if tests don't fit in a smaller factory app partition (exact size will depend on configured options). +If building unit tests to run on a smaller flash size, edit `partition_table_unit_tests_app.csv` and use `-T ...` or `TEST_COMPONENTS=` (Legacy GNU Make) or instead of `-T all` or `TESTS_ALL` if tests don't fit in a smaller factory app partition (exact size will depend on configured options). # Running Unit Tests