From c7f19e76d7bcb62762ba36ea000c3f9f958f3dc7 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 3 May 2018 14:22:35 +1000 Subject: [PATCH] docs: Move main docs to cover CMake Add "GNU Make build system" doc with "cheat sheet" for moving to new system --- README.md | 40 +- components/ethernet/emac_main.c | 2 +- components/spi_flash/README.rst | 2 +- docs/en/api-guides/build-system-cmake.rst | 799 ---------------- docs/en/api-guides/build-system.rst | 899 +++++++++++------- docs/en/api-guides/cmake-preview-index.rst | 10 - docs/en/api-guides/console.rst | 2 +- docs/en/api-guides/core_dump.rst | 4 +- docs/en/api-guides/gnu-make-build-system.rst | 51 + .../jtag-debugging/setup-openocd-windows.rst | 4 +- .../add-idf_path-to-profile-cmake.rst | 70 -- .../get-started/add-idf_path-to-profile.rst | 62 +- docs/en/get-started/eclipse-setup-windows.rst | 78 -- docs/en/get-started/eclipse-setup.rst | 104 +- .../establish-serial-connection.rst | 3 - docs/en/get-started/idf-monitor.rst | 9 +- docs/en/get-started/index-cmake.rst | 347 ------- docs/en/get-started/index.rst | 180 +++- docs/en/get-started/linux-setup-cmake.rst | 113 --- docs/en/get-started/linux-setup-scratch.rst | 21 +- docs/en/get-started/linux-setup.rst | 12 +- docs/en/get-started/macos-setup-cmake.rst | 64 -- docs/en/get-started/macos-setup-scratch.rst | 28 +- docs/en/get-started/macos-setup.rst | 23 +- docs/en/get-started/windows-setup-cmake.rst | 58 -- .../windows-setup-scratch-cmake.rst | 85 -- docs/en/get-started/windows-setup-scratch.rst | 167 ++-- docs/en/get-started/windows-setup.rst | 67 +- docs/en/index.rst | 4 +- .../api-guides/gnu-make-build-system.rst | 1 + .../get-started/eclipse-setup-windows.rst | 81 -- docs/zh_CN/get-started/eclipse-setup.rst | 103 +- docs/zh_CN/get-started/index.rst | 2 + docs/zh_CN/get-started/linux-setup.rst | 2 + docs/zh_CN/get-started/macos-setup.rst | 2 + docs/zh_CN/get-started/windows-setup.rst | 4 +- tools/idf.py | 8 +- tools/unit-test-app/README.md | 2 +- 38 files changed, 996 insertions(+), 2517 deletions(-) delete mode 100644 docs/en/api-guides/build-system-cmake.rst delete mode 100644 docs/en/api-guides/cmake-preview-index.rst create mode 100644 docs/en/api-guides/gnu-make-build-system.rst delete mode 100644 docs/en/get-started/add-idf_path-to-profile-cmake.rst delete mode 100644 docs/en/get-started/eclipse-setup-windows.rst delete mode 100644 docs/en/get-started/index-cmake.rst delete mode 100644 docs/en/get-started/linux-setup-cmake.rst delete mode 100644 docs/en/get-started/macos-setup-cmake.rst delete mode 100644 docs/en/get-started/windows-setup-cmake.rst delete mode 100644 docs/en/get-started/windows-setup-scratch-cmake.rst create mode 100644 docs/zh_CN/api-guides/gnu-make-build-system.rst delete mode 100644 docs/zh_CN/get-started/eclipse-setup-windows.rst diff --git a/README.md b/README.md index df29f2221f..631d54a407 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Once you've found the project you want to work with, change to its directory and ## 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. @@ -36,51 +36,41 @@ Once done configuring, press Escape multiple times to exit and say "Yes" to save ## Compiling the Project -`make all` +`idf.py build` ... will compile app, bootloader and generate a partition table based on the config. ## Flashing the Project -When `make all` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running: +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 flash` +`idf.py 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`. +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 `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it. +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://esp-idf.readthedocs.io/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://esp-idf.readthedocs.io/en/latest/get-started/idf-monitor.html). +The `idf.py monitor` target uses the [idf_monitor tool](https://esp-idf.readthedocs.io/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://esp-idf.readthedocs.io/en/latest/get-started/idf-monitor.html). Exit the monitor by typing Ctrl-]. To flash and monitor output in one pass, you can run: -`make flash monitor` +`idf.py flash monitor` ## Compiling & Flashing Just 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 it needs it. +`idf.py app-flash` will automatically rebuild the app if it needs it. (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 or one more than the number of CPU cores in your system.) - -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. @@ -89,20 +79,20 @@ A single ESP32's flash can contain multiple apps, as well as many different kind 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 `idf.py 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. +In both cases the factory app is flashed at offset 0x10000. If you `idf.py 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 erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table. # Resources diff --git a/components/ethernet/emac_main.c b/components/ethernet/emac_main.c index b8c94b0fad..5605ea860a 100644 --- a/components/ethernet/emac_main.c +++ b/components/ethernet/emac_main.c @@ -275,7 +275,7 @@ static void emac_set_user_config_data(eth_config_t *config ) emac_config.emac_flow_ctrl_enable = config->flow_ctrl_enable; #else if(config->flow_ctrl_enable == true) { - ESP_LOGE(TAG, "eth flow ctrl init err!!! Please run make menuconfig and make sure DMA_RX_BUF_NUM > 9 ."); + ESP_LOGE(TAG, "eth flow ctrl init err!!! Please run idf.py menuconfig and make sure DMA_RX_BUF_NUM > 9 ."); } emac_config.emac_flow_ctrl_enable = false; #endif diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst index ef4cb1f821..601603954b 100644 --- a/components/spi_flash/README.rst +++ b/components/spi_flash/README.rst @@ -36,7 +36,7 @@ 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 -:ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``. +:ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``idf.py menuconfig``. If it is necessary to override the configured flash size at runtime, is is possible to set the ``chip_size`` member of ``g_rom_flashchip`` structure. This 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 7175896342..0000000000 --- a/docs/en/api-guides/build-system-cmake.rst +++ /dev/null @@ -1,799 +0,0 @@ -CMake-based Build System -************************ - -This document explains the CMake-based 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 using the CMake-based build system. - -We recommend using the esp-idf-template_ project as a starting point for your project. - -Preview Release -=============== - -.. note:: - The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The document describing the :doc:`fully supported non-CMake build system is here `. - -CMake-based build system preview release temporarily has the following limitations: - -- No instructions published for use with any IDEs. -- No support for building ULP firmware as part of the build. -- No support for flash encryption, secure boot. -- ``idf.py monitor`` only runs at 115200bps -- The rebuild/reflash commands inside monitor don't work correctly. - -These missing features will be added before CMake support is officially supported. - -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 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 ``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. - -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 ------- - -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 subdirectory ``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. -- ``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. -- ``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. - -Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean build flash monitor`` will perform a clean build of the project, then flash to the ESP32 and run the serial monitor. - -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. - -Using CMake Directly --------------------- - -``idf.py`` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer. - -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:: - - mkdir -p build - cd build - cmake .. -G Ninja # or 'GNU Make' - 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_: runnning ``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 reconfiguring. - -If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` subcommands - for example running ``make 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. - -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. - -Example Project -=============== - -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. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then 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. - -- 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 "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. 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 --------------------------- - -:: - cmake_minimum_required(VERSION 3.5) - - set(MAIN_SRCS main/src1.c main/src2.c) - - include($ENV{IDF_PATH}/tools/cmake/project.cmake) - project(myProject) - - -Mandatory Parts ---------------- - -The inclusion of these four lines, in the order shown above, is necessary for every project: - -- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version 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. -- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" subdirectory, but this structure is encouraged. - - It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below. - - ``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else). -- ``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``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, 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. 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 ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list doesn't need to include dependencies in this way. -- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically treated to be in every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this is set to the minimal set of core "system" components needed for any ESP-IDF project. - -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. - - -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 (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 subdirectories 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 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 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 CMakeLists ----------------------------- - -The minimal component ``CMakeLists.txt`` file is as follows:: - - set(COMPONENT_SRCDIRS ".") - set(COMPONENT_ADD_INCLUDEDIRS "include") - register_component() - -- ``COMPONENT_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library. -- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for all other components, and the main source files. -- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if() statement` or similar), this component will not be built at all. - -Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute. - -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_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. 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. - -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. 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. -- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. `More information here `. -- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``) - -If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug. - - -- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component - directory, which will be added to the include search path for - all other components which require this one. If an include directory is only needed to compile - this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead. -- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If a public header header file listed in ``COMPONENT_ADD_INCLUDEDIRS`` includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive. - - The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``. - - If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead. - - See `Component Requirements` for more details. - -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_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements` for more details. -- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the - component directory, which will be searched for source files (``*.cpp``, - ``*.c``, ``*.S``). Set this to specify a list of directories - which contain source files. -- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled. - If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add paths to include search paths. - -Controlling Component Compilation ---------------------------------- - -To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function:: - - component_compile_options(-Wno-unused-variable) - -This is a wrapper around the CMake `target_compile_options`_ command. - -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 ``register_component()`` line in the component CMakeLists file. - -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 -======================== - -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 recurisvely evaluates its components. - -Each component's source file is compiled with these include path directories: - -- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``. -- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies). -- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded). - -When writing a component ------------------------- - -- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component. -- ``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. -- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``. -- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_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. - -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 components you need can significantly reduce your project's compile time. -- When compiling the project's source files (``MAIN_SRCS``), the public header directories of all components included in the build are available. - -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). -- 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. - -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 environmenmt. - -It also defines an overriden custom version of the built-in CMake_ ``project`` function. This function is overriden to add all of the ESP-IDF specific project functionality. - -project function ----------------- - -The custom ``project()`` function performs the following steps: - -- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see `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 produces a ``cmake`` include file and a C header file, to set config macros. If the project configuration changes, cmake will automatically be re-run to reconfigure the project. -- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain. -- Declare the actual cmake-level project by calling the `CMake project function `. -- Load 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`_. -- Include ``project_include.cmake`` files from any components which have them. -- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the cmake `add_library ` function to add a library and then adds source files, compile options, etc. -- Add the final app executable to the build. -- Go back and add 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`` 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 -^^^^^^^^^^^^^^^^^^^^^ - -For components that have build requirements that must be evaluated before any component CMakeLists -files are evaluated, you can create a file called ``project_include.cmake`` in the -component directory. This makefile is included when ``project.cmake`` is evaluating the entire project. - -``project_include.cmake`` 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 ``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. - -Take great care when setting variables or targets in this 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 `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`. - - -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 ``register_config_only_component()``. 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. - -If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration. - -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. - - -``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(CONFIG_FOO_ENABLE_BAR) - -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 - - -``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_NEABLE_LCD_PLOT) - list(APPEND COMPONENT_SRCS "font.c") - endif() - - -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 - - add_custom_command(OUTPUT logo.h - COMMAND bmp2h -i ${COMPONENT_PATH}/logo.bmp -o log.h - DEPENDS ${COMPONENT_PATH}/logo.bmp - VERBATIM) - - add_custom_target(logo DEPENDS logo.h) - add_dependencies(${COMPONENT_NAME} logo) - - set_property(DIRECTORY "${COMPONENT_PATH}" 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 make clean is called which -why it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property. - -(Note: If generating files as part of the project CMakeLists, not a component CMakeLists, use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.) - -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. - -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 your component's CMakeLists, giving the names of the files to embed in this way:: - - set(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:: - - set(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. - -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. - - -Fully Overriding The Component Build Process --------------------------------------------- - -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_PATH} - SOURCE_DIR ${COMPONENT_PATH}/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_PATH}/quirc/libquirc.a) - set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES - ${COMPONENT_PATH}/quirc/lib) - - set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES - "${COMPONENT_PATH}/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.) - -ExternalProject dependencies, clean builds -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CMake has some unusual behaviour around external project builds: - -.. ADDITIONAL_MAKE_CLEAN_FILES_note: - -- `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. - - -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. - -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. - -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 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``). - -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. - -Here is an example minimal "pure CMake" component CMakeLists file for a componen named ``json``:: - - add_library(json STATIC - cJSON/cJSON.c - cJSON/cJSON_Utils.c) - - target_include_directories(json PUBLIC cJSON) - -- This is actually an equivalent version of the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`. -- This file 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. - - -File Globbing & Incremental Builds -================================== - -The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``:: - - set(COMPONENT_SRCDIRS library platform) - -The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually:: - - set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c) - -Usually, CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build. - -The tradeoff 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 CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is "the CMake way" to do things.) - -For project components (not part of ESP-IDF), there are a few options: - -- If keeping your project file in Git, ESP-IDF will automaticallytrack the Git revision and re-run CMake if the revision changes. -- If some components are kept in a third git repo (not the project repo or ESP-IDF repo), you can add calls to the ``git_describe`` function to component CMakeLists to trigger re-runs of CMake. -- If not using Git, you remember to manually run ``idf.py reconfigure`` whenever a source file may change. -- Use ``COMPONENT_SRCS`` to list all source files in project components. - -The best option will depend on your particular project and its users. - -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_SRCS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax. - -However, 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 user. The name of the component library can no longer be overriden by the user. -- ``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 files like linker scripts. -- ``COMPONENT_SUBMODULES``: No longer used by ESP-IDF components, the build system will automatically enumerate all submodules in the repo. -- ``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``: Used to be specified as a list of object files. Now specified as an optional list of source files via ``COMPONENT_SRCS``. -- ``COMPONENT_EXTRA_CLEAN``: Set property `ADDITIONAL_MAKE_CLEAN_FILES` instead but note `CMake has some restrictions around this functionality `. -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See `Fully Overriding The Component CMakeLists` for full details. -- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_. -- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use CMake_ commands instead. See `Controlling Component Compilation`_. - -The following variables no longer have default values: - -- ``COMPONENT_SRCDIRS`` -- ``COMPONENT_ADD_INCLUDEDIRS`` - -It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set). - -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). - -- ``project_description.json`` contains some general information about the 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. - -.. _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 -.. _add_compile_options-cmake: https://cmake.org/cmake/help/v3.5/command/add_compile_options.html -.. _if-cmake: https://cmake.org/cmake/help/v3.5/command/if.html -.. _string-cmake: 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 -.. _language-variables-cmake: 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 - diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 8d3830c8bb..28789b3071 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -1,17 +1,19 @@ Build System ************ -This document explains the Espressif IoT Development Framework build system and the -concept of "components" +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. -Read this document if you want to know how to organise a new ESP-IDF project. +This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components". -We recommend using the esp-idf-template_ project as a starting point for your project. +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. -Using the Build System -====================== +For information relating to the older GNU Make-based build system, see here: -The esp-idf README file contains a description of how to use the build system to build your project. +.. toctree:: + :maxdepth: 1 + + gnu-make-build-system Overview ======== @@ -19,7 +21,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 @@ -28,425 +30,456 @@ 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. -- "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). -- "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. 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 subdirectory ``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 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. +- ``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:`/get-started/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. + +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. + +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 'GNU Make' + 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_: runnning ``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 reconfiguring. + +If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` subcommands - 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. + +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. 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 set 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. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then 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. - 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 "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. 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) + + set(MAIN_SRCS main/src1.c main/src2.c) + + include($ENV{IDF_PATH}/tools/cmake/project.cmake) + project(myProject) -Mandatory Project Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Mandatory Parts +--------------- + +The inclusion of these four lines, in the order shown above, is necessary for every project: + +- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version 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. +- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" subdirectory, but this structure is encouraged. + + It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below. + + ``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else). +- ``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. +- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, 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. 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 ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list can be very short. +- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically added to every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this variable is set to the minimal set of core "system" components needed for any ESP-IDF project. Usually, you would not change this variable in your project. -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 -------------------- +Component CMakeLists Files +========================== -Each project contains one or more components, which can either be part of esp-idf or added from other component directories. +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 (see above). -A component is any directory that contains a ``component.mk`` file. +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 subdirectories 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 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 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Minimal Component CMakeLists +---------------------------- -The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set: +.. highlight:: cmake -- 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. +The minimal component ``CMakeLists.txt`` file is as follows:: -See `example component makefiles`_ for more complete component makefile examples. + set(COMPONENT_SRCDIRS ".") + set(COMPONENT_ADD_INCLUDEDIRS "include") + register_component() -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_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library. +- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for any component which requires this component, and also the main source files. +- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if function `_ or similar), this component will not be part of the build. -.. component variables: +Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute. + +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_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. 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. -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`. +- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. 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. +- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. :doc:`More information here `. +- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``) -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. +If you modify any of these variables inside ``CMakeLists.txt`` 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component directory, which will be added to the include search path for + all other components which require this one. If an include directory is only needed to compile this specific component, + add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead. +- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If this component has a header file in a ``COMPONENT_ADD_INCLUDEDIRS`` directory that includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive. -The following variables can be set inside ``component.mk`` to control build settings across the entire project: + The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``. -- ``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_REQUIRES``: 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. + If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead. + See `Component Requirements` for more details. 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_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements` for more details. +- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the component directory, which will be searched for source files (``*.cpp``, + ``*.c``, ``*.S``). Set this to specify a list of directories which contain source files. +- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled. + If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add include paths for use when compiling other components or the source files listed in ``MAIN_SRCS``. -To apply compilation flags to a single source file, you can add a variable override as a target, ie:: +Controlling Component Compilation +--------------------------------- - apps/dhcpserver.o: CFLAGS += -Wno-unused-variable +.. highlight:: cmake + +To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function:: + + component_compile_options(-Wno-unused-variable) + +This is a wrapper around the CMake `target_compile_options`_ command. + +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. -Component Configuration ------------------------ +When using these commands, place them after the ``register_component()`` line 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 +======================= + +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 ------------------------- +======================== -ESP-IDF build systems adds the following C preprocessor definitions on the command line: +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`` — ESP-IDF version, see `Preset Component Variables`_ for more details. +- ``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. -Build Process Internals +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: + +- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``. +- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies). +- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded). + +When writing a component +------------------------ + +- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component. +- ``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. +- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``. +- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_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. + +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: + - 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 components you need can significantly reduce your project's compile time. +- When compiling the project's source files (``MAIN_SRCS``), the public header directories (``COMPONENT_ADD_INCLUDEDIRS`` list) of all components included in the build are available. -- "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. +.. _component-requirements-implementation: -To better understand the project make process, have a read through the ``project.mk`` file itself. +Requirements in the build system implementation +----------------------------------------------- -Second Level: Component Makefiles -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- 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). +- 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. -- 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. +Build Process Internals +======================= -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. +For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`. -Running Make Non-Interactively ------------------------------- +project.cmake contents +---------------------- -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). +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 environmenmt. -Setting ``BATCH_BUILD`` implies the following: +It also defines an overriden custom version of the built-in CMake_ ``project`` function. This function is overriden to add all of the ESP-IDF specific project functionality. -- 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. +project function +---------------- -Debugging The Make Process --------------------------- +The custom ``project()`` function performs the following steps: -Some tips for debugging the esp-idf build system: +- 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 produces a ``cmake`` include file and a C header file, to set config macros. If the project configuration changes, cmake will automatically be re-run to reconfigure the project. +- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain. +- Declare the actual cmake-level project by calling the `CMake project function `_. +- Load 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`_. +- Include ``project_include.cmake`` files from any components which have them. +- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the cmake `add_library `_ function to add a library and then adds source files, compile options, etc. +- Add the final app executable to the build. +- Go back and add 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`` 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: 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`. - -Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles. +If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``. 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. +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. -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. +``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". -``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 ``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. -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! +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 `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`. -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. +Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``register_config_only_component()``. 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 ---------------------------- +If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration. + +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``:: @@ -455,17 +488,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(CONFIG_FOO_ENABLE_BAR) -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: @@ -488,28 +519,24 @@ 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_NEABLE_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.) 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 @@ -518,104 +545,304 @@ 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_PATH}/logo.bmp -o log.h + DEPENDS ${COMPONENT_PATH}/logo.bmp + VERBATIM) - graphics_lib.o: logo.h + add_custom_target(logo DEPENDS logo.h) + add_dependencies(${COMPONENT_NAME} logo) - logo.h: $(COMPONENT_PATH)/logo.bmp - bmp2h -i $^ -o $@ + set_property(DIRECTORY "${COMPONENT_PATH}" 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: If generating files as part of the project CMakeLists, not a component CMakeLists, use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.) -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_REQUIRES`` list to ensure that the components were built -in-order. +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. 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 set a variable ``COMPONENT_EMBED_FILES`` in your component's CMakeLists, giving the names of the files to embed in this way:: - COMPONENT_EMBED_FILES := server_root_cert.der + set(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:: +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 + set(COMPONENT_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. +.. _component-build-full-override: -Fully Overriding The Component Makefile ---------------------------------------- +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_PATH} + SOURCE_DIR ${COMPONENT_PATH}/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) -.. _esp-idf-template: https://github.com/espressif/esp-idf-template -.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html + set_target_properties(quirc PROPERTIES IMPORTED_LOCATION + ${COMPONENT_PATH}/quirc/libquirc.a) + set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES + ${COMPONENT_PATH}/quirc/lib) + set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES + "${COMPONENT_PATH}/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.) + +.. _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. -Save flash arguments --------------------- +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:: +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. - --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin +After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files: -Then use flash arguments as the arguemnts for esptool write_flash arguments:: +- ``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. - 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 +.. 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``). + +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. + + +File Globbing & Incremental Builds +================================== + +.. highlight:: cmake + +The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``:: + + set(COMPONENT_SRCDIRS library platform) + +The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually:: + + set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c) + +Usually, CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build. + +The tradeoff 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 CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is "the CMake way" to do things.) + +For project components (not part of ESP-IDF), there are a few 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 repo (not the project repo or ESP-IDF repo), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to trigger re-runs of CMake. +- If not using Git, you remember to manually run ``idf.py reconfigure`` whenever a source file may change. +- Use ``COMPONENT_SRCS`` to list all source files in project components. + +The best option will depend on your particular project and its users. + +.. _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_SRCS`` 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 user. The name of the component library can no longer be overriden by the user. +- ``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 files like linker scripts. +- ``COMPONENT_SUBMODULES``: No longer used by ESP-IDF components, the build system will automatically enumerate all submodules in the repo. +- ``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``: Used to be specified as a list of object files. Now specified as an optional list of source files via ``COMPONENT_SRCS``. +- ``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_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set). + +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. +- ``sdkconfig.json`` is a JSON-formatted version of the project configuration values. + +.. _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/project.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 diff --git a/docs/en/api-guides/cmake-preview-index.rst b/docs/en/api-guides/cmake-preview-index.rst deleted file mode 100644 index 22e94c67a5..0000000000 --- a/docs/en/api-guides/cmake-preview-index.rst +++ /dev/null @@ -1,10 +0,0 @@ -CMake-Based Build System Preview -******************************** - -.. toctree:: - :maxdepth: 1 - - Getting Started <../get-started/index-cmake> - Linux Setup <../get-started/linux-setup-cmake> - Windows Setup <../get-started/windows-setup-cmake> - Build System Guide diff --git a/docs/en/api-guides/console.rst b/docs/en/api-guides/console.rst index 490c9948d4..c012c49d1d 100644 --- a/docs/en/api-guides/console.rst +++ b/docs/en/api-guides/console.rst @@ -15,7 +15,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 47cfd89c07..ce6a1afad0 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 configuration menu of the application (`idf.py menuconfig`). 1. Core dump data destination (`Components -> ESP32-specific config -> Core dump destination`): @@ -81,6 +81,6 @@ 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. Ofsset of coredump partition in flash (type "make partition_table" to see it). + * --off,-o OFF. Ofsset 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". * --print-mem,-m Print memory dump. Used only with "info_corefile". diff --git a/docs/en/api-guides/gnu-make-build-system.rst b/docs/en/api-guides/gnu-make-build-system.rst new file mode 100644 index 0000000000..1f9c5b9bdf --- /dev/null +++ b/docs/en/api-guides/gnu-make-build-system.rst @@ -0,0 +1,51 @@ +GNU Make Build System +********************* + +This document contains a "cheat sheet" for users of the older ESP-IDF GNU Make build system and the newer CMake build system. + +Currently, this version of ESP-IDF contains support for both build systems, and either build system can be used. However, the rest of the documentation for this version has been updated for the CMake build system. + +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view dedicated documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. + +Dependencies +============ + +For Linux & Mac OS, the dependencies for the GNU Make and CMake-based build systems are very similar. The only additional tool required for GNU Make is ``make`` 3.81 or newer. This is pre-installed on Mac OS and can be installed on Linux via the distribution package manager. + +For Windows, the requirements are different as the GNU Make based build system requires MSYS2 for a Unix compatibility layer. Consult the Getting Started docs for IDF v3.0 for steps to set up MSYS2. + +Cheat Sheet +=========== + +Equivalents between GNU make-based build system commands and the CMake-based build system: + +==================== ================== ================= +Summary CMake-based GNU Make based +==================== ================== ================= +Configure project idf.py menuconfig make menuconfig +Build project idf.py build make +Flash project idf.py flash make flash +Monitor project idf.py monitor make monitor +Clean project idf.py fullclean make clean +==================== ================== ================= + +To override the default build directory: + +- CMake based: ``idf.py -b (directory) build`` +- GNU Make based: ``make BUILD_DIR_BASE=(directory)``. + +To set the serial port for flashing/monitoring: + +- CMake based: ``idf.py -p (port) flash`` +- GNU Make based: ``make flash ESPPORT=/dev/ttyUSB0``, or set in ``menuconfig``. + +To set the baud rate for flashing: + +- CMake based: ``idf.py -b 921600 flash`` +- GNU Make based: ``make flash ESPBAUD=921600``, or set in ``menuconfig``. + +Porting GNU Make Based Components to CMake +========================================== + +See :ref:`gnu-make-to-cmake`. 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 12e5560b00..e7d6f5dfaf 100644 --- a/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst +++ b/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst @@ -7,7 +7,7 @@ Set up OpenOCD ============== -OpenOCD for Windows / MSYS2 is available for download from Github: +OpenOCD for Windows is available for download from Github: https://github.com/espressif/openocd-esp32/releases @@ -16,7 +16,7 @@ Download latest release archive with `win32` in its name, for example `openocd-e Extract the downloaded file in ``~/esp/`` directory. cd ~/esp - unzip /c/Users//Downloads/openocd-esp32-win32-.zip + unzip /c/Users//Downloads/openocd-esp32-win32-.zip Next Steps ========== diff --git a/docs/en/get-started/add-idf_path-to-profile-cmake.rst b/docs/en/get-started/add-idf_path-to-profile-cmake.rst deleted file mode 100644 index b1f1247d10..0000000000 --- a/docs/en/get-started/add-idf_path-to-profile-cmake.rst +++ /dev/null @@ -1,70 +0,0 @@ -Add IDF_PATH & idf.py PATH to User Profile -========================================== - -.. note:: - The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here`. - -To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables: - -- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF. -- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF). - -To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below. - -.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below. - -.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both. - -.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing. - -.. _add-paths-to-profile-windows-cmake: - -Windows -------- - -To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu. - -On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button. - -You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF. - -- Click ``New...`` to add a new environment variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\myuser\esp\esp-idf``. -- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt. - -If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`. - - -.. _add-idf_path-to-profile-linux-macos-cmake: - -Linux and MacOS ---------------- - -Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to ``~/.profile`` file:: - - export IDF_PATH=~/esp/esp-idf - export PATH="$PATH:$IDF_PATH/tools" - -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. - -To verify idf.py is now on the ``PATH``, you can run the following:: - - which idf.py - -A path like ``${IDF_PATH}/tools/idf.py`` should be printed. - -If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout:: - - export IDF_PATH=~/esp/esp-idf - export PATH="$PATH:$IDF_PATH/tools" - -If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`. 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 60ca434814..f775f901f9 100644 --- a/docs/en/get-started/add-idf_path-to-profile.rst +++ b/docs/en/get-started/add-idf_path-to-profile.rst @@ -1,39 +1,37 @@ -Add IDF_PATH to User Profile -============================ +Add IDF_PATH & idf.py PATH to User Profile +========================================== -To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below. +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. +To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables: -.. _add-idf_path-to-profile-windows: +- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF. +- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF). + +To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below. + +.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below. + +.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both. + +.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing. + +.. _add-paths-to-profile-windows: Windows ------- -The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window. +To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu. -#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``. +On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button. -#. 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`` +You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF. -#. Add the ``export`` command to the script file, e.g.:: +- Click ``New...`` to add a new environment variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\myuser\esp\esp-idf``. +- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt. - 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`. +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: @@ -41,11 +39,12 @@ If you got here from section :ref:`get-started-setup-path`, while installing s/w Linux and MacOS --------------- -Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file:: +Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to ``~/.profile`` file:: export IDF_PATH=~/esp/esp-idf + export PATH="$PATH:$IDF_PATH/tools" -Log off and log in back to make this change effective. +Log off and log in back to make this change effective. .. note:: @@ -57,8 +56,15 @@ Run the following command to check if ``IDF_PATH`` is set:: 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:: +To verify idf.py is now on the ``PATH``, you can run the following:: + + which idf.py + +A path like ``${IDF_PATH}/tools/idf.py`` should be printed. + +If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout:: export IDF_PATH=~/esp/esp-idf + export PATH="$PATH:$IDF_PATH/tools" 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`. diff --git a/docs/en/get-started/eclipse-setup-windows.rst b/docs/en/get-started/eclipse-setup-windows.rst deleted file mode 100644 index a924d2dc7a..0000000000 --- a/docs/en/get-started/eclipse-setup-windows.rst +++ /dev/null @@ -1,78 +0,0 @@ -********************** -Eclipse IDE on Windows -********************** - -Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below. - -(For OS X and Linux instructions, see the :doc:`Eclipse IDE page `.) - -Installing Eclipse IDE -====================== - -Follow the steps under :ref:`Installing Eclipse IDE ` for all platforms. - -.. _eclipse-windows-setup: - -Setting up Eclipse on Windows -============================= - -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" uncheck "Show only available toolchains that support this platform". - -* On the extended list that appears, choose "Cygwin GCC". Then click Finish. - -*Note: you may see warnings in the UI that Cygwin GCC Toolchain could not be found. This is OK, we're going to reconfigure Eclipse to find our toolchain.* - -Project Properties ------------------- - -* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu. - -* Click on the "C/C++ Build" properties page (top-level): - - * Uncheck "Use default build command" and enter this for the custom build command: ``python ${IDF_PATH}/tools/windows/eclipse_make.py``. - -* 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. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/MyUser/Development/esp-idf*. - - * Edit the PATH environment variable. Delete the existing value and replace it with ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (If you installed msys32 to a different directory then you'll need to change these paths to match). - -* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros, etc." property page: - - * Click the "Providers" tab - - * In the list of providers, click "CDT GCC Built-in Compiler Settings Cygwin". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``. - - * In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern, and wrap remaining part with brackets. This means the full Compiler command pattern should be ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))`` - - -Building in Eclipse -------------------- - -Continue from :ref:`Building in Eclipse ` for all platforms. - -Technical Details -================= - -**Of interest to Windows gurus or very curious parties, only.** - -Explanations of the technical reasons for some of these steps. You don't need to know this to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support: - -* The xtensa-esp32-elf-gcc cross-compiler is *not* a Cygwin toolchain, even though we tell Eclipse that it is one. This is because msys2 uses Cygwin and supports Unix-style paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-esp32-elf-gcc reports to the Eclipse "built-in compiler settings" function that its built-in include directories are all under ``/usr/``, which is a Unix/Cygwin-style path that Eclipse otherwise can't resolve. By telling Eclipse the compiler is Cygwin, it resolves these paths internally using the ``cygpath`` utility. - -* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason, the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse. diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst index 9ceb3c7791..8b8c34c3bd 100644 --- a/docs/en/get-started/eclipse-setup.rst +++ b/docs/en/get-started/eclipse-setup.rst @@ -2,108 +2,10 @@ Build and Flash with Eclipse IDE ******************************** -.. _eclipse-install-steps: - -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.) - -Windows Users -============= - -Using ESP-IDF with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide `. - -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. - -* 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. - -* 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. - -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". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``. - -* In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern. This means the full Compiler command pattern should be ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)`` - -.. _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. - -Related Documents ------------------ - -.. toctree:: - :maxdepth: 1 - - eclipse-setup-windows +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. +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/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst index c96c2e546a..363de1ccee 100644 --- a/docs/en/get-started/establish-serial-connection.rst +++ b/docs/en/get-started/establish-serial-connection.rst @@ -125,7 +125,4 @@ If you see some legible log, it means serial connection is working and you are r 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`. -(If you are following the CMake preview documentation, `go back to the CMake-specific section instead <: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/idf-monitor.rst b/docs/en/get-started/idf-monitor.rst index e1ec23cb3d..30258de2fb 100644 --- a/docs/en/get-started/idf-monitor.rst +++ b/docs/en/get-started/idf-monitor.rst @@ -2,7 +2,7 @@ IDF Monitor *********** -The idf_monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF. +The idf_monitor tool is a Python program which runs when the ``idf.py monitor`` target is invoked in IDF. It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific xfeatures. @@ -66,7 +66,7 @@ By default, if an esp-idf app crashes then the panic handler prints registers an Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required. -To enable the gdbstub, run ``make menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``. +To enable the gdbstub, run ``idf.py menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``. If this option is enabled and idf_monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.) @@ -78,9 +78,9 @@ Behind the scenes, the command idf_monitor runs is:: Quick Compile and Flash ======================= -The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``make flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing. +The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``idf.py flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing. -The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``make app-flash`` target, then resume idf_monitor. This is similar to ``make flash``, but only the main app is compiled and reflashed. +The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py flash``, but only the main app is compiled and reflashed. Quick Reset @@ -114,6 +114,7 @@ This program can still be run, via ``make simple_monitor``. idf_monitor is based on miniterm and shares the same basic keyboard shortcuts. +.. note:: This target only works in the GNU Make based build system, not the CMake-based build system preview. Known Issues with idf_monitor ============================= diff --git a/docs/en/get-started/index-cmake.rst b/docs/en/get-started/index-cmake.rst deleted file mode 100644 index 9bc7f0773a..0000000000 --- a/docs/en/get-started/index-cmake.rst +++ /dev/null @@ -1,347 +0,0 @@ -*************************************** -Get Started with the CMake build system -*************************************** - -.. note:: - The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). For a stable experience, follow the :doc:`original (non-cmake) setup guide here`. - -This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. - -Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards. - - -Introduction -============ - -ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. - -Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features. - - -What You Need -============= - -To develop applications for ESP32 you need: - -* **PC** loaded with either Windows, Linux or Mac operating system -* **Toolchain** to build the **Application** for ESP32 -* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain** -* A text editor to write programs (**Projects**) in C, e.g. `Eclipse `_ -* The **ESP32** board itself and a **USB cable** to connect it to the **PC** - -.. figure:: ../../_static/what-you-need.png - :align: center - :alt: Development of applications for ESP32 - :figclass: align-center - - Development of applications for ESP32 - -Preparation of development environment consists of three steps: - -1. Setup of **Toolchain** -2. Getting of **ESP-IDF** from GitHub -3. Installation and configuration of **Eclipse** - -You may skip the last step, if you prefer to use different editor. - -Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps: - -1. Configuration of a **Project** and writing the code -2. Compilation of the **Project** and linking it to build an **Application** -3. Flashing (uploading) of the **Application** to **ESP32** -4. Monitoring / debugging of the **Application** - -See instructions below that will walk you through these steps. - - -Guides -====== - -If you have one of ESP32 development boards listed below, click on provided links to get you up and running. - -.. toctree:: - :maxdepth: 1 - - ESP32 DevKitC - ESP-WROVER-KIT - ESP32-PICO-KIT - -If you have different board, move to sections below. - - -.. _get-started-setup-toolchain-cmake: - -Setup Toolchain -=============== - -The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow 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/windows-setup-cmake.html - -.. |linux-logo| image:: ../../_static/linux-logo.png - :target: ../get-started/linux-setup-cmake.html - -.. |macos-logo| image:: ../../_static/macos-logo.png - :target: ../get-started/macos-setup-cmake.html - -.. _Windows: ../get-started/windows-setup-cmake.html -.. _Linux: ../get-started/linux-setup-cmake.html -.. _Mac OS: ../get-started/macos-setup-cmake.html - -.. note:: - - We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands. - -Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`. - -Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf-cmake`. - - -.. _get-started-get-esp-idf-cmake: - -Get ESP-IDF -=========== - -.. highlight:: bash - -Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository `_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command:: - - cd ~/esp - git clone --recursive https://github.com/espressif/esp-idf.git - -ESP-IDF will be downloaded into ``~/esp/esp-idf``. - -.. 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/esp-idf - git submodule update --init - - -.. _get-started-setup-path-cmake: - -Setup Paths for ESP-IDF -======================= - -The build system and tools find ESP-IDF using the ``IDF_PATH`` environment variable, or by running the ``idf.py`` utility in the tools/ directory of the esp-idf source. - -These paths should be set up as environment variables on your computer, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` and updating ``PATH`` in your user profile. To do so, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile-cmake`. - -.. _get-started-start-project-cmake: - -Start a Project -=============== - -Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. - -Copy :example:`get-started/hello_world` to ``~/esp`` directory. You can do this via your operating system's file manager (like Windows Explorer). Or for Linux and MacOS, to do it from a Bash shell:: - - cd ~/esp - cp -r $IDF_PATH/examples/get-started/hello_world . - - -You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects. - -.. important:: - - The esp-idf build system does not support spaces in paths to esp-idf or to projects. - - -.. _get-started-connect-cmake: - -Connect -======= - -You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step. - - -.. _get-started-configure-cmake: - -Configure -========= - -Open a terminal window (or a Windows Command Prompt), go to directory of the ``hello_world`` application by typing ``cd ~/esp/hello_world`` or ```cd \Users\esp\hello_world`` for Windows. Then start the project configuration utility ``menuconfig``:: - - cd ~/esp/hello_world - idf.py menuconfig - -.. note:: - The first time you run ``idf.py`` for a given ESP-IDF project, CMake will run to configure the project. If any software tools or other requirements like environment variables are not configured correctly, this will produce a configuration error at this stage. - -.. note:: - The previous (non-CMake) build system instructions would have told you to run ``make`` here, but the CMake-based system doesn't require use of ``make``. - -If previous steps have been done correctly, the following menu will be displayed: - -.. 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 application by selecting ``< Exit >``. - -.. note:: - - On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. - (See :doc:`establish-serial-connection` for full details.) - -Here are couple of tips on navigation and use of ``menuconfig``: - -* Use up & down arrow keys to navigate the menu. -* Use Enter key to go into a submenu, Escape key to go out or to exit. -* Type ``?`` to see a help screen. Enter key exits the help screen. -* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``" -* Pressing ``?`` while highlighting a configuration item displays help about that item. -* Type ``/`` to search the configuration items. - -.. _get-started-build-flash-cmake: - -Build and Flash -=============== - -Now you can build and flash the application. To build (but not flash) run:: - - idf.py build - -This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries. - -To flash these built firmware files to your ESP32 board, run:: - - idf.py -p flash - -For ````, specify the connected ESP32's serial port like ``/dev/ttyUSB0`` (Linux), ``/dev/cu.USBx`` (MacOS) or ``COM1`` (Windows). - -.. 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 there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start. - -.. note:: - It's not necessary to run ``idf.py build`` before ``idf.py flash``, then flash step will automatically build the firmware if it needs to be built. - -.. _get-started-build-monitor-cmake: - -Monitor -======= - -To see if "hello_world" application is indeed running, type ``idf.py monitor``. This command is launching :doc:`IDF Monitor ` application:: - - $ idf.py 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 - ... - -Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. :: - - ... - 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 the monitor use shortcut ``Ctrl+]``. - -.. note:: - - If instead of the messages above, you see a random garbage similar to:: - - e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA - ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp - - or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. - -To execute ``idf.py flash`` and then ``idf.py monitor``, you can run ``idf.py flash monitor``. Check section :doc:`IDF Monitor ` for handy shortcuts and more details on using this application. - -.. note:: - At the moment not all of the idf_monitor shortcuts work correctly with the CMake-based build system. - -That's all what you need to get started with ESP32! - -Now you are ready to try some other :idf:`examples`, or go right to developing your own applications. - - -Updating ESP-IDF -================ - -After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`. - -Another solution is to update only what has changed. This method is useful if you have slow connection to the GiHub. To do the update run the following commands:: - - cd ~/esp/esp-idf - git pull - git submodule update --init --recursive - -The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC. - -If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run:: - - cd ~/esp - git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1 - cd esp-idf-v2.1/ - git checkout v2.1 - git submodule update --init --recursive - -After that remember to :doc:`add-idf_path-to-profile-cmake`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location. - - -Related Documents -================= - -.. toctree:: - :maxdepth: 1 - - add-idf_path-to-profile-cmake - establish-serial-connection - make-project - idf-monitor - toolchain-setup-scratch diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index dffffb929f..b87a55076a 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -2,7 +2,10 @@ Get Started *********** -This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards. +This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards. + +.. note:: + The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. Introduction @@ -99,13 +102,12 @@ The quickest way to start development with ESP32 is by installing a prebuilt too .. note:: - We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands. + We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and Mac OS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands. Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`. Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`. - .. _get-started-get-esp-idf: Get ESP-IDF @@ -115,26 +117,42 @@ Get ESP-IDF Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository `_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command:: + mkdir -p ~/esp cd ~/esp git clone --recursive https://github.com/espressif/esp-idf.git ESP-IDF will be downloaded into ``~/esp/esp-idf``. +.. highlight:: batch + +For Windows Command Prompt users, the equivalent commands are:: + + mkdir %userprofile%\esp + cd %userprofile%\esp + git clone --recursive https://github.com/espressif/esp-idf.git + +.. highlight:: bash .. 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/esp-idf + cd esp-idf git submodule update --init .. _get-started-setup-path: -Setup Path to ESP-IDF -===================== +Setup Environment Variables +=========================== -The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile`. +ESP-IDF requires two environment variables to be set for normal operation: +- ``IDF_PATH`` should be set to the path to the ESP-IDF root directory. +- ``PATH`` should include the path to the ``tools`` directory inside the same ``IDF_PATH`` directory. + +These two variables should be set up on your PC, otherwise projects will not build. + +Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile`. .. _get-started-start-project: @@ -143,13 +161,24 @@ Start a Project Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. +.. highlight:: bash + Copy :example:`get-started/hello_world` to ``~/esp`` directory:: cd ~/esp cp -r $IDF_PATH/examples/get-started/hello_world . +.. highlight:: batch + +For Windows Command Prompt users, the equivalent commands are:: + + cd %userprofile%\esp + xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world + You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects. +It is also possible to build examples in-place, without copying them first. + .. important:: The esp-idf build system does not support spaces in paths to esp-idf or to projects. @@ -168,12 +197,27 @@ You are almost there. To be able to proceed further, connect ESP32 board to PC, Configure ========= +.. highlight:: bash + Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``:: cd ~/esp/hello_world - make menuconfig + idf.py menuconfig -If previous steps have been done correctly, the following menu will be displayed: +.. highlight:: batch + +For Windows Command Prompt users:: + + cd %userprofile%\esp + idf.py menuconfig + +.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path`. + +.. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work. You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files. + +.. note:: Linux users, if your default version of Python is 3.x then you may need to run ``python2 idf.py`` instead. + +If previous steps have been done correctly, the following menu will be displayed: .. figure:: ../../_static/project-configuration.png :align: center @@ -182,13 +226,6 @@ If previous steps have been done correctly, the following menu will be displayed 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 application by selecting ``< Exit >``. - -.. note:: - - On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. - (See :doc:`establish-serial-connection` for full details.) - Here are couple of tips on navigation and use of ``menuconfig``: * Use up & down arrow keys to navigate the menu. @@ -202,15 +239,18 @@ Here are couple of tips on navigation and use of ``menuconfig``: If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``. - .. _get-started-build-flash: Build and Flash =============== +.. highlight:: bash + Now you can build and flash the application. Run:: - make flash + idf.py -p PORT flash + +Replace PORT with the name of your ESP32 board's serial port. On Windows, serial ports have names like ``COM1``. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. (See :doc:`establish-serial-connection` for full details.) This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board. @@ -218,35 +258,38 @@ This will compile the application and all the ESP-IDF components, generate bootl :: - 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. + 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... + Leaving... + Hard resetting via RTS pin... -If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start. +If there are no issues, at the end of build process, you should see messages describing progress of flashing the project binary image onto the ESP32. Finally, the module will be reset and "hello_world" application will be running there. -If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. +If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide `. .. _get-started-build-monitor: @@ -254,10 +297,11 @@ If you'd like to use the Eclipse IDE instead of running ``make``, check out the Monitor ======= -To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor ` application:: +To see if "hello_world" application is indeed running, type ``idf.py monitor``. This command is launching :doc:`IDF Monitor ` application:: - $ make monitor - MONITOR + $ idf.py 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 @@ -276,7 +320,7 @@ Several lines below, after start up and diagnostic log, you should see "Hello wo Restarting in 8 seconds... Restarting in 7 seconds... -To exit the monitor use shortcut ``Ctrl+]``. +To exit the monitor use shortcut ``Ctrl+]``. .. note:: @@ -285,11 +329,19 @@ To exit the monitor use shortcut ``Ctrl+]``. e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp - or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. + or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency. -To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor ` for handy shortcuts and more details on using this application. +.. note:: -That's all what you need to get started with ESP32! + You can combine building, flashing and monitoring into one step as follows:: + + idf.py -p PORT flash monitor + +Check the section :doc:`IDF Monitor ` for handy shortcuts and more details on using the monitor. + +Check the section :ref:`idf.py` for a full reference of ``idf.py`` commands and options. + +That's all what you need to get started with ESP32! Now you are ready to try some other :idf:`examples`, or go right to developing your own applications. @@ -299,14 +351,26 @@ Updating ESP-IDF After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`. +.. highlight:: bash + Another solution is to update only what has changed. This method is useful if you have a slow connection to GitHub. To do the update run the following commands:: cd ~/esp/esp-idf git pull git submodule update --init --recursive +.. highlight:: batch + +For Windows Command Prompt users:: + + cd %userprofile%\esp + git pull + git submodule update --init --recursive + The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC. +.. highlight:: bash + If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run:: cd ~/esp @@ -315,8 +379,22 @@ If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run:: git checkout v2.1 git submodule update --init --recursive +.. highlight:: batch + +For Windows Command Prompt users:: + + cd %userprofile%\esp + git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1 + cd esp-idf-v2.1/ + git checkout v2.1 + git submodule update --init --recursive + After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location. +.. note:: + + Different versions of ESP-IDF may have different setup or prerequisite requirements, or require different toolchain versions. If you experience any problems, carefully check the Getting Started documentation for the version you are switching to. + Related Documents ================= diff --git a/docs/en/get-started/linux-setup-cmake.rst b/docs/en/get-started/linux-setup-cmake.rst deleted file mode 100644 index 2e3bbdbbe1..0000000000 --- a/docs/en/get-started/linux-setup-cmake.rst +++ /dev/null @@ -1,113 +0,0 @@ -************************************* -Setup for cmake on Linux -************************************* - -.. note:: - The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here`. - -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 cmake ninja-build ccache - -- Ubuntu and Debian:: - - sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache - -.. note:: - CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake") - -Toolchain Setup -=============== - -ESP32 toolchain for Linux is available for download from Espressif website: - -- for 64-bit Linux: - - https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz - -- for 32-bit Linux: - - https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz - -1. Download this file, then extract it in ``~/esp`` directory:: - - mkdir -p ~/esp - cd ~/esp - tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz - -.. _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="$PATH:$HOME/esp/xtensa-esp32-elf/bin" - - 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="$PATH:$HOME/esp/xtensa-esp32-elf/bin"' - - Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. - - .. note:: - - If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. - -3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set:: - - printenv PATH - - You are looking for similar result containing toolchain's path at the end of displayed string:: - - $ printenv PATH - /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/esp/xtensa-esp32-elf/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-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/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst index b2cb96ec37..1c1d287e89 100644 --- a/docs/en/get-started/linux-setup-scratch.rst +++ b/docs/en/get-started/linux-setup-scratch.rst @@ -2,6 +2,9 @@ Setup Linux Toolchain from Scratch ********************************** +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. + 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`. @@ -10,14 +13,20 @@ 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 cmake ninja-build ccache + - Ubuntu and Debian:: - sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial + sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache +.. note:: + CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake") Compile the Toolchain from Source ================================= @@ -26,19 +35,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:: - 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:: diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst index 8004c37ee7..3736191bc8 100644 --- a/docs/en/get-started/linux-setup.rst +++ b/docs/en/get-started/linux-setup.rst @@ -2,6 +2,8 @@ Standard Setup of Toolchain for Linux ************************************* +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. Install Prerequisites ===================== @@ -10,16 +12,18 @@ 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 pyserial + sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache - Ubuntu and Debian:: - sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-serial + sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache +.. note:: + CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake") Toolchain Setup =============== @@ -79,7 +83,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: diff --git a/docs/en/get-started/macos-setup-cmake.rst b/docs/en/get-started/macos-setup-cmake.rst deleted file mode 100644 index ce5623a53e..0000000000 --- a/docs/en/get-started/macos-setup-cmake.rst +++ /dev/null @@ -1,64 +0,0 @@ -************************* -Setup for CMake on Mac OS -************************* - -.. note:: - The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is `here <:doc:macos-setup>`. - -Install Prerequisites -===================== - -- install pip:: - - sudo easy_install pip - -- install pyserial:: - - sudo pip install pyserial - -- install CMake & Ninja build: - - If you have HomeBrew, you can run:: - - brew install cmake ninja - - Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation. - -- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew, this can be done via ``brew install ccache``. - -Toolchain Setup -=============== - -ESP32 toolchain for macOS is available for download from Espressif website: - -https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz - -Download this file, then extract it in ``~/esp`` directory:: - - mkdir -p ~/esp - cd ~/esp - tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz - -.. _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=$PATH:$HOME/esp/xtensa-esp32-elf/bin - -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=$PATH:$HOME/esp/xtensa-esp32-elf/bin" - -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-cmake`. - -.. _cmake: https://cmake.org/ -.. _ninja: https://ninja-build.org/ -.. _ccache: https://ccache.samba.org/ diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index 7516158a1d..53b8a99476 100644 --- a/docs/en/get-started/macos-setup-scratch.rst +++ b/docs/en/get-started/macos-setup-scratch.rst @@ -2,6 +2,16 @@ Setup Toolchain for Mac OS from Scratch *************************************** +Package Manager +=============== + +To set up the toolchain from scratch, rather than `downloading a precocmpiled 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 + Install Prerequisites ===================== @@ -13,24 +23,28 @@ Install Prerequisites sudo pip install 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:: diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst index 14764601b5..a699c3bef6 100644 --- a/docs/en/get-started/macos-setup.rst +++ b/docs/en/get-started/macos-setup.rst @@ -2,6 +2,9 @@ Standard Setup of Toolchain for Mac OS ************************************** +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. + Install Prerequisites ===================== @@ -13,6 +16,19 @@ Install Prerequisites sudo pip install 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 Mac OS 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_. Toolchain Setup =============== @@ -47,7 +63,6 @@ Next Steps To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. - Related Documents ================= @@ -55,3 +70,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/windows-setup-cmake.rst b/docs/en/get-started/windows-setup-cmake.rst deleted file mode 100644 index 0545e7d501..0000000000 --- a/docs/en/get-started/windows-setup-cmake.rst +++ /dev/null @@ -1,58 +0,0 @@ -*************************************** -Setup for cmake on Windows -*************************************** - -.. note:: - The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here`. - -.. note:: - The CMake-based build system is only supported on 64-bit versions of Windows. - -Introduction -============ - -Unlike the conventional ESP-IDF make-based build environment, cmake does not require MSYS2 or another GNU-compatible environment (like Cygwin) for building. You can build with cmake from Windows Command Prompt, or from an IDE with cmake support. - -ESP-IDF Tools Installer -======================= - -The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL: - -https://dl.espressif.com/dl/esp-idf-tools-setup-1.0.exe - -The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and mconf configuration tool. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer. - -By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths. - -Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself. - -Installing Git -============== - -The ESP-IDF tools does not include Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a Git command line for Windows (along with the Git-Bash terminal) from https://gitforwindows.org/. - -If you prefer to use a different graphical Git client, then you can install one of these instead - you will need to translate the Git commands in the getting started guide for use with your chosen Git client. - - -Related Documents -================= - -.. toctree:: - :maxdepth: 1 - - windows-setup-scratch-cmake - -Manual Installation -^^^^^^^^^^^^^^^^^^^ - -Optionall - -Next Steps -========== - -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`. - - -.. _cmake: https://cmake.org/download/ -.. _ninja: https://ninja-build.org/ -.. _Python: https://www.python.org/downloads/windows/ diff --git a/docs/en/get-started/windows-setup-scratch-cmake.rst b/docs/en/get-started/windows-setup-scratch-cmake.rst deleted file mode 100644 index a4e12ae5cf..0000000000 --- a/docs/en/get-started/windows-setup-scratch-cmake.rst +++ /dev/null @@ -1,85 +0,0 @@ -*************************************** -Setup for cmake on Windows 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:`ESP-IDF Tools Installer ` automates the steps mentioned below. - -To quickly setup the toolchain and other tools in standard way, using the installer, proceed to section :doc:`windows-setup-cmake`. - -Note that, unlike the previous "GNU Make" based ESP-IDF build environment, the cmake environment does not include or require MSYS2 or any other Unix compatibility layer. - -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 pyserial - -MConf -^^^^^ - -Download the ESP-IDF customized version of the configuration tool mconf from the `mconf releases page `. - -This tool will also need to be unzipped to a directory which is then `added to your Path `. - -Toolchain Setup -=============== - -Download the precompiled Windows toolchain from dl.espressif.com: - -https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip - -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-cmake`. - - -.. _cmake: https://cmake.org/download/ -.. _ninja: https://ninja-build.org/ -.. _ninja-dl: https://github.com/ninja-build/ninja/releases -.. _Python: https://www.python.org/downloads/windows/ diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst index 4c772eeb3f..9088976130 100644 --- a/docs/en/get-started/windows-setup-scratch.rst +++ b/docs/en/get-started/windows-setup-scratch.rst @@ -2,91 +2,81 @@ 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. +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 in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`. +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: - -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 -============================================ - -If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: - -https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. .. note:: - If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download. + Unlike the previous "GNU Make" based ESP-IDF build environment, the cmake environment does not include or require MSYS2 or any other Unix compatibility layer. -.. important:: +Tools +===== - 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). +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 pyserial + +MConf +^^^^^ + +Download the ESP-IDF customized version of the configuration tool mconf from the `mconf releases page `_. + +This tool will also need to be unzipped to a directory which is then `added to your Path `_. + +Toolchain Setup +=============== + +Download the precompiled Windows toolchain from dl.espressif.com: + +https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip + +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 @@ -94,22 +84,5 @@ 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. - -.. _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 +.. _ninja: https://ninja-build.org/ +.. _Python: https://www.python.org/downloads/windows/ diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index e2adebde29..c9e1b70115 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -2,64 +2,61 @@ Standard Setup of Toolchain for Windows *************************************** +.. note:: + This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. + +.. note:: + The CMake-based build system is only supported on 64-bit versions of Windows. + 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 Git, a cross-compiler and the CMake build tool. We'll go over each one in this document. +For this Getting Started we're going to use a 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 a GNU Make based build system, which required the MSYS2_ Unix compatibility environment on Windows. This is no longer required. -The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com: +ESP-IDF Tools Installer +======================= -https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110.zip +The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL: -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. +https://dl.espressif.com/dl/esp-idf-tools-setup-1.0.exe +The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a customized configuration tool called mconf. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer. -Check it Out -============ +By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths. -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:: +Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself. - mkdir -p ~/esp +Installing Git +============== -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. +The ESP-IDF tools installer does not install Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a command line Git for Windows (along with the "Git Bash" terminal) from `Git For Windows`_. -.. figure:: ../../_static/msys2-terminal-window.png - :align: center - :alt: MSYS2 MINGW32 shell window - :figclass: align-center +If you prefer to use a different graphical Git client, then you can install one such as `Github Desktop`. You will need to translate the Git commands in the Getting Started guide for use with your chosen Git client. - MSYS2 MINGW32 shell window +Using a Terminal +================ -Use this window in the following steps setting up development environment for ESP32. +For the remaining Getting Started steps, we're going to use a terminal command prompt. It doesn't matter which command prompt you use: +- You can use the built-in Windows Command Prompt, under the Start menu. Note that command line instructions in this documentation give "bash" commands for Mac OS or Linux first. The Windows Command Prompt equivalent is given afterwards. +- You can use the "Git Bash" terminal which is part of `Git for Windows`_. This uses the same "bash" command prompt syntax as Mac OS or Linux. You can find it in the Start menu once installed. +- If you have MSYS2_ installed (maybe from a previous ESP-IDF version), then you can also use the MSYS terminal. 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. - Related Documents ================= +For advanced users who want to customize the install process: + .. toctree:: :maxdepth: 1 @@ -67,3 +64,9 @@ Related Documents .. _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: https://github.com/espressif/kconfig-frontends/releases/ +.. _Github Desktop: https://desktop.github.com/ diff --git a/docs/en/index.rst b/docs/en/index.rst index 317eff85d3..a92218f320 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -3,6 +3,9 @@ ESP-IDF Programming Guide This is the documentation for Espressif IoT Development Framework (`esp-idf `_). ESP-IDF is the official development framework for the `ESP32 `_ chip. +.. note:: + This is documentation for the the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release. + ================== ================== ================== |Get Started|_ |API Reference|_ |H/W Reference|_ ------------------ ------------------ ------------------ @@ -40,7 +43,6 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf H/W Reference API Guides - CMake Build System Preview Contribute Resources Copyrights diff --git a/docs/zh_CN/api-guides/gnu-make-build-system.rst b/docs/zh_CN/api-guides/gnu-make-build-system.rst new file mode 100644 index 0000000000..19bc45fc3a --- /dev/null +++ b/docs/zh_CN/api-guides/gnu-make-build-system.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/gnu-make-build-system.rst diff --git a/docs/zh_CN/get-started/eclipse-setup-windows.rst b/docs/zh_CN/get-started/eclipse-setup-windows.rst deleted file mode 100644 index ba15bc9dba..0000000000 --- a/docs/zh_CN/get-started/eclipse-setup-windows.rst +++ /dev/null @@ -1,81 +0,0 @@ -***************************************************** -Eclipse IDE 的创建和烧录指南（Windows 平台） -***************************************************** - -Windows 平台上的 Eclipse 配置略有不同，具体步骤请见下文。 - -注意：OS X 和 Linux 平台上的 Eclipse IDE 配置，请见 :doc:`Eclipse IDE page `。 - -安装 Eclipse IDE -================== - -Windows 平台的 Eclipse 安装步骤与其他平台相同，请见 :ref:`Installing Eclipse IDE `。 - -.. _eclipse-windows-setup: - - -Windows 平台上的 Eclipse 配置 -================================ - -完成 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” 下取消选中 “Show only available toolchains that support this platform”。 - -* 在出现的扩展列表中，选择 “Cygwin GCC”。然后点击 “Finish”。 - -*注意：您可能看到有关“无法找到 Cygwin GCC 工具链”的警告。这种情况并不影响安装，我们只需重新配置 Eclipse，并找到我们的工具链即可。* - -项目属性 ----------- - -* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择顶层 “Properties”。 - -* 点击 “C/C++ Build” 属性页。 - - * 取消选中 “Use default build command”，然后输入命令：``python${IDF_PATH}/tools/windows/eclipse_make.py``，开始自定义创建。 - -* 点击 “C/C++ Build” 下的 “Environment” 属性页面。 - - * 选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。 - - * 再次点击 “Add...”，输入名称 ``IDF_PATH``，并填写 ESP-IDF 的完整安装路径。``IDF_PATH`` 目录路径应使用正斜杠，而非反斜线，即 ``C:/Users/MyUser/Development/esp-idf``。 - - * 选择 PATH 环境变量，删除默认值，并将其替换为 ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` （如果您已经将 msys32 安装到其他目​​录，这里请自行调整）。 - - -* 点击 “C/C++ General” -> “Preprocessor Include Paths, Macros, etc.” 属性页。 - - * 点击 “Providers” 选项卡。 - - * 从 “Providers” 列表中选择 “CDT GCC Built-in Compiler Settings Cygwin”。在 “Command to get compiler specs” 输入框中，用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``${COMMAND}``，最终完整的 ``Command to get compiler specs`` 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。 - - * 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 Compiler 命令模式的起始位置输入 ``xtensa-esp32-elf-``，并用括号把剩余部分扩起来。最终的完整 Compiler 命令模式应为 ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``。 - - -在 Eclipse IDE 中创建项目 ---------------------------- - -Windows 平台的 Eclipse 项目创建步骤与其他平台相同，请见 :ref:`Building in Eclipse `。 - -技术细节 -========= - -**以下内容仅供 Windows 平台专家或非常感兴趣的开发者阅读。** - -Windows 平台的 Eclipse 介绍到此结束，下方将主要将介绍一些关键步骤的原理，助您了解更多 Eclipse 的背景信息。 - -* 首先，xtensa-esp32-elf-gcc 交叉编译器 *并非* Cygwin 工具链，但我们会在 Eclipse 中指定其为 Cygwin 工具链。主要原因在于：msys2 需要使用 Cygwin，并支持 Unix 风格的路径，即 ``/c/blah``，而非 ``c:/blah`` 或 ``c:\\blah``。特别需要说明的是，``xtensa-esp32-elf-gcc`` 会“告知” Eclipse 的 ``built-in compiler settings`` 功能，其内置 “include” 目录全部位于 ``/usr/`` 路径下，这也是 Eclipse 唯一可以解析的 ``Unix/Cygwin`` 风格路径。通过在 Eclipse 中指定 ``xtensa-esp32-elf-gcc`` 交叉编译器为 Cygwin 编译器，可以让 Eclipse 使用 cygpath 实用程序直接内部解析路径。 - - -* 在解析 ESP-IDF 的 make 结果时也经常会出现同样的问题。Eclipse 可以解析 make 的结果，查找头文件目录，但是无法脱离 ``cygpath``，直接解析类似 ``/c/blah`` 的目录。``Eclipse Build Output Parser`` 将利用该机制确认是否调用 ``cygpath``，但由于未知原因，目前 ESP-IDF 配置并不会触发该功能。出于这个原因，我们会使用 ``eclipse_make.py`` 包装脚本调用 ``make``，然后使用 ``cygpath`` 处理 Eclipse 的结果。 \ No newline at end of file diff --git a/docs/zh_CN/get-started/eclipse-setup.rst b/docs/zh_CN/get-started/eclipse-setup.rst index 8db8639428..634c5ee122 100644 --- a/docs/zh_CN/get-started/eclipse-setup.rst +++ b/docs/zh_CN/get-started/eclipse-setup.rst @@ -2,107 +2,6 @@ Eclipse IDE 的创建和烧录指南 **************************** -.. _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）。 - -Windows 用户 -============ - -在 Windows 平台上使用 Eclipse IDE 的用户，请参考 :ref:`Windows 用户的 Eclipse IDE 使用指南 `。 - -配置 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``) 增加至列表。 - -* 在 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`` 替换行首的 ``${COMMAND}``，最终的完整 “Command to get compiler specs” 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。 - - * 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 “Compiler command pattern“ 输入框的起始位置输入 ``xtensa-esp32-elf-``，最终的完整编译器命令应为 ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``。 - -.. _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``）。 - -* 从菜单中选择 “Make Targets” -> “Create”。 - -* 输入 “flash” 为目标名称，其他选项使用默认值。 - -* 选择 “Project” -> “Make Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。 - -注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。 - -如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。 - -相关文档 --------- - -.. toctree:: - :maxdepth: 1 - - eclipse-setup-windows - - -.. _eclipse.org: https://www.eclipse.org/ +.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index e2eb3d2eaa..be92cc0d69 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -2,6 +2,8 @@ 快速入门 *********** +.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 + 本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子来说明如何使用 ESP-IDF (Espressif IoT Development Framework)，包括配置、编译、下载固件到开发板等步骤。 概述 diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst index a4dc1d943c..267782a372 100644 --- a/docs/zh_CN/get-started/linux-setup.rst +++ b/docs/zh_CN/get-started/linux-setup.rst @@ -2,6 +2,8 @@ Linux 平台工具链的标准设置 ***************************** +.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 + 安装前提 ===================== diff --git a/docs/zh_CN/get-started/macos-setup.rst b/docs/zh_CN/get-started/macos-setup.rst index ea5b6c60d3..b7c303f132 100644 --- a/docs/zh_CN/get-started/macos-setup.rst +++ b/docs/zh_CN/get-started/macos-setup.rst @@ -2,6 +2,8 @@ 在 Mac OS 上安装 ESP32 工具链 ************************************** +.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 + 安装准备 ================ diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index d83408e3c0..bff59ab996 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -2,6 +2,8 @@ Windows 平台工具链的标准设置 *************************************** +.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。 + 引言 ============ @@ -53,8 +55,6 @@ https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110 你可以在系统上拥有独立的不同的 MSYS2 环境，前提是在不同的目录中。 -或者，:ref:`你也可以更新现有的环境而不是下载新环境 `，但是这样更复杂。 - 相关文档 ================= diff --git a/tools/idf.py b/tools/idf.py index 989f310634..3607a90033 100755 --- a/tools/idf.py +++ b/tools/idf.py @@ -322,12 +322,12 @@ ACTIONS = { "size-files": ( build_target, [ "app" ], [] ), "bootloader": ( build_target, [], [] ), "bootloader-clean": ( build_target, [], [] ), - "bootloader-flash": ( flash, [ "bootloader" ], [] ), + "bootloader-flash": ( flash, [ "bootloader" ], [ "erase_flash"] ), "app": ( build_target, [], [ "clean", "fullclean", "reconfigure" ] ), - "app-flash": ( flash, [ "app" ], []), + "app-flash": ( flash, [ "app" ], [ "erase_flash"]), "partition_table": ( build_target, [], [ "reconfigure" ] ), - "partition_table-flash": ( flash, [ "partition_table" ], []), - "flash": ( flash, [ "all" ], [ ] ), + "partition_table-flash": ( flash, [ "partition_table" ], [ "erase_flash" ]), + "flash": ( flash, [ "all" ], [ "erase_flash" ] ), "erase_flash": ( erase_flash, [], []), "monitor": ( monitor, [], [ "flash", "partition_table-flash", "bootloader-flash", "app-flash" ]), } diff --git a/tools/unit-test-app/README.md b/tools/unit-test-app/README.md index 1f06be55bf..2df5e82514 100644 --- a/tools/unit-test-app/README.md +++ b/tools/unit-test-app/README.md @@ -7,7 +7,7 @@ ESP-IDF unit tests are run using Unit Test App. The app can be built with the un * 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. +* `idf.py 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`.