From 62ed221dafdd94077cd251d449c65de0b46502d5 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 25 Jun 2019 11:29:49 +1000 Subject: [PATCH] docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) --- docs/en/api-guides/build-system-cmake.rst | 1311 ---------------- docs/en/api-guides/build-system-legacy.rst | 650 ++++++++ docs/en/api-guides/build-system.rst | 1387 ++++++++++++----- .../{ulp-cmake.rst => ulp-legacy.rst} | 52 +- docs/en/api-guides/ulp.rst | 52 +- ...-tests-cmake.rst => unit-tests-legacy.rst} | 57 +- docs/en/api-guides/unit-tests.rst | 57 +- .../add-idf_path-to-profile.rst | 3 - docs/en/get-started-cmake/eclipse-setup.rst | 12 - docs/en/get-started-cmake/index.rst | 491 ------ .../get-started-cmake/linux-setup-scratch.rst | 77 - docs/en/get-started-cmake/linux-setup.rst | 68 - .../get-started-cmake/macos-setup-scratch.rst | 88 -- docs/en/get-started-cmake/macos-setup.rst | 60 - .../windows-setup-scratch.rst | 122 -- docs/en/get-started-cmake/windows-setup.rst | 70 - .../get-started/add-idf_path-to-profile.rst | 65 + .../get-started/eclipse-setup.rst | 109 ++ .../establish-serial-connection.rst | 20 +- .../get-started-legacy/get-started/index.rst | 452 ++++++ .../get-started/linux-setup-scratch.rst | 75 + .../get-started/linux-setup.rst | 118 ++ .../get-started/macos-setup-scratch.rst | 72 + .../get-started/macos-setup.rst | 57 + .../get-started/make-project.rst | 0 .../get-started}/toolchain-setup-scratch.rst | 12 +- .../get-started/windows-setup-scratch.rst | 117 ++ .../get-started/windows-setup.rst | 70 + .../get-started/add-idf_path-to-profile.rst | 66 +- docs/en/get-started/eclipse-setup.rst | 109 +- .../establish-serial-connection.rst | 20 +- docs/en/get-started/index.rst | 359 +++-- docs/en/get-started/linux-setup-scratch.rst | 38 +- docs/en/get-started/linux-setup.rst | 78 +- docs/en/get-started/macos-setup-scratch.rst | 50 +- docs/en/get-started/macos-setup.rst | 69 +- .../get-started/toolchain-setup-scratch.rst | 12 +- docs/en/get-started/windows-setup-scratch.rst | 201 +-- .../windows-setup-update.rst | 0 docs/en/get-started/windows-setup.rst | 74 +- .../hw-reference/get-started-devkitc-v2.rst | 8 +- docs/en/hw-reference/get-started-devkitc.rst | 15 +- .../hw-reference/get-started-pico-kit-v3.rst | 6 +- docs/en/hw-reference/get-started-pico-kit.rst | 34 +- .../get-started-wrover-kit-v2.rst | 18 +- .../get-started-wrover-kit-v3.rst | 49 +- .../hw-reference/get-started-wrover-kit.rst | 48 +- 47 files changed, 3483 insertions(+), 3495 deletions(-) delete mode 100644 docs/en/api-guides/build-system-cmake.rst create mode 100644 docs/en/api-guides/build-system-legacy.rst rename docs/en/api-guides/{ulp-cmake.rst => ulp-legacy.rst} (80%) rename docs/en/api-guides/{unit-tests-cmake.rst => unit-tests-legacy.rst} (77%) delete mode 100644 docs/en/get-started-cmake/add-idf_path-to-profile.rst delete mode 100644 docs/en/get-started-cmake/eclipse-setup.rst delete mode 100644 docs/en/get-started-cmake/index.rst delete mode 100644 docs/en/get-started-cmake/linux-setup-scratch.rst delete mode 100644 docs/en/get-started-cmake/linux-setup.rst delete mode 100644 docs/en/get-started-cmake/macos-setup-scratch.rst delete mode 100644 docs/en/get-started-cmake/macos-setup.rst delete mode 100644 docs/en/get-started-cmake/windows-setup-scratch.rst delete mode 100644 docs/en/get-started-cmake/windows-setup.rst create mode 100644 docs/en/get-started-legacy/get-started/add-idf_path-to-profile.rst create mode 100644 docs/en/get-started-legacy/get-started/eclipse-setup.rst rename docs/en/{get-started-cmake => get-started-legacy/get-started}/establish-serial-connection.rst (84%) create mode 100644 docs/en/get-started-legacy/get-started/index.rst create mode 100644 docs/en/get-started-legacy/get-started/linux-setup-scratch.rst create mode 100644 docs/en/get-started-legacy/get-started/linux-setup.rst create mode 100644 docs/en/get-started-legacy/get-started/macos-setup-scratch.rst create mode 100644 docs/en/get-started-legacy/get-started/macos-setup.rst rename docs/en/{ => get-started-legacy}/get-started/make-project.rst (100%) rename docs/en/{get-started-cmake => get-started-legacy/get-started}/toolchain-setup-scratch.rst (72%) create mode 100644 docs/en/get-started-legacy/get-started/windows-setup-scratch.rst create mode 100644 docs/en/get-started-legacy/get-started/windows-setup.rst rename docs/en/{get-started-cmake => get-started}/windows-setup-update.rst (100%) diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst deleted file mode 100644 index ec63c0fc4..000000000 --- a/docs/en/api-guides/build-system-cmake.rst +++ /dev/null @@ -1,1311 +0,0 @@ -Build System (CMake) -******************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -.. include:: ../cmake-pending-features.rst - -This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components". :doc:`Documentation for the GNU Make based build system ` is also available - -Read this document if you want to know how to organise and build a new ESP-IDF project or component using the CMake-based build system. - - -Overview -======== - -An ESP-IDF project can be seen as an amalgamation of a number of components. -For example, for a webserver that shows the current humidity, there could be: - -- The ESP32 base libraries (libc, ROM bindings, etc) -- The WiFi drivers -- A TCP/IP stack -- The FreeRTOS operating system -- A webserver -- A driver for the humidity sensor -- Main code tying it all together - -ESP-IDF makes these components explicit and configurable. To do that, -when a project is compiled, the build system will look up all the -components in the ESP-IDF directories, the project directories and -(optionally) in additional custom component directories. It then -allows the user to configure the ESP-IDF project using a a text-based -menu system to customize each component. After the components in the -project are configured, the build system will compile the project. - -Concepts --------- - -- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader. - -- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. - -- An "app" is an executable which is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). - -- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places. - -- "Target" is the hardware for which an application is built. At the moment, ESP-IDF supports only one target, ``esp32``. - -Some things are not part of the project: - -- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project. - -- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH. - -Using the Build System -====================== - -.. _idf.py: - -idf.py ------- - -The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools: - -- CMake_, which configures the project to be built -- A command line build tool (either Ninja_ build or `GNU Make`) -- `esptool.py`_ for flashing ESP32. - -The :ref:`getting started guide ` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects. - -``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``. - -Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones: - -- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project. -- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps: - - - Create the build directory if needed. The sub-directory ``build`` is used to hold build output, although this can be changed with the ``-B`` option. - - Run CMake_ as necessary to configure the project and generate build files for the main build tool. - - Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``. - - Building is incremental so if no source files or configuration has changed since the last build, nothing will be done. -- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files. -- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted. -- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively. -- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor. - -Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor. - -.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default. - -.. _idf.py-size: - -Advanced Commands -^^^^^^^^^^^^^^^^^ - -- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable. -- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32. -- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip. -- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text. -- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``. - -The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.). - -Using CMake Directly --------------------- - -:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer. - -.. highlight:: bash - -When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt):: - - mkdir -p build - cd build - cmake .. -G Ninja # or 'Unix Makefiles' - ninja - -In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: running ``ninja`` actually builds the project. - -It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration. - -If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``. - -.. note:: - If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components. - -.. _flash-with-ninja-or-make: - -Flashing with ninja or make -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It's possible to build and flash directly from ninja or make by running a target like:: - - ninja flash - -Or:: - - make app-flash - -Available targets are: ``flash``, ``app-flash`` (app only), ``bootloader-flash`` (bootloader only). - -When flashing this way, optionally set the ``ESPPORT`` and ``ESPBAUD`` environment variables to specify the serial port and baud rate. You can set environment variables in your operating system or IDE project. Alternatively, set them directly on the command line:: - - ESPPORT=/dev/ttyUSB0 ninja flash - -.. note:: Providing environment variables at the start of the command like this is Bash shell Syntax. It will work on Linux and macOS. It won't work when using Windows Command Prompt, but it will work when using Bash-like shells on Windows. - -Or:: - - make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000 - -.. note:: Providing variables at the end of the command line is ``make`` syntax, and works for ``make`` on all platforms. - - -Using CMake in an IDE ---------------------- - -You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE. - -When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands. - -For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_. - -.. _setting-python-interpreter: - -Setting the Python Interpreter ------------------------------- - -Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems. - -If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command. - -If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter. - -If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter. - -To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version. - -.. _example-project-structure: - -Example Project -=============== - -.. highlight:: none - -An example project directory tree might look like this:: - - - myProject/ - - CMakeLists.txt - - sdkconfig - - components/ - component1/ - CMakeLists.txt - - Kconfig - - src1.c - - component2/ - CMakeLists.txt - - Kconfig - - src1.c - - include/ - component2.h - - main/ - src1.c - - src2.c - - - build/ - -This example "myProject" contains the following elements: - -- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file :idf_file:`/tools/cmake/project.cmake` which - implements the rest of the build system. Finally, it sets the project name and defines the project. - -- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project. - -- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF. - -- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places. See the :ref:`renaming main ` section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main". - -- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. - -Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions -to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details. - -Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_. - -Project CMakeLists File -======================= - -Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal. - -Minimal Example CMakeLists --------------------------- - -.. highlight:: cmake - -Minimal project:: - - cmake_minimum_required(VERSION 3.5) - include($ENV{IDF_PATH}/tools/cmake/project.cmake) - project(myProject) - - -.. _project-mandatory-parts: - -Mandatory Parts ---------------- - -The inclusion of these three lines, in the order shown above, is necessary for every project: - -- ``cmake_minimum_required(VERSION 3.5)`` tells CMake the minimum version that is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file. -- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc. -- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file. - - -Optional Project Variables --------------------------- - -These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details. - -- ``COMPONENT_DIRS``,``COMPONENTS_DIRS``: Directories to search for components. Defaults to `IDF_PATH/components`, `PROJECT_DIR/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. -- ``EXTRA_COMPONENT_DIRS``, ``EXTRA_COMPONENTS_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute. -- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via the REQUIRES or PRIV_REQUIRES arguments on component registration will automatically have it added to this list, so the ``COMPONENTS`` list can be very short. - -Any paths in these variables can be absolute paths, or set relative to the project directory. - -To set these variables, use the `cmake set command `_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line. - -.. _rename-main-cmake: - -Renaming ``main`` component ----------------------------- - -The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided -that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, -saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component -causes the loss of these behind-the-scences heavy lifting, requiring the user to specify the location of the newly renamed component -and manually specifying its dependencies. Specifically, the steps to renaming ``main`` are as follows: - -1. Rename ``main`` directory. -2. Set ``EXTRA_COMPONENT_DIRS`` in the project CMakeLists.txt to include the renamed ``main`` directory. -3. Specify the dependencies in the renamed component's CMakeLists.txt file via REQUIRES or PRIV_REQUIRES arguments :ref:`on component registration`. - -.. _component-directories-cmake: - -Component CMakeLists Files -========================== - -Each project contains one or more components. Components can be part of ESP-IDF, part of the project's own components directory, or added from custom component directories (:ref:`see above `). - -A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file. - -Searching for Components ------------------------- - -The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose sub-directories are components. - -When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components. - -Multiple components with the same name --------------------------------------- - -When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories -contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components -with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. -If used in this way, the ESP-IDF directory itself can remain untouched. - -.. _cmake_minimal_component_cmakelists: - -Minimal Component CMakeLists ----------------------------- - -.. highlight:: cmake - -The minimal component ``CMakeLists.txt`` file simply registers the component to the build system using ``idf_component_register``:: - - idf_component_register(SRCS "foo.c" "bar.c" - INCLUDE_DIRS "include") - -- ``SRCS`` is a list of source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``). These source files will be compiled into the component library. -- ``INCLUDE_DIRS`` is a list of directories to add to the global include search path for any component which requires this component, and also the main source files. - -A library with the name of the component will be built and linked into the final app. -Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute. - -There are other arguments that can be passed to ``idf_component_register``. These arguments -are discussed :ref:`here`. - -See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples. - -.. _component variables: - -Preset Component Variables --------------------------- - -The following component-specific variables are available for use inside component CMakeLists, but should not be modified: - -- ``COMPONENT_DIR``: The component directory. Evaluates to the absolute path of the directory containing ``CMakeLists.txt``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable. -- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory. -- ``COMPONENT_ALIAS``: Alias of the library created internally by the build system for the component. -- ``COMPONENT_LIB``: Name of the library created internally by the build system for the component. - -The following variables are set at the project level, but available for use in component CMakeLists: - -- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in cmake. All names begin with ``CONFIG_``. :doc:`More information here `. -- ``ESP_PLATFORM``: Set to 1 when the CMake file is processed within ESP-IDF build system. - -Build/Project Variables ------------------------- - -The following are some project/build variables that are available as build properties and whose values can be queried using ``idf_build_get_property`` -from the component CMakeLists.txt: - -- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file. -- ``PROJECT_DIR``: Absolute path of the project directory containing the project CMakeLists. Same as the ``CMAKE_SOURCE_DIR`` variable. -- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list. -- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``) -- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``IDF_VERSION_*`` variables, but different ``IDF_VER`` values. -- ``IDF_TARGET``: Name of the target for which the project is being built. -- ``PROJECT_VER``: Project version. - - * If ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used. - * Else, if the ``PROJECT_DIR/version.txt`` exists, its contents will be used as ``PROJECT_VER``. - * Else, if the project is located inside a Git repository, the output of git describe will be used. - * Otherwise, ``PROJECT_VER`` will be "1". - -Other build properties are listed :ref:`here`. - -Controlling Component Compilation ---------------------------------- - -.. highlight:: cmake - -To pass compiler options when compiling source files belonging to a particular component, use the ``target_compile_options`` function:: - - target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable) - -To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command:: - - set_source_files_properties(mysrc.c - PROPERTIES COMPILE_FLAGS - -Wno-unused-variable - ) - -This can be useful if there is upstream code that emits warnings. - -When using these commands, place them after the call to ``idf_component_register`` in the component CMakeLists file. - -.. _component-configuration-cmake: - -Component Configuration -======================= - -Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains -configuration settings to add to the configuration menu for this component. - -These settings are found under the "Component Settings" menu when menuconfig is run. - -To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF. - -For an example, see `Adding conditional configuration`_. - -Preprocessor Definitions -======================== - -The ESP-IDF build system adds the following C preprocessor definitions on the command line: - -- ``ESP_PLATFORM`` : Can be used to detect that build happens within ESP-IDF. -- ``IDF_VER`` : Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit. - -Component Requirements -====================== - -When compiling each component, the ESP-IDF build system recursively evaluates its components. - -Each component's source file is compiled with these include path directories, as specified in the passed arguments -to ``idf_component_register``: - -- The current component's ``INCLUDE_DIRS`` and ``PRIV_INCLUDE_DIRS``. -- The ``INCLUDE_DIRS`` set by all components in the current component's ``REQUIRES`` and ``PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies). -- All of the ``REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded). - -When writing a component ------------------------- - -- ``REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component. -- ``PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly. -- ``REQUIRES`` and/or ``PRIV_REQUIRES`` should be set before calling ``idf_component_register()``. -- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices. -- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset. - -Components which support only some targets (values of ``IDF_TARGET``) may specify ``REQUIRED_IDF_TARGETS`` in the ``idf_component_register`` call to express these requirements. In this case the build system will generate an error if the component is included into the build, but does not support selected target. - -When creating a project ------------------------ - -- By default, every component is included in the build. -- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include: - - - Components mentioned explicitly in ``COMPONENTS``. - - Those components' requirements (evaluated recursively). - - The "common" components that every component depends on. -- Setting ``COMPONENTS`` to the minimal list of required components can significantly reduce compile times. - -.. _component-requirements-implementation: - -Requirements in the build system implementation ------------------------------------------------ - -- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory. -- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable). The ``BUILD_COMPONENTS`` variable is sorted so dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies. -- The value of ``BUILD_COMPONENTS`` is logged by CMake as "Component names: " -- Configuration is then evaluated for the components included in the build. -- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build. - -Component Dependency Order -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The order of components in the ``BUILD_COMPONENTS`` variable determines other orderings during the build: - -- Order that :ref:`project_include.cmake` files are included into the project. -- Order that the list of header paths is generated for compilation (via ``-I`` argument). (Note that for a given component's source files, only that component's dependency's header paths are passed to the compiler.) - -Build Process Internals -======================= - -For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`_. - -project.cmake contents ----------------------- - -When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environment. - -It also defines an overridden custom version of the built-in CMake_ ``project`` function. This function is overridden to add all of the ESP-IDF specific project functionality. - -project function ----------------- - -The custom ``project()`` function performs the following steps: - -- Determines the target (set by ``IDF_TARGET`` environment variable) and saves the target in CMake cache. If the target set in the environment does not match the one in cache, exits with an error. -- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above`). -- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set). -- Loads the project configuration from the ``sdkconfig`` file and generates a ``sdkconfig.cmake`` file and a ``sdkconfig.h`` header. These define configuration values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to re-generate these files and re-configure the project. -- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the correct toolchain file, depending on the target. -- Declares the actual cmake-level project by calling the `CMake project function `_. -- Loads the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_. -- Includes :ref:`project_include.cmake` files from any components which have them. -- Adds each component to the build. Each component CMakeLists file calls ``idf_component_register``, calls the CMake `add_library `_ function to add a library and then adds source files, compile options, etc. -- Adds the final app executable to the build. -- Goes back and adds inter-component dependencies between components (ie adding the public header directories of each component to each other component). - -Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details. - -Debugging CMake ---------------- - -Some tips for debugging the ESP-IDF CMake-based build system: - -- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths. -- Running ``cmake -DDEBUG=1`` will produce more verbose diagnostic output from the IDF build system. -- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_. - -.. _warn-undefined-variables-cmake: - -Warning On Undefined Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files. - -If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``. - -Overriding Parts of the Project -------------------------------- - -.. _project_include.cmake: - -project_include.cmake -^^^^^^^^^^^^^^^^^^^^^ - -For components that have build requirements which must be evaluated before any component CMakeLists -files are evaluated, you can create a file called ``project_include.cmake`` in the -component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project. - -``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". - -Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cmake`` file the current source directory (``CMAKE_CURRENT_SOURCE_DIR`` and working directory) is the project directory. Use the variable ``COMPONENT_DIR`` for the absolute directory of the component. - -Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details. - -``project_include.cmake`` files are included in the order given in ``BUILD_COMPONENTS`` variable (as logged by CMake). This means that a component's ``project_include.cmake`` file will be included after it's all dependencies' ``project_include.cmake`` files, unless both components are part of a dependency cycle. This is important if a ``project_include.cmake`` file relies on variables set by another component. See also :ref:`above`. - -Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components! - -KConfig.projbuild -^^^^^^^^^^^^^^^^^ - -This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration-cmake` KConfig files. If you want to include -configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file. - -Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for :ref:`component-configuration-cmake`. - - -Configuration-Only Components -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``idf_component_register()`` with no -arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths. - -Example Component CMakeLists -============================ - -Because the build environment tries to set reasonable defaults that will work most -of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality. - -Here are some more advanced examples of component CMakeLists files. - -Adding conditional configuration --------------------------------- - -The configuration system can be used to conditionally compile some files -depending on the options selected in the project configuration. - -.. highlight:: none - -``Kconfig``:: - - config FOO_ENABLE_BAR - bool "Enable the BAR feature." - help - This enables the BAR feature of the FOO component. - -``CMakeLists.txt``:: - - set(COMPONENT_SRCS "foo.c" "more_foo.c") - - if(CONFIG_FOO_ENABLE_BAR) - list(APPEND COMPONENT_SRCS "bar.c") - endif() - -This example makes use of the CMake `if `_ function and `list APPEND `_ function. - -This can also be used to select or stub out an implementation, as such: - -``Kconfig``:: - - config ENABLE_LCD_OUTPUT - bool "Enable LCD output." - help - Select this if your board has a LCD. - - config ENABLE_LCD_CONSOLE - bool "Output console text to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output debugging output to the lcd - - config ENABLE_LCD_PLOT - bool "Output temperature plots to LCD" - depends on ENABLE_LCD_OUTPUT - help - Select this to output temperature plots - -.. highlight:: cmake - -``CMakeLists.txt``:: - - if(CONFIG_ENABLE_LCD_OUTPUT) - set(COMPONENT_SRCS lcd-real.c lcd-spi.c) - else() - set(COMPONENT_SRCS lcd-dummy.c) - endif() - - # We need font if either console or plot is enabled - if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT) - list(APPEND COMPONENT_SRCS "font.c") - endif() - - -Conditions which depend on the target -------------------------------------- - -The current target is available to CMake files via ``IDF_TARGET`` variable. - -In addition to that, if target ``xyz`` is used (``IDF_TARGET=xyz``), then Kconfig variable ``CONFIG_IDF_TARGET_XYZ`` will be set. - -Note that component dependencies may depend on ``IDF_TARGET`` variable, but not on Kconfig variables. Also one can not use Kconfig variables in ``include`` statements in CMake files, but ``IDF_TARGET`` can be used in such context. - - -Source Code Generation ----------------------- - -Some components will have a situation where a source file isn't -supplied with the component itself but has to be generated from -another file. Say our component has a header file that consists of the -converted binary data of a BMP file, converted using a hypothetical -tool called bmp2h. The header file is then included in as C source -file called graphics_lib.c:: - - add_custom_command(OUTPUT logo.h - COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h - DEPENDS ${COMPONENT_DIR}/logo.bmp - VERBATIM) - - add_custom_target(logo DEPENDS logo.h) - add_dependencies(${COMPONENT_LIB} logo) - - set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY - ADDITIONAL_MAKE_CLEAN_FILES logo.h) - -This answer is adapted from the `CMake FAQ entry `_, which contains some other examples that will also work with ESP-IDF builds. - -In this example, logo.h will be generated in the -current directory (the build directory) while logo.bmp comes with the -component and resides under the component path. Because logo.h is a -generated file, it should be cleaned when the project is cleaned. For this reason -it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property. - -.. note:: - - If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use build property ``PROJECT_DIR`` instead of ``${COMPONENT_DIR}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_LIB}``.) - -If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between -the two components, to ensure that the component source files were always compiled in the correct order. - -.. _cmake_embed_data: - -Embedding Binary Data ---------------------- - -Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source. - -You can specify argument ``COMPONENT_EMBED_FILES`` in the component registration, giving space-delimited names of the files to embed:: - - idf_component_register(... - EMBED_FILES server_root_cert.der) - - -Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string:: - - idf_component_register(... - EMBED_TXTFILES server_root_cert.pem) - -.. highlight:: c - -The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows:: - - extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); - extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); - -The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. - -.. highlight:: cmake - -To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this:: - - target_add_binary_data(myproject.elf "main/data.bin" TEXT) - -Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is. - -For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time. - -Code and Data Placements ------------------------- - -ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through -linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking -app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion -of the mechanism. - -.. _component-build-full-override: - -Fully Overriding The Component Build Process --------------------------------------------- - -.. highlight:: cmake - -Obviously, there are cases where all these recipes are insufficient for a -certain component, for example when the component is basically a wrapper -around another third-party component not originally intended to be -compiled under this build system. In that case, it's possible to forego -the ESP-IDF build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists:: - - # External build process for quirc, runs in source dir and - # produces libquirc.a - externalproject_add(quirc_build - PREFIX ${COMPONENT_DIR} - SOURCE_DIR ${COMPONENT_DIR}/quirc - CONFIGURE_COMMAND "" - BUILD_IN_SOURCE 1 - BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a - INSTALL_COMMAND "" - ) - - # Add libquirc.a to the build process - # - add_library(quirc STATIC IMPORTED GLOBAL) - add_dependencies(quirc quirc_build) - - set_target_properties(quirc PROPERTIES IMPORTED_LOCATION - ${COMPONENT_DIR}/quirc/libquirc.a) - set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES - ${COMPONENT_DIR}/quirc/lib) - - set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES - "${COMPONENT_DIR}/quirc/libquirc.a") - -(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.) - -- ``externalproject_add`` defines an external build system. - - - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds. - - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``. - - Consult the ExternalProject_ documentation for more details about ``externalproject_add()`` - -- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is. -- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.) - -.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. - -.. _ADDITIONAL_MAKE_CLEAN_FILES_note: - -ExternalProject dependencies, clean builds -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CMake has some unusual behaviour around external project builds: - -- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning. -- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run. -- Therefore, there are two alternative recommended ways to configure the external build command: - - 1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.) - 2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run. - -The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project. - -.. _custom-sdkconfig-defaults-cmake: - -Custom sdkconfig defaults -========================= - -For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file. - -To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable. - -Target-dependent sdkconfig defaults ------------------------------------ - -In addition to ``sdkconfig.defaults`` file, build system will also load defaults from ``sdkconfig.defaults.TARGET_NAME`` file, where ``TARGET_NAME`` is the value of ``IDF_TARGET``. For example, for ``esp32`` target, default settings will be taken from ``sdkconfig.defaults`` first, and then from ``sdkconfig.defaults.esp32``. - -If ``SDKCONFIG_DEFAULTS`` is used to override the name of defaults file, the name of target-specific defaults file will be derived from ``SDKCONFIG_DEFAULTS`` value. - - -Flash arguments -=============== - -There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. - -After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files: - -- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured). -- ``flash_app_args`` contains arguments to flash only the app. -- ``flash_bootloader_args`` contains arguments to flash only the bootloader. - -.. highlight:: bash - -You can pass any of these flasher argument files to ``esptool.py`` as follows:: - - python esptool.py --chip esp32 write_flash @build/flash_project_args - -Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line. - -The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build. - -Building the Bootloader -======================= - -The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``. - -The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project. - -The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``). - -Selecting the Target -==================== - -Currently ESP-IDF supports one target, ``esp32``. It is used by default by the build system. Developers working on adding multiple target support can change the target as follows:: - - rm sdkconfig - idf.py -DIDF_TARGET=new_target reconfigure - - -Writing Pure CMake Components -============================= - -The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build. - -However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake. - -.. highlight:: cmake - -Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``:: - - add_library(json STATIC - cJSON/cJSON.c - cJSON/cJSON_Utils.c) - - target_include_directories(json PUBLIC cJSON) - -- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`. -- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.) -- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands. - - -Using Third-Party CMake Projects with Components -================================================ - -CMake is used for a lot of open-source C and C++ projects — code that users can tap into for their applications. One of the benefits of having a CMake build system -is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may -not yet be provided by a component, or use another library for the same functionality. - -.. highlight:: cmake - -Importing a library might look like this for a hypothetical library ``foo`` to be used in the ``main`` component:: - - # Register the component - idf_component_register() - - # Set values of hypothetical variables that control the build of `foo` - set(FOO_BUILD_STATIC OFF) - set(FOO_BUILD_TESTS OFF) - - # Create and import the library targets - add_subdirectory(foo) - - # Link `foo` to `main` component - target_link_libraries(main foo) - -For an actual example, take a look at :example:`build_system/cmake/import_lib`. Take note that what needs to be done in order to import -the library may vary. It is recommended to read up on the library's documentation for instructions on how to -import it from other projects. Studying the library's CMakeLists.txt and build structure can also be helpful. - -It is also possible to wrap a third-party library to be used as a component in this manner. For example, the :component:`mbedtls` component is a wrapper for -Espressif's fork of `mbedtls `_. See its :component_file:`component CMakeLists.txt `. - -The CMake variable ``ESP_PLATFORM`` is set to 1 whenever the ESP-IDF build system is being used. Tests such as ``if (ESP_PLATFORM)`` can be used in generic CMake code if special IDF-specific logic is required. - - -Using ESP-IDF in Custom CMake Projects -====================================== - -ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already -have an existing CMake project or may want to create a custom one. In these cases it is desirable to be able to consume IDF components -as libraries to be linked to the user's targets (libraries/ executables). - -It is possible to do so by using the :ref:`build system APIs provided` by :idf_file:`tools/cmake/idf.cmake`. For example: - -.. code-block:: cmake - - cmake_minimum_required(VERSION 3.5) - project(my_custom_app C) - - # Include CMake file that provides ESP-IDF CMake build system APIs. - include($ENV{IDF_PATH}/tools/cmake/idf.cmake) - - # Include ESP-IDF components in the build, may be thought as an equivalent of - # add_subdirectory() but with some additional procesing and magic for ESP-IDF build - # specific build processes. - idf_build_process(esp32) - - # Create the project executable and plainly link the newlib component to it using - # its alias, idf::newlib. - add_executable(${CMAKE_PROJECT_NAME}.elf main.c) - target_link_libraries(${CMAKE_PROJECT_NAME}.elf idf::newlib) - - # Let the build system know what the project executable is to attach more targets, dependencies, etc. - idf_build_executable(${CMAKE_PROJECT_NAME}.elf) - -The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creation of an application equivalent to :example:`hello world application ` -using a custom CMake project. - -.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. -.. _cmake_buildsystem_api: - -ESP-IDF CMake Build System API -============================== - -idf-build-commands ------------------- - -.. code-block:: none - - idf_build_get_property(var property [GENERATOR_EXPRESSION]) - -Retrieve a :ref:`build property` *property* and store it in *var* accessible from the current scope. Specifying -*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which -can be used with CMake commands that support generator expressions. - -.. code-block:: none - - idf_build_set_property(property val [APPEND]) - -Set a :ref:`build property` *property* with value *val*. Specifying *APPEND* will append the specified value to the current -value of the property. If the property does not previously exist or it is currently empty, the specified value becomes -the first element/member instead. - -.. code-block:: none - - idf_build_component(component_dir) - -Present a directory *component_dir* that contains a component to the build system. Relative paths are converted to absolute paths with respect to current directory. -All calls to this command must be performed before `idf_build_process`. - -This command does not guarantee that the component will be processed during build (see the `COMPONENTS` argument description for `idf_build_process`) - -.. code-block:: none - - idf_build_process(target - [PROJECT_DIR project_dir] - [PROJECT_VER project_ver] - [PROJECT_NAME project_name] - [SDKCONFIG sdkconfig] - [SDKCONFIG_DEFAULTS sdkconfig_defaults] - [BUILD_DIR build_dir] - [COMPONENTS component1 component2 ...]) - -Performs the bulk of the behind-the-scenes magic for including ESP-IDF components such as component configuration, libraries creation, -dependency expansion and resolution. Among these functions, perhaps the most important -from a user's perspective is the libraries creation by calling each component's ``idf_component_register``. This command creates the libraries for each component, which are accessible using aliases in the form -idf::*component_name*. These aliases can be used to link the components to the user's own targets, either libraries -or executables. - -The call requires the target chip to be specified with *target* argument. Optional arguments for the call include: - -- PROJECT_DIR - directory of the project; defaults to CMAKE_SOURCE_DIR -- PROJECT_NAME - name of the project; defaults to CMAKE_PROJECT_NAME -- PROJECT_VER - version/revision of the project; defaults to "0.0.0" -- SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set -- SDKCONFIG_DEFAULTS - defaults file to use for the build; defaults to empty -- BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, components; defaults to CMAKE_BINARY_DIR -- COMPONENTS - select components to process among the components known by the build system (added via `idf_build_component`). This argument is used to trim the build. - Other components are automatically added if they are required in the dependency chain, i.e. - the public and private requirements of the components in this list are automatically added, and in turn the public and private requirements of those requirements, - so on and so forth. If not specified, all components known to the build system are processed. - -.. code-block:: none - - idf_build_executable(executable) - -Specify the executable *executable* for ESP-IDF build. This attaches additional targets such as dependencies related to -flashing, generating additional binary files, etc. Should be called after ``idf_build_process``. - -.. code-block:: none - - idf_build_get_config(var config [GENERATOR_EXPRESSION]) - -Get the value of the specified config. Much like build properties, specifying -*GENERATOR_EXPRESSION* will retrieve the generator expression string for that config, instead of the actual value, which -can be used with CMake commands that support generator expressions. Actual config values are only known after call to `idf_build_process`, however. - -.. _cmake-build-properties: - -idf-build-properties --------------------- - -These are properties that describe the build. Values of build properties can be retrieved by using the build command ``idf_build_get_property``. -For example, to get the Python interpreter used for the build: - -.. code-block: cmake - - idf_build_get_property(python PYTHON) - message(STATUS "The Python intepreter is: ${python}") - - - BUILD_DIR - build directory; set from ``idf_build_process`` BUILD_DIR argument - - BUILD_COMPONENTS - list of components (more specifically, component aliases) included in the build; set by ``idf_build_process`` - - C_COMPILE_OPTIONS - compile options applied to all components' C source files - - COMPILE_OPTIONS - compile options applied to all components' source files, regardless of it being C or C++ - - COMPILE_DEFINITIONS - compile definitions applied to all component source files - - CXX_COMPILE_OPTIONS - compile options applied to all components' C++ source files - - EXECUTABLE - project executable; set by call to ``idf_build_executable`` - - EXECUTABLE_NAME - name of project executable without extension; set by call to ``idf_build_executable`` - - IDF_PATH - ESP-IDF path; set from IDF_PATH environment variable, if not, inferred from the location of ``idf.cmake`` - - IDF_TARGET - target chip for the build; set from the required target argument for ``idf_build_process`` - - IDF_VER - ESP-IDF version; set from either a version file or the Git revision of the IDF_PATH repository - - INCLUDE_DIRECTORIES - include directories for all component source files - - KCONFIGS - list of Kconfig files found in components in build; set by ``idf_build_process`` - - KCONFIG_PROJBUILDS - list of Kconfig.projbuild diles found in components in build; set by ``idf_build_process`` - - PROJECT_NAME - name of the project; set from ``idf_build_process`` PROJECT_NAME argument - - PROJECT_DIR - directory of the project; set from ``idf_build_process`` PROJECT_DIR argument - - PROJECT_VER - version of the project; set from ``idf_build_process`` PROJECT_VER argument - - PYTHON - Python interpreter used for the build; set from PYTHON environment variable if available, if not "python" is used - - SDKCONFIG - full path to output config file; set from ``idf_build_process`` SDKCONFIG argument - - SDKCONFIG_DEFAULTS - full path to config defaults file; set from ``idf_build_process`` SDKCONFIG_DEFAULTS argument - - SDKCONFIG_HEADER - full path to C/C++ header file containing component configuration; set by ``idf_build_process`` - - SDKCONFIG_CMAKE - full path to CMake file containing component configuration; set by ``idf_build_process`` - - SDKCONFIG_JSON - full path to JSON file containing component configuration; set by ``idf_build_process`` - - SDKCONFIG_JSON_MENUS - full path to JSON file containing config menus; set by ``idf_build_process`` - -idf-component-commands ----------------------- - -.. code-block:: none - - idf_component_get_property(var component property [GENERATOR_EXPRESSION]) - -Retrieve a specified *component*'s :ref:`component property`, *property* and store it in *var* accessible from the current scope. Specifying -*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which -can be used with CMake commands that support generator expressions. - -.. code-block:: none - - idf_component_set_property(property val [APPEND]) - -Set a specified *component*'s :ref:`component property`, *property* with value *val*. Specifying *APPEND* will append the specified value to the current -value of the property. If the property does not previously exist or it is currently empty, the specified value becomes -the first element/member instead. - -.. _cmake-component-register: - -.. code-block:: none - - idf_component_register([[SRCS src1 src2 ...] | [[SRC_DIRS dir1 dir2 ...] [EXCLUDE_SRCS src1 src2 ...]] - [INCLUDE_DIRS dir1 dir2 ...] - [PRIV_INCLUDE_DIRS dir1 dir2 ...] - [REQUIRES component1 component2 ...] - [PRIV_REQUIRES component1 component2 ...] - [LDFRAGMENTS ldfragment1 ldfragment2 ...] - [REQUIRED_IDF_TARGETS target1 target2 ...] - [EMBED_FILES file1 file2 ...] - [EMBED_TXTFILES file1 file2 ...]) - -Register a component to the build system. Much like the ``project()`` CMake command, this should be called from the component's -CMakeLists.txt directly (not through a function or macro) and is recommended to be called before any other command. Here are some -guidelines on what commands can **not** be called before ``idf_component_register``: - - - commands that are not valid in CMake script mode - - custom commands defined in project_include.cmake - - build system API commands except ``idf_build_get_property``; although consider whether the property may not have been set yet - -Commands that set and operate on variables are generally okay to call before ``idf_component_register``. - -The arguments for ``idf_component_register`` include: - - - SRCS - component source files used for creating a static library for the component; if not specified, component is a treated as a - config-only component and an interface library is created instead. - - SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of specifying source files manually via SRCS. - Note that this is subject to the :ref:`limitations of globbing in CMake`. Source files specified in EXCLUDE_SRCS are removed from the globbed files. - - INCLUDE_DIRS - paths, relative to the component directory, which will be added to the include search path for all other components which require the current component - - PRIV_INCLUDE_DIRS - directory paths, must be relative to the component directory, which will be added to the include search path for this component's source files only - - REQUIRES - public component requirements for the component - - PRIV_REQUIRES - private component requirements for the component; ignored on config-only components - - LDFRAGMENTS - component linker fragment files - - REQUIRED_IDF_TARGETS - specify the only target the component supports - -The following are used for :ref:`embedding data into the component`, and is considered as source files -when determining if a component is config-only. This means that even if the component does not specify source files, a static library is still -created internally for the component if it specifies either: - - - EMBED_FILES - binary files to be embedded in the component - - EMBED_TXTFILES - text files to be embedded in the component - -.. _cmake-component-properties: - -idf-component-properties ------------------------- - -These are properties that describe a component. Values of component properties can be retrieved by using the build command ``idf_component_get_property``. -For example, to get the directory of the ``freertos`` component: - -.. code-block: cmake - - idf_component_get_property(dir freertos COMPONENT_DIR) - message(STATUS "The 'freertos' component directory is: ${dir}") - -- COMPONENT_ALIAS - alias for COMPONENT_LIB used for linking the component to external targets; set by ``idf_build_component`` and alias library itself - is created by ``idf_component_register`` -- COMPONENT_DIR - component directory; set by ``idf_build_component`` -- COMPONENT_LIB - name for created component static/interface library; set by ``idf_build_component`` and library itself - is created by ``idf_component_register`` -- COMPONENT_NAME - name of the component; set by ``idf_build_component`` based on the component directory name -- COMPONENT_TYPE - type of the component, whether LIBRARY or CONFIG_ONLY. A component is of type LIBRARY if it specifies - source files or embeds a file -- EMBED_FILES - list of files to embed in component; set from ``idf_component_register`` EMBED_FILES argument -- EMBED_TXTFILES - list of text files to embed in component; set from ``idf_component_register`` EMBED_TXTFILES argument -- INCLUDE_DIRS - list of component include directories; set from ``idf_component_register`` INCLUDE_DIRS argument -- KCONFIG - component Kconfig file; set by ``idf_build_component`` -- KCONFIG_PROJBUILD - component Kconfig.projbuild; set by ``idf_build_component`` -- LDFRAGMENTS - list of component linker fragment files; set from ``idf_component_register`` LDFRAGMENTS argument -- PRIV_INCLUDE_DIRS - list of component private include directories; set from ``idf_component_register`` PRIV_INCLUDE_DIRS on components of type LIBRARY -- PRIV_REQUIRES - list of private component dependentices; set from ``idf_component_register`` PRIV_REQUIRES argument -- REQUIRED_IDF_TARGETS - list of targets the component supports; set from ``idf_component_register`` EMBED_TXTFILES argument -- REQUIRES - list of public component dependencies; set from ``idf_component_register`` REQUIRES argument -- SRCS - list of component source files; set from SRCS or SRC_DIRS/EXCLUDE_SRCS argument of ``idf_component_register`` - -.. _cmake-file-globbing: - -File Globbing & Incremental Builds -================================== - -.. highlight:: cmake - -The preferred way to include source files in an ESP-IDF component is to list them manually via SRCS argument to ``idf_component_register``:: - - idf_component_register(SRCS library/a.c library/b.c platform/platform.c - ...) - -This preference reflects the `CMake best practice `_ of manually listing source files. This could, however, be inconvenient when there are lots of source files to add to the build. The ESP-IDF build system provides an alternative way for specifying source files using ``SRC_DIRS``:: - - idf_component_register(SRC_DIRS library platform - ...) - -This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new source file is added and this method is used, then CMake won't know to automatically re-run and this file won't be added to the build. - -The trade-off is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git... - -For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun. - -For project components (not part of ESP-IDF), there are a few different options: - -- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes. -- If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to automatically trigger re-runs of CMake when the Git revision changes. -- If not using Git, remember to manually run ``idf.py reconfigure`` whenever a source file may change. -- To avoid this problem entirely, use ``COMPONENT_SRCS`` to list all source files in project components. - -The best option will depend on your particular project and its users. - -Build System Metadata -===================== - -For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command). - -- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it. -- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc. -- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_. -- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc. -- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values. -- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs. - -JSON Configuration Server -------------------------- - -.. highlight :: json - -A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout. - -You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator. - -The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``:: - - {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } } - -Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.) - -The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline:: - - {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } } - -The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes:: - - {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}} - -Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value. - -If the range of a config item changes, due to conditional range depending on another value, then this is also sent:: - - {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } } - -If invalid data is passed, an "error" field is present on the object:: - - {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]} - -By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent:: - - {"version": 1, "save": null } - -To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent:: - - {"version": 1, "load": null } - -The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname. - -The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started. - -Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command. - -.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited. - -.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run. - -.. _gnu-make-to-cmake: - -Migrating from ESP-IDF GNU Make System -====================================== - -Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax. - -Automatic Conversion Tool -------------------------- - -.. highlight:: bash - -An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this:: - - $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir - -The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH. - -The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files. - -It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables. - -The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand. - -No Longer Available in CMake ----------------------------- - -Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system: - -- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead. -- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component. -- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here `_. -- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually. -- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead. -- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``. -- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repository. -- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute). -- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``. -- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead. -- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality `. -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details. -- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_. -- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_. - - -No Default Values ------------------ - -The following variables no longer have default values: - -- ``COMPONENT_SRCDIRS`` -- ``COMPONENT_ADD_INCLUDEDIRS`` - -No Longer Necessary -------------------- - -It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCS`` is ignored if ``COMPONENT_SRCDIRS`` is set). - -Flashing from make ------------------- - -``make flash`` and similar targets still work to build and flash. However, project ``sdkconfig`` no longer specifies serial port and baud rate. Environment variables can be used to override these. See :ref:`flash-with-ninja-or-make` for more details. - -.. _esp-idf-template: https://github.com/espressif/esp-idf-template -.. _cmake: https://cmake.org -.. _ninja: https://ninja-build.org -.. _esptool.py: https://github.com/espressif/esptool/#readme -.. _CMake v3.5 documentation: https://cmake.org/cmake/help/v3.5/index.html -.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options -.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/add_library.html -.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html -.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html -.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html -.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html -.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html -.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F -.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html -.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html -.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages -.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html -.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html -.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries -.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html -.. _quirc: https://github.com/dlbeer/quirc -.. _pyenv: https://github.com/pyenv/pyenv#README -.. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/en/api-guides/build-system-legacy.rst b/docs/en/api-guides/build-system-legacy.rst new file mode 100644 index 000000000..5f936c05f --- /dev/null +++ b/docs/en/api-guides/build-system-legacy.rst @@ -0,0 +1,650 @@ +Build System +************ +:link_to_translation:`zh_CN:[中文]` + +This document explains the Espressif IoT Development Framework build system and the +concept of "components" + +Read this document if you want to know how to organise a new ESP-IDF project. + +We recommend using the esp-idf-template_ project as a starting point for your project. + +Using the Build System +====================== + +The esp-idf README file contains a description of how to use the build system to build your project. + +Overview +======== + +An ESP-IDF project can be seen as an amalgamation of a number of components. +For example, for a webserver that shows the current humidity, there could be: + +- The ESP32 base libraries (libc, rom bindings etc) +- The 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 environment will look up all the +components in the ESP-IDF directories, the project directories and +(optionally) in additional custom component directories. It then +allows the user to configure the ESP-IDF project using a a text-based +menu system to customize each component. After the components in the +project are configured, the build process will compile the project. + +Concepts +-------- + +- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader. + +- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. + +- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). + +- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places. + +Some things are not part of the project: + +- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project. + +- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration. + + +Example Project +--------------- + +An example project directory tree might look like this:: + + - myProject/ + - Makefile + - sdkconfig + - components/ - component1/ - component.mk + - Kconfig + - src1.c + - component2/ - component.mk + - Kconfig + - src1.c + - include/ - component2.h + - main/ - src1.c + - src2.c + - component.mk + + - build/ + +This example "myProject" contains the following elements: + +- A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) defines + other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which + implements the rest of the ESP-IDF build system. + +- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project. + +- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF. + +- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places. + +- "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. + +Component directories contain a component makefile - ``component.mk``. This may contain variable definitions +to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details. + +Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`. + +Project Makefiles +----------------- + +Each project has a single Makefile that contains build settings for the entire project. By default, the project Makefile can be quite minimal. + +Minimal Example Makefile +^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + PROJECT_NAME := myProject + + include $(IDF_PATH)/make/project.mk + + +Mandatory Project Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin, myProject.elf. + +Optional Project Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These variables all have default values that can be overridden for custom behaviour. Look in ``make/project.mk`` for all of the implementation details. + +- ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile. Many other project variables are based on this variable. The project path cannot contain spaces. +- ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJECT_PATH)/build``. +- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `$(PROJECT_PATH)/components`, ``$(PROJECT_PATH)/main`` and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. +- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. +- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories. +- ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Note that this decreases build time, but not binary size. +- ``TEST_EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process of unit tests. + +Any paths in these Makefile variables should be absolute paths. You can convert relative paths using ``$(PROJECT_PATH)/xxx``, ``$(IDF_PATH)/xxx``, or use the Make function ``$(abspath xxx)``. + +These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile. + +Component Makefiles +------------------- + +Each project contains one or more components, which can either be part of esp-idf or added from other component directories. + +A component is any directory that contains a ``component.mk`` file. + +Searching for Components +------------------------ + +The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `component.mk` file), or they can be top-level directories whose subdirectories are components. + +Running the ``make list-components`` target dumps many of these variables and can help debug the discovery of component directories. + +Multiple components with the same name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the +idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories +contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components +with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. +If used in this way, the esp-idf directory itself can remain untouched. + +Minimal Component Makefile +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set: + +- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) will be compiled into the component library +- A sub-directory "include" will be added to the global include search path for all other components. +- The component library will be linked into the project app. + +See `example component makefiles`_ for more complete component makefile examples. + +Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process. + +.. component variables: + +Preset Component Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following component-specific variables are available for use inside ``component.mk``, but should not be modified: + +- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. +- ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory. +- ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a directory inside `$(BUILD_DIR_BASE)` where this component's source files are to be built. This is also the Current Working Directory any time the component is being built, so relative paths in make targets, etc. will be relative to this directory. +- ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory) that will be built for this component. Defaults to ``$(COMPONENT_NAME).a``. + +The following variables are set at the project level, but exported for use in the component build: + +- ``PROJECT_NAME``: Name of the project, as set in project Makefile +- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. +- ``COMPONENTS``: Name of all components that are included in this build. +- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. +- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. +- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. +- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`. +- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values. +- ``PROJECT_VER``: Project version. + + * If ``PROJECT_VER`` variable is set in project Makefile file, its value will be used. + * Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``. + * Else, if the project is located inside a Git repository, the output of git describe will be used. + * Otherwise, ``PROJECT_VER`` will be "1". + +If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug. + +Optional Project-Wide Component Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables can be set inside ``component.mk`` to control build settings across the entire project: + +- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component + directory, which will be added to the include search path for + all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile + this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead. +- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for + the app executable. Defaults to ``-l$(COMPONENT_NAME)``. If + adding pre-compiled libraries to this directory, add them as + absolute paths - ie $(COMPONENT_PATH)/libwhatever.a +- ``COMPONENT_DEPENDS``: Optional list of component names that should + be compiled before this component. This is not necessary for + link-time dependencies, because all component include directories + are available at all times. It is necessary if one component + generates an include file which you then want to include in another + component. Most components do not need to set this variable. +- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths + to files which should trigger a re-link of the ELF file if they change. + Typically used for linker script files and binary libraries. Most components do + not need to set this variable. + +The following variable only works for components that are part of esp-idf itself: + +- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths + (relative to COMPONENT_PATH) used by the component. These will be + checked (and initialised if necessary) by the build process. This + variable is ignored if the component is outside the IDF_PATH + directory. + + +Optional Component-Specific Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables can be set inside ``component.mk`` to control the build of that component: + +- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to + the component directory, which will be added to the include search + path for this component's source files only. +- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when + compiling the component's source files. These will be prefixed with + '-I' and passed as-is to the compiler. Similar to the + ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not + expanded relative to the component directory. +- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the + component directory, which will be searched for source files (``*.cpp``, + ``*.c``, ``*.S``). Defaults to '.', ie the component directory + itself. Override this to specify a different list of directories + which contain source files. +- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o + file for each source file that is found in ``COMPONENT_SRCDIRS``. + Overriding this list allows you to exclude source files in + ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See + `Specifying source files` +- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build + directory, of any files that are generated using custom make rules + in the component.mk file and which need to be removed as part of + ``make clean``. See `Source Code Generation`_ for an example. +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These + targets allow you to fully override the default build behaviour for + the component. See `Fully Overriding The Component Makefile`_ for + more details. +- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component + produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built), + and most other component variables are ignored. This flag is used for IDF + internal components which contain only ``KConfig.projbuild`` and/or + ``Makefile.projbuild`` files to configure the project, but no source files. +- ``CFLAGS``: Flags passed to the C compiler. A default set of + ``CFLAGS`` is defined based on project settings. Component-specific + additions can be made via ``CFLAGS +=``. It is also possible + (although not recommended) to override this variable completely for + a component. +- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp + and .S files). A default set of ``CPPFLAGS`` is defined based on + project settings. Component-specific additions can be made via + ``CPPFLAGS +=``. It is also possible (although not recommended) to + override this variable completely for a component. +- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of + ``CXXFLAGS`` is defined based on project + settings. Component-specific additions can be made via ``CXXFLAGS + +=``. It is also possible (although not recommended) to override + this variable completely for a component. +- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker + script generation functionality. See :doc:`Linker Script Generation `. + +To apply compilation flags to a single source file, you can add a variable override as a target, ie:: + + apps/dhcpserver.o: CFLAGS += -Wno-unused-variable + +This can be useful if there is upstream code that emits warnings. + +Component Configuration +----------------------- + +Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains +configuration settings to add to the "make menuconfig" for this component. + +These settings are found under the "Component Settings" menu when menuconfig is run. + +To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf. + +For an example, see `Adding conditional configuration`_. + +Preprocessor Definitions +------------------------ + +ESP-IDF build systems adds the following C preprocessor definitions on the command line: + +- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF. +- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details. + +Build Process Internals +----------------------- + +Top Level: Project Makefile +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- "make" is always run from the project directory and the project makefile, typically named Makefile. +- The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project variables` +- The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic. +- ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top. +- ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`. +- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top. +- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. +- By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets. +- In order to compile each component, a recursive make is performed for the component makefile. + +To better understand the project make process, have a read through the ``project.mk`` file itself. + +Second Level: Component Makefiles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper makefile. +- This component wrapper includes all component ``Makefile.componentbuild`` files, making any recipes, variables etc in these files available to every component. +- The ``component_wrapper.mk`` is called with the current directory set to the component build directory, and the ``COMPONENT_MAKEFILE`` variable is set to the absolute path to ``component.mk``. +- ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `component.mk` file which can override or modify these. +- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file. +- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration. + +To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf. + +Running Make Non-Interactively +------------------------------ + +When running ``make`` in a situation where you don't want interactive prompts (for example: inside an IDE or an automated build system) append ``BATCH_BUILD=1`` to the make arguments (or set it as an environment variable). + +Setting ``BATCH_BUILD`` implies the following: + +- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``. +- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item. +- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails. + +.. _make-size: + +Advanced Make Targets +--------------------- + +- ``make app``, ``make bootloader``, ``make partition table`` can be used to build only the app, bootloader, or partition table from the project as applicable. +- ``make erase_flash`` and ``make erase_ota`` will use esptool.py to erase the entire flash chip and the OTA selection setting from the flash chip, respectively. +- ``make size`` prints some size information about the app. ``make size-components`` and ``make size-files`` are similar targets which print more detailed per-component or per-source-file information, respectively. + + +Debugging The Make Process +-------------------------- + +Some tips for debugging the esp-idf build system: + +- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make. +- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands. +- Running ``make --trace`` (possibly in addition to one of the above arguments) will print out every target as it is built, and the dependency which caused it to be built. +- Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile. + +For more debugging tips and general make information, see the `GNU Make Manual`. + +.. _warn-undefined-variables: + +Warning On Undefined Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names. + +If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`. + +Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles. + +Overriding Parts of the Project +------------------------------- + +Makefile.projbuild +^^^^^^^^^^^^^^^^^^ + +For components that have build requirements that must be evaluated in the top-level +project make pass, you can create a file called ``Makefile.projbuild`` in the +component directory. This makefile is included when ``project.mk`` is evaluated. + +For example, if your component needs to add to CFLAGS for the entire +project (not just for its own source files) then you can set +``CFLAGS +=`` in Makefile.projbuild. + +``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". + +Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details. + +Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components! + +KConfig.projbuild +^^^^^^^^^^^^^^^^^ + +This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include +configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file. + +Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`. + + +Makefile.componentbuild +^^^^^^^^^^^^^^^^^^^^^^^ + +For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions +into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included +in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're +included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component. + +Configuration-Only Components +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some special components which contain no source files, only ``Kconfig.projbuild`` and ``Makefile.projbuild``, may set the flag ``COMPONENT_CONFIG_ONLY`` in the component.mk file. If this flag is set, most other component variables are ignored and no build step is run for the component. + +Example Component Makefiles +--------------------------- + +Because the build environment tries to set reasonable defaults that will work most +of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality. + +Here are some more advanced examples of ``component.mk`` makefiles: + + +Adding source directories +^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, sub-directories are ignored. If your project has sources in sub-directories +instead of in the root of the component then you can tell that to the build +system by setting ``COMPONENT_SRCDIRS``:: + + COMPONENT_SRCDIRS := src1 src2 + +This will compile all source files in the src1/ and src2/ sub-directories +instead. + +Specifying source files +^^^^^^^^^^^^^^^^^^^^^^^ + +The standard component.mk logic adds all .S and .c files in the source +directories as sources to be compiled unconditionally. It is possible +to circumvent that logic and hard-code the objects to be compiled by +manually setting the ``COMPONENT_OBJS`` variable to the name of the +objects that need to be generated:: + + COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o + COMPONENT_SRCDIRS := . thing anotherthing + +Note that ``COMPONENT_SRCDIRS`` must be set as well. + +Adding conditional configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The configuration system can be used to conditionally compile some files +depending on the options selected in ``make menuconfig``. For this, ESP-IDF +has the compile_only_if and compile_only_if_not macros: + +``Kconfig``:: + + config FOO_ENABLE_BAR + bool "Enable the BAR feature." + help + This enables the BAR feature of the FOO component. + +``component.mk``:: + + $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) + + +As can be seen in the example, the ``compile_only_if`` macro takes a condition and a +list of object files as parameters. If the condition is true (in this case: if the +BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will +always be compiled. The opposite goes as well: if the condition is not true, bar.o +will never be compiled. ``compile_only_if_not`` does the opposite: compile if the +condition is false, not compile if the condition is true. + +This can also be used to select or stub out an implementation, as such: + +``Kconfig``:: + + config ENABLE_LCD_OUTPUT + bool "Enable LCD output." + help + Select this if your board has a LCD. + + config ENABLE_LCD_CONSOLE + bool "Output console text to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output debugging output to the lcd + + config ENABLE_LCD_PLOT + bool "Output temperature plots to LCD" + depends on ENABLE_LCD_OUTPUT + help + Select this to output temperature plots + + +``component.mk``:: + + # If LCD is enabled, compile interface to it, otherwise compile dummy interface + $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o) + $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o) + + #We need font if either console or plot is enabled + $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) + +Note the use of the Make 'or' function to include the font file. Other substitution functions, +like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also +be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains +only whitespace to be false while a variable with any non-whitespace in it is true. + +(Note: Older versions of this document advised conditionally adding object file names to +``COMPONENT_OBJS``. While this still is possible, this will only work when all object +files for a component are named explicitely, and will not clean up deselected object files +in a ``make clean`` pass.) + +Source Code Generation +^^^^^^^^^^^^^^^^^^^^^^ + +Some components will have a situation where a source file isn't +supplied with the component itself but has to be generated from +another file. Say our component has a header file that consists of the +converted binary data of a BMP file, converted using a hypothetical +tool called bmp2h. The header file is then included in as C source +file called graphics_lib.c:: + + COMPONENT_EXTRA_CLEAN := logo.h + + graphics_lib.o: logo.h + + logo.h: $(COMPONENT_PATH)/logo.bmp + bmp2h -i $^ -o $@ + + +In this example, graphics_lib.o and logo.h will be generated in the +current directory (the build directory) while logo.bmp comes with the +component and resides under the component path. Because logo.h is a +generated file, it needs to be cleaned when make clean is called which +why it is added to the COMPONENT_EXTRA_CLEAN variable. + +Cosmetic Improvements +^^^^^^^^^^^^^^^^^^^^^ + +Because logo.h is a generated file, it needs to be cleaned when make +clean is called which why it is added to the COMPONENT_EXTRA_CLEAN +variable. + +Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be +generated before ``graphics_lib.c`` is compiled. + +If a a source file in another component included ``logo.h``, then this +component's name would have to be added to the other component's +``COMPONENT_DEPENDS`` list to ensure that the components were built +in-order. + +Embedding Binary Data +^^^^^^^^^^^^^^^^^^^^^ + +Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source. + +You can set a variable COMPONENT_EMBED_FILES in component.mk, giving the names of the files to embed in this way:: + + COMPONENT_EMBED_FILES := server_root_cert.der + +Or if the file is a string, you can use the variable COMPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string:: + + COMPONENT_EMBED_TXTFILES := server_root_cert.pem + +The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows:: + + extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); + extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); + +The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. + +For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time. + +Code and Data Placements +------------------------ + +ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through +linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking +app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion +of the mechanism. + +Fully Overriding The Component Makefile +--------------------------------------- + +Obviously, there are cases where all these recipes are insufficient for a +certain component, for example when the component is basically a wrapper +around another third-party component not originally intended to be +compiled under this build system. In that case, it's possible to forego +the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and +possibly COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk`` +target. The build target can do anything as long as it creates +$(COMPONENT_LIBRARY) for the project make process to link into the app binary. + +(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable +is overridden then the component can instruct the linker to link other binaries instead.) + +.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. + +.. _esp-idf-template: https://github.com/espressif/esp-idf-template +.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html + + +.. _custom-sdkconfig-defaults: + +Custom sdkconfig defaults +------------------------- + +For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch. + +To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable. + + +Save flash arguments +-------------------- + +There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. We can use command ``make print_flash_cmd``, it will print the flash arguments:: + + --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin + +Then use flash arguments as the arguemnts for esptool write_flash arguments:: + + python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin + +Building the Bootloader +======================= + +The bootloader is built by default as part of "make all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list-components" to see the components included in the bootloader build. + +The component in IDF components/bootloader is special, as the second stage bootloader is a separate .ELF and .BIN file to the main project. However it shares its configuration and build directory with the main project. + +This is accomplished by adding a subproject under components/bootloader/subproject. This subproject has its own Makefile, but it expects to be called from the project's own Makefile via some glue in the components/bootloader/Makefile.projectbuild file. See these files for more details. diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 5f936c05f..ec63c0fc4 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -1,18 +1,16 @@ -Build System -************ +Build System (CMake) +******************** + :link_to_translation:`zh_CN:[中文]` -This document explains the Espressif IoT Development Framework build system and the -concept of "components" +.. include:: ../cmake-warning.rst -Read this document if you want to know how to organise a new ESP-IDF project. +.. include:: ../cmake-pending-features.rst -We recommend using the esp-idf-template_ project as a starting point for your project. +This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components". :doc:`Documentation for the GNU Make based build system ` is also available -Using the Build System -====================== +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. -The esp-idf README file contains a description of how to use the build system to build your project. Overview ======== @@ -20,7 +18,7 @@ Overview An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be: -- The ESP32 base libraries (libc, rom bindings etc) +- The ESP32 base libraries (libc, ROM bindings, etc) - The WiFi drivers - A TCP/IP stack - The FreeRTOS operating system @@ -29,445 +27,537 @@ For example, for a webserver that shows the current humidity, there could be: - Main code tying it all together ESP-IDF makes these components explicit and configurable. To do that, -when a project is compiled, the build environment will look up all the +when a project is compiled, the build system will look up all the components in the ESP-IDF directories, the project directories and (optionally) in additional custom component directories. It then allows the user to configure the ESP-IDF project using a a text-based menu system to customize each component. After the components in the -project are configured, the build process will compile the project. +project are configured, the build system will compile the project. Concepts -------- -- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader. +- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader. -- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. +- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration. -- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). +- An "app" is an executable which is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app). -- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places. +- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places. + +- "Target" is the hardware for which an application is built. At the moment, ESP-IDF supports only one target, ``esp32``. Some things are not part of the project: - "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project. -- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration. +- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH. +Using the Build System +====================== + +.. _idf.py: + +idf.py +------ + +The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools: + +- CMake_, which configures the project to be built +- A command line build tool (either Ninja_ build or `GNU Make`) +- `esptool.py`_ for flashing ESP32. + +The :ref:`getting started guide ` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects. + +``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``. + +Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones: + +- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project. +- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps: + + - Create the build directory if needed. The sub-directory ``build`` is used to hold build output, although this can be changed with the ``-B`` option. + - Run CMake_ as necessary to configure the project and generate build files for the main build tool. + - Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``. + + Building is incremental so if no source files or configuration has changed since the last build, nothing will be done. +- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files. +- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted. +- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively. +- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`tools/idf-monitor` for more details about using the monitor. + +Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor. + +.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default. + +.. _idf.py-size: + +Advanced Commands +^^^^^^^^^^^^^^^^^ + +- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable. +- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32. +- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip. +- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text. +- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``. + +The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.). + +Using CMake Directly +-------------------- + +:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer. + +.. highlight:: bash + +When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt):: + + mkdir -p build + cd build + cmake .. -G Ninja # or 'Unix Makefiles' + ninja + +In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: running ``ninja`` actually builds the project. + +It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration. + +If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``. + +.. note:: + If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components. + +.. _flash-with-ninja-or-make: + +Flashing with ninja or make +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It's possible to build and flash directly from ninja or make by running a target like:: + + ninja flash + +Or:: + + make app-flash + +Available targets are: ``flash``, ``app-flash`` (app only), ``bootloader-flash`` (bootloader only). + +When flashing this way, optionally set the ``ESPPORT`` and ``ESPBAUD`` environment variables to specify the serial port and baud rate. You can set environment variables in your operating system or IDE project. Alternatively, set them directly on the command line:: + + ESPPORT=/dev/ttyUSB0 ninja flash + +.. note:: Providing environment variables at the start of the command like this is Bash shell Syntax. It will work on Linux and macOS. It won't work when using Windows Command Prompt, but it will work when using Bash-like shells on Windows. + +Or:: + + make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000 + +.. note:: Providing variables at the end of the command line is ``make`` syntax, and works for ``make`` on all platforms. + + +Using CMake in an IDE +--------------------- + +You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE. + +When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands. + +For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_. + +.. _setting-python-interpreter: + +Setting the Python Interpreter +------------------------------ + +Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems. + +If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command. + +If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter. + +If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter. + +To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version. + +.. _example-project-structure: Example Project ---------------- +=============== + +.. highlight:: none An example project directory tree might look like this:: - myProject/ - - Makefile + - CMakeLists.txt - sdkconfig - - components/ - component1/ - component.mk + - components/ - component1/ - CMakeLists.txt - Kconfig - src1.c - - component2/ - component.mk + - component2/ - CMakeLists.txt - Kconfig - src1.c - include/ - component2.h - main/ - src1.c - src2.c - - component.mk - build/ This example "myProject" contains the following elements: -- A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) defines - other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which - implements the rest of the ESP-IDF build system. +- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file :idf_file:`/tools/cmake/project.cmake` which + implements the rest of the build system. Finally, it sets the project name and defines the project. -- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project. +- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project. - Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF. -- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places. +- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places. See the :ref:`renaming main ` section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main". -- "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. +- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code. -Component directories contain a component makefile - ``component.mk``. This may contain variable definitions -to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details. +Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions +to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details. -Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`. +Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_. -Project Makefiles ------------------ +Project CMakeLists File +======================= -Each project has a single Makefile that contains build settings for the entire project. By default, the project Makefile can be quite minimal. +Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal. -Minimal Example Makefile -^^^^^^^^^^^^^^^^^^^^^^^^ +Minimal Example CMakeLists +-------------------------- -:: +.. highlight:: cmake - PROJECT_NAME := myProject - - include $(IDF_PATH)/make/project.mk +Minimal project:: + + cmake_minimum_required(VERSION 3.5) + include($ENV{IDF_PATH}/tools/cmake/project.cmake) + project(myProject) -Mandatory Project Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _project-mandatory-parts: + +Mandatory Parts +--------------- + +The inclusion of these three lines, in the order shown above, is necessary for every project: + +- ``cmake_minimum_required(VERSION 3.5)`` tells CMake the minimum version that is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file. +- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc. +- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file. -- ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin, myProject.elf. Optional Project Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- -These variables all have default values that can be overridden for custom behaviour. Look in ``make/project.mk`` for all of the implementation details. +These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details. -- ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile. Many other project variables are based on this variable. The project path cannot contain spaces. -- ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJECT_PATH)/build``. -- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `$(PROJECT_PATH)/components`, ``$(PROJECT_PATH)/main`` and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. -- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. -- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories. -- ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Note that this decreases build time, but not binary size. -- ``TEST_EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process of unit tests. +- ``COMPONENT_DIRS``,``COMPONENTS_DIRS``: Directories to search for components. Defaults to `IDF_PATH/components`, `PROJECT_DIR/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places. +- ``EXTRA_COMPONENT_DIRS``, ``EXTRA_COMPONENTS_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute. +- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via the REQUIRES or PRIV_REQUIRES arguments on component registration will automatically have it added to this list, so the ``COMPONENTS`` list can be very short. -Any paths in these Makefile variables should be absolute paths. You can convert relative paths using ``$(PROJECT_PATH)/xxx``, ``$(IDF_PATH)/xxx``, or use the Make function ``$(abspath xxx)``. +Any paths in these variables can be absolute paths, or set relative to the project directory. -These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile. +To set these variables, use the `cmake set command `_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line. -Component Makefiles -------------------- +.. _rename-main-cmake: -Each project contains one or more components, which can either be part of esp-idf or added from other component directories. +Renaming ``main`` component +---------------------------- -A component is any directory that contains a ``component.mk`` file. +The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided +that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, +saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component +causes the loss of these behind-the-scences heavy lifting, requiring the user to specify the location of the newly renamed component +and manually specifying its dependencies. Specifically, the steps to renaming ``main`` are as follows: + +1. Rename ``main`` directory. +2. Set ``EXTRA_COMPONENT_DIRS`` in the project CMakeLists.txt to include the renamed ``main`` directory. +3. Specify the dependencies in the renamed component's CMakeLists.txt file via REQUIRES or PRIV_REQUIRES arguments :ref:`on component registration`. + +.. _component-directories-cmake: + +Component CMakeLists Files +========================== + +Each project contains one or more components. Components can be part of ESP-IDF, part of the project's own components directory, or added from custom component directories (:ref:`see above `). + +A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file. Searching for Components ------------------------ -The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `component.mk` file), or they can be top-level directories whose subdirectories are components. +The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose sub-directories are components. -Running the ``make list-components`` target dumps many of these variables and can help debug the discovery of component directories. +When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components. Multiple components with the same name -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------- -When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the -idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories -contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components -with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. -If used in this way, the esp-idf directory itself can remain untouched. +When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories +contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components +with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. +If used in this way, the ESP-IDF directory itself can remain untouched. -Minimal Component Makefile -^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _cmake_minimal_component_cmakelists: -The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set: +Minimal Component CMakeLists +---------------------------- -- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) will be compiled into the component library -- A sub-directory "include" will be added to the global include search path for all other components. -- The component library will be linked into the project app. +.. highlight:: cmake -See `example component makefiles`_ for more complete component makefile examples. +The minimal component ``CMakeLists.txt`` file simply registers the component to the build system using ``idf_component_register``:: -Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process. + idf_component_register(SRCS "foo.c" "bar.c" + INCLUDE_DIRS "include") -.. component variables: +- ``SRCS`` is a list of source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``). These source files will be compiled into the component library. +- ``INCLUDE_DIRS`` is a list of directories to add to the global include search path for any component which requires this component, and also the main source files. + +A library with the name of the component will be built and linked into the final app. +Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute. + +There are other arguments that can be passed to ``idf_component_register``. These arguments +are discussed :ref:`here`. + +See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples. + +.. _component variables: Preset Component Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- -The following component-specific variables are available for use inside ``component.mk``, but should not be modified: +The following component-specific variables are available for use inside component CMakeLists, but should not be modified: -- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. -- ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory. -- ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a directory inside `$(BUILD_DIR_BASE)` where this component's source files are to be built. This is also the Current Working Directory any time the component is being built, so relative paths in make targets, etc. will be relative to this directory. -- ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory) that will be built for this component. Defaults to ``$(COMPONENT_NAME).a``. +- ``COMPONENT_DIR``: The component directory. Evaluates to the absolute path of the directory containing ``CMakeLists.txt``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable. +- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory. +- ``COMPONENT_ALIAS``: Alias of the library created internally by the build system for the component. +- ``COMPONENT_LIB``: Name of the library created internally by the build system for the component. -The following variables are set at the project level, but exported for use in the component build: +The following variables are set at the project level, but available for use in component CMakeLists: -- ``PROJECT_NAME``: Name of the project, as set in project Makefile -- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. -- ``COMPONENTS``: Name of all components that are included in this build. -- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. -- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. -- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. -- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`. -- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values. -- ``PROJECT_VER``: Project version. +- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in cmake. All names begin with ``CONFIG_``. :doc:`More information here `. +- ``ESP_PLATFORM``: Set to 1 when the CMake file is processed within ESP-IDF build system. - * If ``PROJECT_VER`` variable is set in project Makefile file, its value will be used. - * Else, if the ``$PROJECT_PATH/version.txt`` exists, its contents will be used as ``PROJECT_VER``. +Build/Project Variables +------------------------ + +The following are some project/build variables that are available as build properties and whose values can be queried using ``idf_build_get_property`` +from the component CMakeLists.txt: + +- ``PROJECT_NAME``: Name of the project, as set in project CMakeLists.txt file. +- ``PROJECT_DIR``: Absolute path of the project directory containing the project CMakeLists. Same as the ``CMAKE_SOURCE_DIR`` variable. +- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list. +- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``) +- ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``IDF_VERSION_*`` variables, but different ``IDF_VER`` values. +- ``IDF_TARGET``: Name of the target for which the project is being built. +- ``PROJECT_VER``: Project version. + + * If ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used. + * Else, if the ``PROJECT_DIR/version.txt`` exists, its contents will be used as ``PROJECT_VER``. * Else, if the project is located inside a Git repository, the output of git describe will be used. * Otherwise, ``PROJECT_VER`` will be "1". -If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug. +Other build properties are listed :ref:`here`. -Optional Project-Wide Component Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Controlling Component Compilation +--------------------------------- -The following variables can be set inside ``component.mk`` to control build settings across the entire project: +.. highlight:: cmake -- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component - directory, which will be added to the include search path for - all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile - this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead. -- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for - the app executable. Defaults to ``-l$(COMPONENT_NAME)``. If - adding pre-compiled libraries to this directory, add them as - absolute paths - ie $(COMPONENT_PATH)/libwhatever.a -- ``COMPONENT_DEPENDS``: Optional list of component names that should - be compiled before this component. This is not necessary for - link-time dependencies, because all component include directories - are available at all times. It is necessary if one component - generates an include file which you then want to include in another - component. Most components do not need to set this variable. -- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths - to files which should trigger a re-link of the ELF file if they change. - Typically used for linker script files and binary libraries. Most components do - not need to set this variable. +To pass compiler options when compiling source files belonging to a particular component, use the ``target_compile_options`` function:: -The following variable only works for components that are part of esp-idf itself: + target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable) -- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths - (relative to COMPONENT_PATH) used by the component. These will be - checked (and initialised if necessary) by the build process. This - variable is ignored if the component is outside the IDF_PATH - directory. +To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command:: - -Optional Component-Specific Variables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following variables can be set inside ``component.mk`` to control the build of that component: - -- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to - the component directory, which will be added to the include search - path for this component's source files only. -- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when - compiling the component's source files. These will be prefixed with - '-I' and passed as-is to the compiler. Similar to the - ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not - expanded relative to the component directory. -- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the - component directory, which will be searched for source files (``*.cpp``, - ``*.c``, ``*.S``). Defaults to '.', ie the component directory - itself. Override this to specify a different list of directories - which contain source files. -- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o - file for each source file that is found in ``COMPONENT_SRCDIRS``. - Overriding this list allows you to exclude source files in - ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See - `Specifying source files` -- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build - directory, of any files that are generated using custom make rules - in the component.mk file and which need to be removed as part of - ``make clean``. See `Source Code Generation`_ for an example. -- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These - targets allow you to fully override the default build behaviour for - the component. See `Fully Overriding The Component Makefile`_ for - more details. -- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component - produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built), - and most other component variables are ignored. This flag is used for IDF - internal components which contain only ``KConfig.projbuild`` and/or - ``Makefile.projbuild`` files to configure the project, but no source files. -- ``CFLAGS``: Flags passed to the C compiler. A default set of - ``CFLAGS`` is defined based on project settings. Component-specific - additions can be made via ``CFLAGS +=``. It is also possible - (although not recommended) to override this variable completely for - a component. -- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp - and .S files). A default set of ``CPPFLAGS`` is defined based on - project settings. Component-specific additions can be made via - ``CPPFLAGS +=``. It is also possible (although not recommended) to - override this variable completely for a component. -- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of - ``CXXFLAGS`` is defined based on project - settings. Component-specific additions can be made via ``CXXFLAGS - +=``. It is also possible (although not recommended) to override - this variable completely for a component. -- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker - script generation functionality. See :doc:`Linker Script Generation `. - -To apply compilation flags to a single source file, you can add a variable override as a target, ie:: - - apps/dhcpserver.o: CFLAGS += -Wno-unused-variable + set_source_files_properties(mysrc.c + PROPERTIES COMPILE_FLAGS + -Wno-unused-variable + ) This can be useful if there is upstream code that emits warnings. -Component Configuration ------------------------ +When using these commands, place them after the call to ``idf_component_register`` in the component CMakeLists file. -Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains -configuration settings to add to the "make menuconfig" for this component. +.. _component-configuration-cmake: + +Component Configuration +======================= + +Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains +configuration settings to add to the configuration menu for this component. These settings are found under the "Component Settings" menu when menuconfig is run. -To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf. +To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF. For an example, see `Adding conditional configuration`_. Preprocessor Definitions +======================== + +The ESP-IDF build system adds the following C preprocessor definitions on the command line: + +- ``ESP_PLATFORM`` : Can be used to detect that build happens within ESP-IDF. +- ``IDF_VER`` : Defined to a git version string. E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit. + +Component Requirements +====================== + +When compiling each component, the ESP-IDF build system recursively evaluates its components. + +Each component's source file is compiled with these include path directories, as specified in the passed arguments +to ``idf_component_register``: + +- The current component's ``INCLUDE_DIRS`` and ``PRIV_INCLUDE_DIRS``. +- The ``INCLUDE_DIRS`` set by all components in the current component's ``REQUIRES`` and ``PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies). +- All of the ``REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded). + +When writing a component ------------------------ -ESP-IDF build systems adds the following C preprocessor definitions on the command line: +- ``REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component. +- ``PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly. +- ``REQUIRES`` and/or ``PRIV_REQUIRES`` should be set before calling ``idf_component_register()``. +- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices. +- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset. -- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF. -- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details. +Components which support only some targets (values of ``IDF_TARGET``) may specify ``REQUIRED_IDF_TARGETS`` in the ``idf_component_register`` call to express these requirements. In this case the build system will generate an error if the component is included into the build, but does not support selected target. -Build Process Internals +When creating a project ----------------------- -Top Level: Project Makefile -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- By default, every component is included in the build. +- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include: -- "make" is always run from the project directory and the project makefile, typically named Makefile. -- The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project variables` -- The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic. -- ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top. -- ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`. -- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top. -- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. -- By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets. -- In order to compile each component, a recursive make is performed for the component makefile. + - Components mentioned explicitly in ``COMPONENTS``. + - Those components' requirements (evaluated recursively). + - The "common" components that every component depends on. +- Setting ``COMPONENTS`` to the minimal list of required components can significantly reduce compile times. -To better understand the project make process, have a read through the ``project.mk`` file itself. +.. _component-requirements-implementation: -Second Level: Component Makefiles -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Requirements in the build system implementation +----------------------------------------------- -- Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper makefile. -- This component wrapper includes all component ``Makefile.componentbuild`` files, making any recipes, variables etc in these files available to every component. -- The ``component_wrapper.mk`` is called with the current directory set to the component build directory, and the ``COMPONENT_MAKEFILE`` variable is set to the absolute path to ``component.mk``. -- ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `component.mk` file which can override or modify these. -- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file. -- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration. +- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory. +- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable). The ``BUILD_COMPONENTS`` variable is sorted so dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies. +- The value of ``BUILD_COMPONENTS`` is logged by CMake as "Component names: " +- Configuration is then evaluated for the components included in the build. +- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build. -To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf. +Component Dependency Order +^^^^^^^^^^^^^^^^^^^^^^^^^^ -Running Make Non-Interactively ------------------------------- +The order of components in the ``BUILD_COMPONENTS`` variable determines other orderings during the build: -When running ``make`` in a situation where you don't want interactive prompts (for example: inside an IDE or an automated build system) append ``BATCH_BUILD=1`` to the make arguments (or set it as an environment variable). +- Order that :ref:`project_include.cmake` files are included into the project. +- Order that the list of header paths is generated for compilation (via ``-I`` argument). (Note that for a given component's source files, only that component's dependency's header paths are passed to the compiler.) -Setting ``BATCH_BUILD`` implies the following: +Build Process Internals +======================= -- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``. -- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item. -- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails. +For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`_. -.. _make-size: +project.cmake contents +---------------------- -Advanced Make Targets ---------------------- +When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environment. -- ``make app``, ``make bootloader``, ``make partition table`` can be used to build only the app, bootloader, or partition table from the project as applicable. -- ``make erase_flash`` and ``make erase_ota`` will use esptool.py to erase the entire flash chip and the OTA selection setting from the flash chip, respectively. -- ``make size`` prints some size information about the app. ``make size-components`` and ``make size-files`` are similar targets which print more detailed per-component or per-source-file information, respectively. +It also defines an overridden custom version of the built-in CMake_ ``project`` function. This function is overridden to add all of the ESP-IDF specific project functionality. +project function +---------------- -Debugging The Make Process --------------------------- +The custom ``project()`` function performs the following steps: -Some tips for debugging the esp-idf build system: +- Determines the target (set by ``IDF_TARGET`` environment variable) and saves the target in CMake cache. If the target set in the environment does not match the one in cache, exits with an error. +- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above`). +- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set). +- Loads the project configuration from the ``sdkconfig`` file and generates a ``sdkconfig.cmake`` file and a ``sdkconfig.h`` header. These define configuration values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to re-generate these files and re-configure the project. +- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the correct toolchain file, depending on the target. +- Declares the actual cmake-level project by calling the `CMake project function `_. +- Loads the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_. +- Includes :ref:`project_include.cmake` files from any components which have them. +- Adds each component to the build. Each component CMakeLists file calls ``idf_component_register``, calls the CMake `add_library `_ function to add a library and then adds source files, compile options, etc. +- Adds the final app executable to the build. +- Goes back and adds inter-component dependencies between components (ie adding the public header directories of each component to each other component). -- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make. -- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands. -- Running ``make --trace`` (possibly in addition to one of the above arguments) will print out every target as it is built, and the dependency which caused it to be built. -- Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile. +Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details. -For more debugging tips and general make information, see the `GNU Make Manual`. +Debugging CMake +--------------- -.. _warn-undefined-variables: +Some tips for debugging the ESP-IDF CMake-based build system: + +- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths. +- Running ``cmake -DDEBUG=1`` will produce more verbose diagnostic output from the IDF build system. +- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_. + +.. _warn-undefined-variables-cmake: Warning On Undefined Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -By default, 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. +project_include.cmake +^^^^^^^^^^^^^^^^^^^^^ -For example, if your component needs to add to CFLAGS for the entire -project (not just for its own source files) then you can set -``CFLAGS +=`` in Makefile.projbuild. +For components that have build requirements which must be evaluated before any component CMakeLists +files are evaluated, you can create a file called ``project_include.cmake`` in the +component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project. -``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". +``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app". -Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details. +Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cmake`` file the current source directory (``CMAKE_CURRENT_SOURCE_DIR`` and working directory) is the project directory. Use the variable ``COMPONENT_DIR`` for the absolute directory of the component. -Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components! +Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details. + +``project_include.cmake`` files are included in the order given in ``BUILD_COMPONENTS`` variable (as logged by CMake). This means that a component's ``project_include.cmake`` file will be included after it's all dependencies' ``project_include.cmake`` files, unless both components are part of a dependency cycle. This is important if a ``project_include.cmake`` file relies on variables set by another component. See also :ref:`above`. + +Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components! KConfig.projbuild ^^^^^^^^^^^^^^^^^ -This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include -configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file. +This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration-cmake` KConfig files. If you want to include +configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file. -Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`. +Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for :ref:`component-configuration-cmake`. -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 ``idf_component_register()`` with no +arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths. -Example Component Makefiles ---------------------------- +Example Component CMakeLists +============================ Because the build environment tries to set reasonable defaults that will work most -of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality. +of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality. -Here are some more advanced examples of ``component.mk`` makefiles: - - -Adding source directories -^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, sub-directories are ignored. If your project has sources in sub-directories -instead of in the root of the component then you can tell that to the build -system by setting ``COMPONENT_SRCDIRS``:: - - COMPONENT_SRCDIRS := src1 src2 - -This will compile all source files in the src1/ and src2/ sub-directories -instead. - -Specifying source files -^^^^^^^^^^^^^^^^^^^^^^^ - -The standard component.mk logic adds all .S and .c files in the source -directories as sources to be compiled unconditionally. It is possible -to circumvent that logic and hard-code the objects to be compiled by -manually setting the ``COMPONENT_OBJS`` variable to the name of the -objects that need to be generated:: - - COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o - COMPONENT_SRCDIRS := . thing anotherthing - -Note that ``COMPONENT_SRCDIRS`` must be set as well. +Here are some more advanced examples of component CMakeLists files. Adding conditional configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------- The configuration system can be used to conditionally compile some files -depending on the options selected in ``make menuconfig``. For this, ESP-IDF -has the compile_only_if and compile_only_if_not macros: +depending on the options selected in the project configuration. + +.. highlight:: none ``Kconfig``:: @@ -476,17 +566,15 @@ has the compile_only_if and compile_only_if_not macros: help This enables the BAR feature of the FOO component. -``component.mk``:: +``CMakeLists.txt``:: - $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) + set(COMPONENT_SRCS "foo.c" "more_foo.c") + if(CONFIG_FOO_ENABLE_BAR) + list(APPEND COMPONENT_SRCS "bar.c") + endif() -As can be seen in the example, the ``compile_only_if`` macro takes a condition and a -list of object files as parameters. If the condition is true (in this case: if the -BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will -always be compiled. The opposite goes as well: if the condition is not true, bar.o -will never be compiled. ``compile_only_if_not`` does the opposite: compile if the -condition is false, not compile if the condition is true. +This example makes use of the CMake `if `_ function and `list APPEND `_ function. This can also be used to select or stub out an implementation, as such: @@ -509,28 +597,34 @@ This can also be used to select or stub out an implementation, as such: help Select this to output temperature plots +.. highlight:: cmake -``component.mk``:: +``CMakeLists.txt``:: - # If LCD is enabled, compile interface to it, otherwise compile dummy interface - $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o) - $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o) + if(CONFIG_ENABLE_LCD_OUTPUT) + set(COMPONENT_SRCS lcd-real.c lcd-spi.c) + else() + set(COMPONENT_SRCS lcd-dummy.c) + endif() - #We need font if either console or plot is enabled - $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) + # We need font if either console or plot is enabled + if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT) + list(APPEND COMPONENT_SRCS "font.c") + endif() -Note the use of the Make 'or' function to include the font file. Other substitution functions, -like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also -be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains -only whitespace to be false while a variable with any non-whitespace in it is true. -(Note: Older versions of this document advised conditionally adding object file names to -``COMPONENT_OBJS``. While this still is possible, this will only work when all object -files for a component are named explicitely, and will not clean up deselected object files -in a ``make clean`` pass.) +Conditions which depend on the target +------------------------------------- + +The current target is available to CMake files via ``IDF_TARGET`` variable. + +In addition to that, if target ``xyz`` is used (``IDF_TARGET=xyz``), then Kconfig variable ``CONFIG_IDF_TARGET_XYZ`` will be set. + +Note that component dependencies may depend on ``IDF_TARGET`` variable, but not on Kconfig variables. Also one can not use Kconfig variables in ``include`` statements in CMake files, but ``IDF_TARGET`` can be used in such context. + Source Code Generation -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- Some components will have a situation where a source file isn't supplied with the component itself but has to be generated from @@ -539,112 +633,679 @@ converted binary data of a BMP file, converted using a hypothetical tool called bmp2h. The header file is then included in as C source file called graphics_lib.c:: - COMPONENT_EXTRA_CLEAN := logo.h + add_custom_command(OUTPUT logo.h + COMMAND bmp2h -i ${COMPONENT_DIR}/logo.bmp -o log.h + DEPENDS ${COMPONENT_DIR}/logo.bmp + VERBATIM) - graphics_lib.o: logo.h + add_custom_target(logo DEPENDS logo.h) + add_dependencies(${COMPONENT_LIB} logo) - logo.h: $(COMPONENT_PATH)/logo.bmp - bmp2h -i $^ -o $@ + set_property(DIRECTORY "${COMPONENT_DIR}" APPEND PROPERTY + ADDITIONAL_MAKE_CLEAN_FILES logo.h) +This answer is adapted from the `CMake FAQ entry `_, which contains some other examples that will also work with ESP-IDF builds. -In this example, graphics_lib.o and logo.h will be generated in the +In this example, logo.h will be generated in the current directory (the build directory) while logo.bmp comes with the component and resides under the component path. Because logo.h is a -generated file, it needs to be cleaned when make clean is called which -why it is added to the COMPONENT_EXTRA_CLEAN variable. +generated file, it should be cleaned when the project is cleaned. For this reason +it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property. -Cosmetic Improvements -^^^^^^^^^^^^^^^^^^^^^ +.. note:: -Because logo.h is a generated file, it needs to be cleaned when make -clean is called which why it is added to the COMPONENT_EXTRA_CLEAN -variable. + If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use build property ``PROJECT_DIR`` instead of ``${COMPONENT_DIR}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_LIB}``.) -Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be -generated before ``graphics_lib.c`` is compiled. +If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between +the two components, to ensure that the component source files were always compiled in the correct order. -If a a source file in another component included ``logo.h``, then this -component's name would have to be added to the other component's -``COMPONENT_DEPENDS`` list to ensure that the components were built -in-order. +.. _cmake_embed_data: Embedding Binary Data -^^^^^^^^^^^^^^^^^^^^^ +--------------------- Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source. -You can set a variable COMPONENT_EMBED_FILES in component.mk, giving the names of the files to embed in this way:: +You can specify argument ``COMPONENT_EMBED_FILES`` in the component registration, giving space-delimited names of the files to embed:: - COMPONENT_EMBED_FILES := server_root_cert.der + idf_component_register(... + EMBED_FILES server_root_cert.der) -Or if the file is a string, you can use the variable COMPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string:: - COMPONENT_EMBED_TXTFILES := server_root_cert.pem +Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string:: + + idf_component_register(... + EMBED_TXTFILES server_root_cert.pem) + +.. highlight:: c The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows:: extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start"); extern const uint8_t server_root_cert_pem_end[] asm("_binary_server_root_cert_pem_end"); -The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. +The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. + +.. highlight:: cmake + +To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this:: + + target_add_binary_data(myproject.elf "main/data.bin" TEXT) + +Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is. For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time. Code and Data Placements ------------------------ -ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through -linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking +ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through +linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion of the mechanism. -Fully Overriding The Component Makefile ---------------------------------------- +.. _component-build-full-override: + +Fully Overriding The Component Build Process +-------------------------------------------- + +.. highlight:: cmake Obviously, there are cases where all these recipes are insufficient for a certain component, for example when the component is basically a wrapper around another third-party component not originally intended to be compiled under this build system. In that case, it's possible to forego -the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and -possibly COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk`` -target. The build target can do anything as long as it creates -$(COMPONENT_LIBRARY) for the project make process to link into the app binary. +the ESP-IDF build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists:: -(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable -is overridden then the component can instruct the linker to link other binaries instead.) + # External build process for quirc, runs in source dir and + # produces libquirc.a + externalproject_add(quirc_build + PREFIX ${COMPONENT_DIR} + SOURCE_DIR ${COMPONENT_DIR}/quirc + CONFIGURE_COMMAND "" + BUILD_IN_SOURCE 1 + BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a + INSTALL_COMMAND "" + ) + + # Add libquirc.a to the build process + # + add_library(quirc STATIC IMPORTED GLOBAL) + add_dependencies(quirc quirc_build) + + set_target_properties(quirc PROPERTIES IMPORTED_LOCATION + ${COMPONENT_DIR}/quirc/libquirc.a) + set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES + ${COMPONENT_DIR}/quirc/lib) + + set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES + "${COMPONENT_DIR}/quirc/libquirc.a") + +(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.) + +- ``externalproject_add`` defines an external build system. + + - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds. + - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``. + - Consult the ExternalProject_ documentation for more details about ``externalproject_add()`` + +- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is. +- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.) .. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. -.. _esp-idf-template: https://github.com/espressif/esp-idf-template -.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html +.. _ADDITIONAL_MAKE_CLEAN_FILES_note: +ExternalProject dependencies, clean builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. _custom-sdkconfig-defaults: +CMake has some unusual behaviour around external project builds: + +- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning. +- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run. +- Therefore, there are two alternative recommended ways to configure the external build command: + + 1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.) + 2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run. + +The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project. + +.. _custom-sdkconfig-defaults-cmake: Custom sdkconfig defaults -------------------------- +========================= -For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch. +For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file. To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable. +Target-dependent sdkconfig defaults +----------------------------------- -Save flash arguments --------------------- +In addition to ``sdkconfig.defaults`` file, build system will also load defaults from ``sdkconfig.defaults.TARGET_NAME`` file, where ``TARGET_NAME`` is the value of ``IDF_TARGET``. For example, for ``esp32`` target, default settings will be taken from ``sdkconfig.defaults`` first, and then from ``sdkconfig.defaults.esp32``. -There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. We can use command ``make print_flash_cmd``, it will print the flash arguments:: +If ``SDKCONFIG_DEFAULTS`` is used to override the name of defaults file, the name of target-specific defaults file will be derived from ``SDKCONFIG_DEFAULTS`` value. - --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin -Then use flash arguments as the arguemnts for esptool write_flash arguments:: +Flash arguments +=============== - python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin +There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. + +After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files: + +- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured). +- ``flash_app_args`` contains arguments to flash only the app. +- ``flash_bootloader_args`` contains arguments to flash only the bootloader. + +.. highlight:: bash + +You can pass any of these flasher argument files to ``esptool.py`` as follows:: + + python esptool.py --chip esp32 write_flash @build/flash_project_args + +Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line. + +The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build. Building the Bootloader ======================= -The bootloader is built by default as part of "make all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list-components" to see the components included in the bootloader build. +The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``. -The component in IDF components/bootloader is special, as the second stage bootloader is a separate .ELF and .BIN file to the main project. However it shares its configuration and build directory with the main project. +The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project. -This is accomplished by adding a subproject under components/bootloader/subproject. This subproject has its own Makefile, but it expects to be called from the project's own Makefile via some glue in the components/bootloader/Makefile.projectbuild file. See these files for more details. +The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``). + +Selecting the Target +==================== + +Currently ESP-IDF supports one target, ``esp32``. It is used by default by the build system. Developers working on adding multiple target support can change the target as follows:: + + rm sdkconfig + idf.py -DIDF_TARGET=new_target reconfigure + + +Writing Pure CMake Components +============================= + +The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build. + +However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake. + +.. highlight:: cmake + +Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``:: + + add_library(json STATIC + cJSON/cJSON.c + cJSON/cJSON_Utils.c) + + target_include_directories(json PUBLIC cJSON) + +- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`. +- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.) +- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands. + + +Using Third-Party CMake Projects with Components +================================================ + +CMake is used for a lot of open-source C and C++ projects — code that users can tap into for their applications. One of the benefits of having a CMake build system +is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may +not yet be provided by a component, or use another library for the same functionality. + +.. highlight:: cmake + +Importing a library might look like this for a hypothetical library ``foo`` to be used in the ``main`` component:: + + # Register the component + idf_component_register() + + # Set values of hypothetical variables that control the build of `foo` + set(FOO_BUILD_STATIC OFF) + set(FOO_BUILD_TESTS OFF) + + # Create and import the library targets + add_subdirectory(foo) + + # Link `foo` to `main` component + target_link_libraries(main foo) + +For an actual example, take a look at :example:`build_system/cmake/import_lib`. Take note that what needs to be done in order to import +the library may vary. It is recommended to read up on the library's documentation for instructions on how to +import it from other projects. Studying the library's CMakeLists.txt and build structure can also be helpful. + +It is also possible to wrap a third-party library to be used as a component in this manner. For example, the :component:`mbedtls` component is a wrapper for +Espressif's fork of `mbedtls `_. See its :component_file:`component CMakeLists.txt `. + +The CMake variable ``ESP_PLATFORM`` is set to 1 whenever the ESP-IDF build system is being used. Tests such as ``if (ESP_PLATFORM)`` can be used in generic CMake code if special IDF-specific logic is required. + + +Using ESP-IDF in Custom CMake Projects +====================================== + +ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already +have an existing CMake project or may want to create a custom one. In these cases it is desirable to be able to consume IDF components +as libraries to be linked to the user's targets (libraries/ executables). + +It is possible to do so by using the :ref:`build system APIs provided` by :idf_file:`tools/cmake/idf.cmake`. For example: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.5) + project(my_custom_app C) + + # Include CMake file that provides ESP-IDF CMake build system APIs. + include($ENV{IDF_PATH}/tools/cmake/idf.cmake) + + # Include ESP-IDF components in the build, may be thought as an equivalent of + # add_subdirectory() but with some additional procesing and magic for ESP-IDF build + # specific build processes. + idf_build_process(esp32) + + # Create the project executable and plainly link the newlib component to it using + # its alias, idf::newlib. + add_executable(${CMAKE_PROJECT_NAME}.elf main.c) + target_link_libraries(${CMAKE_PROJECT_NAME}.elf idf::newlib) + + # Let the build system know what the project executable is to attach more targets, dependencies, etc. + idf_build_executable(${CMAKE_PROJECT_NAME}.elf) + +The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creation of an application equivalent to :example:`hello world application ` +using a custom CMake project. + +.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag. +.. _cmake_buildsystem_api: + +ESP-IDF CMake Build System API +============================== + +idf-build-commands +------------------ + +.. code-block:: none + + idf_build_get_property(var property [GENERATOR_EXPRESSION]) + +Retrieve a :ref:`build property` *property* and store it in *var* accessible from the current scope. Specifying +*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which +can be used with CMake commands that support generator expressions. + +.. code-block:: none + + idf_build_set_property(property val [APPEND]) + +Set a :ref:`build property` *property* with value *val*. Specifying *APPEND* will append the specified value to the current +value of the property. If the property does not previously exist or it is currently empty, the specified value becomes +the first element/member instead. + +.. code-block:: none + + idf_build_component(component_dir) + +Present a directory *component_dir* that contains a component to the build system. Relative paths are converted to absolute paths with respect to current directory. +All calls to this command must be performed before `idf_build_process`. + +This command does not guarantee that the component will be processed during build (see the `COMPONENTS` argument description for `idf_build_process`) + +.. code-block:: none + + idf_build_process(target + [PROJECT_DIR project_dir] + [PROJECT_VER project_ver] + [PROJECT_NAME project_name] + [SDKCONFIG sdkconfig] + [SDKCONFIG_DEFAULTS sdkconfig_defaults] + [BUILD_DIR build_dir] + [COMPONENTS component1 component2 ...]) + +Performs the bulk of the behind-the-scenes magic for including ESP-IDF components such as component configuration, libraries creation, +dependency expansion and resolution. Among these functions, perhaps the most important +from a user's perspective is the libraries creation by calling each component's ``idf_component_register``. This command creates the libraries for each component, which are accessible using aliases in the form +idf::*component_name*. These aliases can be used to link the components to the user's own targets, either libraries +or executables. + +The call requires the target chip to be specified with *target* argument. Optional arguments for the call include: + +- PROJECT_DIR - directory of the project; defaults to CMAKE_SOURCE_DIR +- PROJECT_NAME - name of the project; defaults to CMAKE_PROJECT_NAME +- PROJECT_VER - version/revision of the project; defaults to "0.0.0" +- SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set +- SDKCONFIG_DEFAULTS - defaults file to use for the build; defaults to empty +- BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, components; defaults to CMAKE_BINARY_DIR +- COMPONENTS - select components to process among the components known by the build system (added via `idf_build_component`). This argument is used to trim the build. + Other components are automatically added if they are required in the dependency chain, i.e. + the public and private requirements of the components in this list are automatically added, and in turn the public and private requirements of those requirements, + so on and so forth. If not specified, all components known to the build system are processed. + +.. code-block:: none + + idf_build_executable(executable) + +Specify the executable *executable* for ESP-IDF build. This attaches additional targets such as dependencies related to +flashing, generating additional binary files, etc. Should be called after ``idf_build_process``. + +.. code-block:: none + + idf_build_get_config(var config [GENERATOR_EXPRESSION]) + +Get the value of the specified config. Much like build properties, specifying +*GENERATOR_EXPRESSION* will retrieve the generator expression string for that config, instead of the actual value, which +can be used with CMake commands that support generator expressions. Actual config values are only known after call to `idf_build_process`, however. + +.. _cmake-build-properties: + +idf-build-properties +-------------------- + +These are properties that describe the build. Values of build properties can be retrieved by using the build command ``idf_build_get_property``. +For example, to get the Python interpreter used for the build: + +.. code-block: cmake + + idf_build_get_property(python PYTHON) + message(STATUS "The Python intepreter is: ${python}") + + - BUILD_DIR - build directory; set from ``idf_build_process`` BUILD_DIR argument + - BUILD_COMPONENTS - list of components (more specifically, component aliases) included in the build; set by ``idf_build_process`` + - C_COMPILE_OPTIONS - compile options applied to all components' C source files + - COMPILE_OPTIONS - compile options applied to all components' source files, regardless of it being C or C++ + - COMPILE_DEFINITIONS - compile definitions applied to all component source files + - CXX_COMPILE_OPTIONS - compile options applied to all components' C++ source files + - EXECUTABLE - project executable; set by call to ``idf_build_executable`` + - EXECUTABLE_NAME - name of project executable without extension; set by call to ``idf_build_executable`` + - IDF_PATH - ESP-IDF path; set from IDF_PATH environment variable, if not, inferred from the location of ``idf.cmake`` + - IDF_TARGET - target chip for the build; set from the required target argument for ``idf_build_process`` + - IDF_VER - ESP-IDF version; set from either a version file or the Git revision of the IDF_PATH repository + - INCLUDE_DIRECTORIES - include directories for all component source files + - KCONFIGS - list of Kconfig files found in components in build; set by ``idf_build_process`` + - KCONFIG_PROJBUILDS - list of Kconfig.projbuild diles found in components in build; set by ``idf_build_process`` + - PROJECT_NAME - name of the project; set from ``idf_build_process`` PROJECT_NAME argument + - PROJECT_DIR - directory of the project; set from ``idf_build_process`` PROJECT_DIR argument + - PROJECT_VER - version of the project; set from ``idf_build_process`` PROJECT_VER argument + - PYTHON - Python interpreter used for the build; set from PYTHON environment variable if available, if not "python" is used + - SDKCONFIG - full path to output config file; set from ``idf_build_process`` SDKCONFIG argument + - SDKCONFIG_DEFAULTS - full path to config defaults file; set from ``idf_build_process`` SDKCONFIG_DEFAULTS argument + - SDKCONFIG_HEADER - full path to C/C++ header file containing component configuration; set by ``idf_build_process`` + - SDKCONFIG_CMAKE - full path to CMake file containing component configuration; set by ``idf_build_process`` + - SDKCONFIG_JSON - full path to JSON file containing component configuration; set by ``idf_build_process`` + - SDKCONFIG_JSON_MENUS - full path to JSON file containing config menus; set by ``idf_build_process`` + +idf-component-commands +---------------------- + +.. code-block:: none + + idf_component_get_property(var component property [GENERATOR_EXPRESSION]) + +Retrieve a specified *component*'s :ref:`component property`, *property* and store it in *var* accessible from the current scope. Specifying +*GENERATOR_EXPRESSION* will retrieve the generator expression string for that property, instead of the actual value, which +can be used with CMake commands that support generator expressions. + +.. code-block:: none + + idf_component_set_property(property val [APPEND]) + +Set a specified *component*'s :ref:`component property`, *property* with value *val*. Specifying *APPEND* will append the specified value to the current +value of the property. If the property does not previously exist or it is currently empty, the specified value becomes +the first element/member instead. + +.. _cmake-component-register: + +.. code-block:: none + + idf_component_register([[SRCS src1 src2 ...] | [[SRC_DIRS dir1 dir2 ...] [EXCLUDE_SRCS src1 src2 ...]] + [INCLUDE_DIRS dir1 dir2 ...] + [PRIV_INCLUDE_DIRS dir1 dir2 ...] + [REQUIRES component1 component2 ...] + [PRIV_REQUIRES component1 component2 ...] + [LDFRAGMENTS ldfragment1 ldfragment2 ...] + [REQUIRED_IDF_TARGETS target1 target2 ...] + [EMBED_FILES file1 file2 ...] + [EMBED_TXTFILES file1 file2 ...]) + +Register a component to the build system. Much like the ``project()`` CMake command, this should be called from the component's +CMakeLists.txt directly (not through a function or macro) and is recommended to be called before any other command. Here are some +guidelines on what commands can **not** be called before ``idf_component_register``: + + - commands that are not valid in CMake script mode + - custom commands defined in project_include.cmake + - build system API commands except ``idf_build_get_property``; although consider whether the property may not have been set yet + +Commands that set and operate on variables are generally okay to call before ``idf_component_register``. + +The arguments for ``idf_component_register`` include: + + - SRCS - component source files used for creating a static library for the component; if not specified, component is a treated as a + config-only component and an interface library is created instead. + - SRC_DIRS, EXCLUDE_SRCS - used to glob source files (.c, .cpp, .S) by specifying directories, instead of specifying source files manually via SRCS. + Note that this is subject to the :ref:`limitations of globbing in CMake`. Source files specified in EXCLUDE_SRCS are removed from the globbed files. + - INCLUDE_DIRS - paths, relative to the component directory, which will be added to the include search path for all other components which require the current component + - PRIV_INCLUDE_DIRS - directory paths, must be relative to the component directory, which will be added to the include search path for this component's source files only + - REQUIRES - public component requirements for the component + - PRIV_REQUIRES - private component requirements for the component; ignored on config-only components + - LDFRAGMENTS - component linker fragment files + - REQUIRED_IDF_TARGETS - specify the only target the component supports + +The following are used for :ref:`embedding data into the component`, and is considered as source files +when determining if a component is config-only. This means that even if the component does not specify source files, a static library is still +created internally for the component if it specifies either: + + - EMBED_FILES - binary files to be embedded in the component + - EMBED_TXTFILES - text files to be embedded in the component + +.. _cmake-component-properties: + +idf-component-properties +------------------------ + +These are properties that describe a component. Values of component properties can be retrieved by using the build command ``idf_component_get_property``. +For example, to get the directory of the ``freertos`` component: + +.. code-block: cmake + + idf_component_get_property(dir freertos COMPONENT_DIR) + message(STATUS "The 'freertos' component directory is: ${dir}") + +- COMPONENT_ALIAS - alias for COMPONENT_LIB used for linking the component to external targets; set by ``idf_build_component`` and alias library itself + is created by ``idf_component_register`` +- COMPONENT_DIR - component directory; set by ``idf_build_component`` +- COMPONENT_LIB - name for created component static/interface library; set by ``idf_build_component`` and library itself + is created by ``idf_component_register`` +- COMPONENT_NAME - name of the component; set by ``idf_build_component`` based on the component directory name +- COMPONENT_TYPE - type of the component, whether LIBRARY or CONFIG_ONLY. A component is of type LIBRARY if it specifies + source files or embeds a file +- EMBED_FILES - list of files to embed in component; set from ``idf_component_register`` EMBED_FILES argument +- EMBED_TXTFILES - list of text files to embed in component; set from ``idf_component_register`` EMBED_TXTFILES argument +- INCLUDE_DIRS - list of component include directories; set from ``idf_component_register`` INCLUDE_DIRS argument +- KCONFIG - component Kconfig file; set by ``idf_build_component`` +- KCONFIG_PROJBUILD - component Kconfig.projbuild; set by ``idf_build_component`` +- LDFRAGMENTS - list of component linker fragment files; set from ``idf_component_register`` LDFRAGMENTS argument +- PRIV_INCLUDE_DIRS - list of component private include directories; set from ``idf_component_register`` PRIV_INCLUDE_DIRS on components of type LIBRARY +- PRIV_REQUIRES - list of private component dependentices; set from ``idf_component_register`` PRIV_REQUIRES argument +- REQUIRED_IDF_TARGETS - list of targets the component supports; set from ``idf_component_register`` EMBED_TXTFILES argument +- REQUIRES - list of public component dependencies; set from ``idf_component_register`` REQUIRES argument +- SRCS - list of component source files; set from SRCS or SRC_DIRS/EXCLUDE_SRCS argument of ``idf_component_register`` + +.. _cmake-file-globbing: + +File Globbing & Incremental Builds +================================== + +.. highlight:: cmake + +The preferred way to include source files in an ESP-IDF component is to list them manually via SRCS argument to ``idf_component_register``:: + + idf_component_register(SRCS library/a.c library/b.c platform/platform.c + ...) + +This preference reflects the `CMake best practice `_ of manually listing source files. This could, however, be inconvenient when there are lots of source files to add to the build. The ESP-IDF build system provides an alternative way for specifying source files using ``SRC_DIRS``:: + + idf_component_register(SRC_DIRS library platform + ...) + +This uses globbing behind the scenes to find source files in the specified directories. Be aware, however, that if a new source file is added and this method is used, then CMake won't know to automatically re-run and this file won't be added to the build. + +The trade-off is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git... + +For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun. + +For project components (not part of ESP-IDF), there are a few different options: + +- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes. +- If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to automatically trigger re-runs of CMake when the Git revision changes. +- If not using Git, remember to manually run ``idf.py reconfigure`` whenever a source file may change. +- To avoid this problem entirely, use ``COMPONENT_SRCS`` to list all source files in project components. + +The best option will depend on your particular project and its users. + +Build System Metadata +===================== + +For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command). + +- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it. +- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc. +- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_. +- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc. +- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values. +- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs. + +JSON Configuration Server +------------------------- + +.. highlight :: json + +A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout. + +You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator. + +The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``:: + + {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } } + +Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.) + +The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline:: + + {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } } + +The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes:: + + {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}} + +Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value. + +If the range of a config item changes, due to conditional range depending on another value, then this is also sent:: + + {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } } + +If invalid data is passed, an "error" field is present on the object:: + + {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]} + +By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent:: + + {"version": 1, "save": null } + +To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent:: + + {"version": 1, "load": null } + +The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname. + +The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started. + +Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command. + +.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited. + +.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run. + +.. _gnu-make-to-cmake: + +Migrating from ESP-IDF GNU Make System +====================================== + +Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax. + +Automatic Conversion Tool +------------------------- + +.. highlight:: bash + +An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this:: + + $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir + +The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH. + +The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files. + +It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables. + +The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand. + +No Longer Available in CMake +---------------------------- + +Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system: + +- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead. +- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component. +- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here `_. +- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually. +- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead. +- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``. +- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repository. +- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute). +- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``. +- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead. +- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality `. +- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details. +- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_. +- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_. + + +No Default Values +----------------- + +The following variables no longer have default values: + +- ``COMPONENT_SRCDIRS`` +- ``COMPONENT_ADD_INCLUDEDIRS`` + +No Longer Necessary +------------------- + +It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCS`` is ignored if ``COMPONENT_SRCDIRS`` is set). + +Flashing from make +------------------ + +``make flash`` and similar targets still work to build and flash. However, project ``sdkconfig`` no longer specifies serial port and baud rate. Environment variables can be used to override these. See :ref:`flash-with-ninja-or-make` for more details. + +.. _esp-idf-template: https://github.com/espressif/esp-idf-template +.. _cmake: https://cmake.org +.. _ninja: https://ninja-build.org +.. _esptool.py: https://github.com/espressif/esptool/#readme +.. _CMake v3.5 documentation: https://cmake.org/cmake/help/v3.5/index.html +.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options +.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/add_library.html +.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html +.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html +.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html +.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html +.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html +.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F +.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html +.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html +.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages +.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html +.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html +.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries +.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html +.. _quirc: https://github.com/dlbeer/quirc +.. _pyenv: https://github.com/pyenv/pyenv#README +.. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/en/api-guides/ulp-cmake.rst b/docs/en/api-guides/ulp-legacy.rst similarity index 80% rename from docs/en/api-guides/ulp-cmake.rst rename to docs/en/api-guides/ulp-legacy.rst index 0391ab73d..8eee8cffd 100644 --- a/docs/en/api-guides/ulp-cmake.rst +++ b/docs/en/api-guides/ulp-legacy.rst @@ -1,7 +1,5 @@ -ULP coprocessor programming (CMake) -=================================== - -:link_to_translation:`zh_CN:[中文]` +ULP coprocessor programming +=========================== .. toctree:: :maxdepth: 1 @@ -27,35 +25,39 @@ Compiling ULP code To compile ULP code as part of a component, the following steps must be taken: -1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. +1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. -.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. +.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. -2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: +2. Modify the component makefile, adding the following:: - ... - register_component() + ULP_APP_NAME ?= ulp_$(COMPONENT_NAME) + ULP_S_SOURCES = $(COMPONENT_PATH)/ulp/ulp_source_file.S + ULP_EXP_DEP_OBJECTS := main.o + include $(IDF_PATH)/components/ulp/component_ulp_common.mk + + Here is each line explained: - set(ulp_app_name ulp_${COMPONENT_NAME}) - set(ulp_s_sources ulp/ulp_assembly_source_file.S) - set(ulp_exp_dep_srcs "ulp_c_source_file.c") + ULP_APP_NAME + Name of the generated ULP application, without an extension. This name is used for build products of the ULP application: ELF file, map file, binary file, generated header file, and generated linker export file. - ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs}) + ULP_S_SOURCES + List of assembly files to be passed to the ULP assembler. These must be absolute paths, i.e. start with ``$(COMPONENT_PATH)``. Consider using ``$(addprefix)`` function if more than one file needs to be listed. Paths are relative to component build directory, so prefixing them is not necessary. - The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used other generated artifacts - such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. - Finally, the third argument specifies the list of component source files which include the header file to be generated. - This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. - See section below explaining the concept of generated header files for ULP applications. + ULP_EXP_DEP_OBJECTS + List of object files names within the component which include the generated header file. This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. See section below explaining the concept of generated header files for ULP applications. -3. Build the application as usual (e.g. `idf.py app`) + include $(IDF_PATH)/components/ulp/component_ulp_common.mk + Includes common definitions of ULP build steps. Defines build targets for ULP object files, ELF file, binary file, etc. +3. Build the application as usual (e.g. ``idf.py build`` or ``idf.py app``) + Inside, the build system will take the following steps to build ULP program: - 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d). + 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.pS) in the component build directory. This step also generates dependency files (foo.ulp.d). 2. **Run preprocessed assembly sources through assembler.** This produces objects (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of build process. - + 3. **Run linker script template through C preprocessor.** The template is located in components/ulp/ld directory. 4. **Link object files into an output ELF file** (ulp_app_name.elf). Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes. @@ -71,7 +73,7 @@ To compile ULP code as part of a component, the following steps must be taken: Accessing ULP program variables ------------------------------- -Global symbols defined in the ULP program may be used inside the main program. +Global symbols defined in the ULP program may be used inside the main program. For example, ULP program may define a variable ``measurement_count`` which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep:: @@ -82,10 +84,10 @@ For example, ULP program may define a variable ``measurement_count`` which will move r3, measurement_count ld r3, r3, 0 -Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. +Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``$(ULP_APP_NAME).h`` and ``$(ULP_APP_NAME).ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. The header file contains declaration of the symbol:: - + extern uint32_t ulp_measurement_count; Note that all symbols (variables, arrays, functions) are declared as ``uint32_t``. For functions and arrays, take address of the symbol and cast to the appropriate type. @@ -136,7 +138,7 @@ Once the program is loaded into RTC memory, application can start it, passing th .. doxygenfunction:: ulp_run -Declaration of the entry point symbol comes from the above mentioned generated header file, ``${ULP_APP_NAME}.h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: +Declaration of the entry point symbol comes from the above mentioned generated header file, ``$(ULP_APP_NAME).h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: .global entry diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index 8eee8cffd..0391ab73d 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -1,5 +1,7 @@ -ULP coprocessor programming -=========================== +ULP coprocessor programming (CMake) +=================================== + +:link_to_translation:`zh_CN:[中文]` .. toctree:: :maxdepth: 1 @@ -25,39 +27,35 @@ Compiling ULP code To compile ULP code as part of a component, the following steps must be taken: -1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. +1. ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside component directory, for instance `ulp/`. -.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. +.. note: This directory should not be added to the ``COMPONENT_SRCDIRS`` environment variable. The logic behind this is that the ESP-IDF build system will compile files found in ``COMPONENT_SRCDIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``COMPONENT_SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. -2. Modify the component makefile, adding the following:: +2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: - ULP_APP_NAME ?= ulp_$(COMPONENT_NAME) - ULP_S_SOURCES = $(COMPONENT_PATH)/ulp/ulp_source_file.S - ULP_EXP_DEP_OBJECTS := main.o - include $(IDF_PATH)/components/ulp/component_ulp_common.mk - - Here is each line explained: + ... + register_component() - ULP_APP_NAME - Name of the generated ULP application, without an extension. This name is used for build products of the ULP application: ELF file, map file, binary file, generated header file, and generated linker export file. + set(ulp_app_name ulp_${COMPONENT_NAME}) + set(ulp_s_sources ulp/ulp_assembly_source_file.S) + set(ulp_exp_dep_srcs "ulp_c_source_file.c") - ULP_S_SOURCES - List of assembly files to be passed to the ULP assembler. These must be absolute paths, i.e. start with ``$(COMPONENT_PATH)``. Consider using ``$(addprefix)`` function if more than one file needs to be listed. Paths are relative to component build directory, so prefixing them is not necessary. + ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs}) - ULP_EXP_DEP_OBJECTS - List of object files names within the component which include the generated header file. This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. See section below explaining the concept of generated header files for ULP applications. + The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used other generated artifacts + such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. + Finally, the third argument specifies the list of component source files which include the header file to be generated. + This list is needed to build the dependencies correctly and ensure that the generated header file is created before any of these files are compiled. + See section below explaining the concept of generated header files for ULP applications. - include $(IDF_PATH)/components/ulp/component_ulp_common.mk - Includes common definitions of ULP build steps. Defines build targets for ULP object files, ELF file, binary file, etc. +3. Build the application as usual (e.g. `idf.py app`) -3. Build the application as usual (e.g. ``idf.py build`` or ``idf.py app``) - Inside, the build system will take the following steps to build ULP program: - 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.pS) in the component build directory. This step also generates dependency files (foo.ulp.d). + 1. **Run each assembly file (foo.S) through C preprocessor.** This step generates the preprocessed assembly files (foo.ulp.S) in the component build directory. This step also generates dependency files (foo.ulp.d). 2. **Run preprocessed assembly sources through assembler.** This produces objects (foo.ulp.o) and listing (foo.ulp.lst) files. Listing files are generated for debugging purposes and are not used at later stages of build process. - + 3. **Run linker script template through C preprocessor.** The template is located in components/ulp/ld directory. 4. **Link object files into an output ELF file** (ulp_app_name.elf). Map file (ulp_app_name.map) generated at this stage may be useful for debugging purposes. @@ -73,7 +71,7 @@ To compile ULP code as part of a component, the following steps must be taken: Accessing ULP program variables ------------------------------- -Global symbols defined in the ULP program may be used inside the main program. +Global symbols defined in the ULP program may be used inside the main program. For example, ULP program may define a variable ``measurement_count`` which will define the number of ADC measurements the program needs to make before waking up the chip from deep sleep:: @@ -84,10 +82,10 @@ For example, ULP program may define a variable ``measurement_count`` which will move r3, measurement_count ld r3, r3, 0 -Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``$(ULP_APP_NAME).h`` and ``$(ULP_APP_NAME).ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. +Main program needs to initialize this variable before ULP program is started. Build system makes this possible by generating a ``${ULP_APP_NAME}.h`` and ``${ULP_APP_NAME}.ld`` files which define global symbols present in the ULP program. This files include each global symbol defined in the ULP program, prefixed with ``ulp_``. The header file contains declaration of the symbol:: - + extern uint32_t ulp_measurement_count; Note that all symbols (variables, arrays, functions) are declared as ``uint32_t``. For functions and arrays, take address of the symbol and cast to the appropriate type. @@ -138,7 +136,7 @@ Once the program is loaded into RTC memory, application can start it, passing th .. doxygenfunction:: ulp_run -Declaration of the entry point symbol comes from the above mentioned generated header file, ``$(ULP_APP_NAME).h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: +Declaration of the entry point symbol comes from the above mentioned generated header file, ``${ULP_APP_NAME}.h``. In assembly source of the ULP application, this symbol must be marked as ``.global``:: .global entry diff --git a/docs/en/api-guides/unit-tests-cmake.rst b/docs/en/api-guides/unit-tests-legacy.rst similarity index 77% rename from docs/en/api-guides/unit-tests-cmake.rst rename to docs/en/api-guides/unit-tests-legacy.rst index e08b912f8..43346e4b4 100644 --- a/docs/en/api-guides/unit-tests-cmake.rst +++ b/docs/en/api-guides/unit-tests-legacy.rst @@ -1,9 +1,7 @@ -Unit Testing in ESP32 (CMake) -============================= +Unit Testing in ESP32 +===================== :link_to_translation:`zh_CN:[中文]` -.. include:: ../cmake-warning.rst - ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively. Add normal test cases @@ -28,18 +26,9 @@ Identifiers are used to group related test, or tests with specific properties. There is no need to add a main function with ``UNITY_BEGIN()`` and ``​UNITY_END()`` in each test case. ``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``​UNITY_END()``. -The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt `, since they are themselves, -components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components -:ref:`should list their sources manually `; for component tests however, this requirement is relaxed and the -use of ``COMPONENT_SRCDIRS`` is advised. +Each `test` subdirectory needs to include component.mk file with at least the following line of code:: -Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as follows: - -.. code:: cmake - - idf_component_register(SRC_DIRS "." - INCLUDE_DIRS "." - REQUIRES unity) + COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive See http://www.throwtheswitch.org/unity for more information about writing tests in Unity. @@ -87,13 +76,27 @@ As the secnario in the above example, slave should get GPIO level after master s DUT1 (master) console:: Waiting for signal: [output high level]! - Please press "Enter" key to once any board send this signal. + Please press "Enter" key once any board send this signal. DUT2 (slave) console:: Send signal: [output high level]! -Once the signal is set from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. +Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. + +Signals can also be used to pass parameters between multiple devices. For example, DUT1 want to know the MAC address of DUT2, so it can connect to DUT2. +In this case, ``unity_wait_for_signal_param`` and ``unity_send_signal_param`` can be used: + +DUT1 console:: + + Waiting for signal: [dut2 mac address]! + Please input parameter value from any board send this signal and press "Enter" key. + +DUT2 console:: + + Send signal: [dut2 mac address][10:20:30:40:50:60]! + +Once the signal is sent from DUT2, you need to input ``10:20:30:40:50:60`` on DUT1 and press "Enter". Then DUT1 will get the MAC address string of DUT2 and unblocks from ``unity_wait_for_signal_param``, start to connect to DUT2. Add multiple stages test cases @@ -128,15 +131,15 @@ Make sure that IDF_PATH environment variable is set to point to the path of esp- Change into tools/unit-test-app directory to configure and build it: -* `idf.py menuconfig` - configure unit test app. +* `make menuconfig` - configure unit test app. -* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory. -* `idf.py -T xxx build` - build unit test app with tests for specific components. -* `idf.py -T all -E xxx build` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp -E mbedtls build` - build all unit tests exludes ulp and mbedtls components). +* `make TESTS_ALL=1` - build unit test app with tests for each component having tests in the ``test`` subdirectory. +* `make TEST_COMPONENTS='xxx'` - build unit test app with tests for specific components. +* `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'` - build all unit tests exludes ulp and mbedtls components). -When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output. +When the build finishes, it will print instructions for flashing the chip. You can simply run ``make flash`` to flash all build output. -You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. +You can also run ``make flash TESTS_ALL=1`` or ``make TEST_COMPONENTS='xxx'`` to build and flash. Everything needed will be rebuilt automatically before flashing. Use menuconfig to set the serial port for flashing. @@ -177,13 +180,13 @@ Normal case will print the case name and description. Master slave cases will al Test cases can be run by inputting one of the following: -- Test case name in quotation marks to run a single test case +- Test case name in quotation marks (for example, ``"esp_ota_begin() verifies arguments"``) to run a single test case. -- Test case index to run a single test case +- Test case index (for example, ``1``) to run a single test case. -- Module name in square brackets to run all test cases for a specific module +- Module name in square brackets (for example, ``[cxx]``) to run all test cases for a specific module. -- An asterisk to run all test cases +- An asterisk (``*``) to run all test cases ``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages test case. These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros. diff --git a/docs/en/api-guides/unit-tests.rst b/docs/en/api-guides/unit-tests.rst index 43346e4b4..e08b912f8 100644 --- a/docs/en/api-guides/unit-tests.rst +++ b/docs/en/api-guides/unit-tests.rst @@ -1,7 +1,9 @@ -Unit Testing in ESP32 -===================== +Unit Testing in ESP32 (CMake) +============================= :link_to_translation:`zh_CN:[中文]` +.. include:: ../cmake-warning.rst + ESP-IDF comes with a unit test app based on Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in ``test`` subdirectory of each component respectively. Add normal test cases @@ -26,9 +28,18 @@ Identifiers are used to group related test, or tests with specific properties. There is no need to add a main function with ``UNITY_BEGIN()`` and ``​UNITY_END()`` in each test case. ``unity_platform.c`` will run ``UNITY_BEGIN()``, run the tests cases, and then call ``​UNITY_END()``. -Each `test` subdirectory needs to include component.mk file with at least the following line of code:: +The ``test`` subdirectory should contain a :ref:`component CMakeLists.txt `, since they are themselves, +components. ESP-IDF uses the test framework ``unity`` and should be specified as a requirement for the component. Normally, components +:ref:`should list their sources manually `; for component tests however, this requirement is relaxed and the +use of ``COMPONENT_SRCDIRS`` is advised. - COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive +Overall, the minimal ``test`` subdirectory CMakeLists.txt file may look like as follows: + +.. code:: cmake + + idf_component_register(SRC_DIRS "." + INCLUDE_DIRS "." + REQUIRES unity) See http://www.throwtheswitch.org/unity for more information about writing tests in Unity. @@ -76,27 +87,13 @@ As the secnario in the above example, slave should get GPIO level after master s DUT1 (master) console:: Waiting for signal: [output high level]! - Please press "Enter" key once any board send this signal. + Please press "Enter" key to once any board send this signal. DUT2 (slave) console:: Send signal: [output high level]! -Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. - -Signals can also be used to pass parameters between multiple devices. For example, DUT1 want to know the MAC address of DUT2, so it can connect to DUT2. -In this case, ``unity_wait_for_signal_param`` and ``unity_send_signal_param`` can be used: - -DUT1 console:: - - Waiting for signal: [dut2 mac address]! - Please input parameter value from any board send this signal and press "Enter" key. - -DUT2 console:: - - Send signal: [dut2 mac address][10:20:30:40:50:60]! - -Once the signal is sent from DUT2, you need to input ``10:20:30:40:50:60`` on DUT1 and press "Enter". Then DUT1 will get the MAC address string of DUT2 and unblocks from ``unity_wait_for_signal_param``, start to connect to DUT2. +Once the signal is set from DUT2, you need to press "Enter" on DUT1, then DUT1 unblocks from ``unity_wait_for_signal`` and starts to change GPIO level. Add multiple stages test cases @@ -131,15 +128,15 @@ Make sure that IDF_PATH environment variable is set to point to the path of esp- Change into tools/unit-test-app directory to configure and build it: -* `make menuconfig` - configure unit test app. +* `idf.py menuconfig` - configure unit test app. -* `make TESTS_ALL=1` - build unit test app with tests for each component having tests in the ``test`` subdirectory. -* `make TEST_COMPONENTS='xxx'` - build unit test app with tests for specific components. -* `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='xxx'` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `make TESTS_ALL=1 TEST_EXCLUDE_COMPONENTS='ulp mbedtls'` - build all unit tests exludes ulp and mbedtls components). +* `idf.py -T all build` - build unit test app with tests for each component having tests in the ``test`` subdirectory. +* `idf.py -T xxx build` - build unit test app with tests for specific components. +* `idf.py -T all -E xxx build` - build unit test app with all unit tests, except for unit tests of some components. (For instance: `idf.py -T all -E ulp -E mbedtls build` - build all unit tests exludes ulp and mbedtls components). -When the build finishes, it will print instructions for flashing the chip. You can simply run ``make flash`` to flash all build output. +When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output. -You can also run ``make flash TESTS_ALL=1`` or ``make TEST_COMPONENTS='xxx'`` to build and flash. Everything needed will be rebuilt automatically before flashing. +You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. Use menuconfig to set the serial port for flashing. @@ -180,13 +177,13 @@ Normal case will print the case name and description. Master slave cases will al Test cases can be run by inputting one of the following: -- Test case name in quotation marks (for example, ``"esp_ota_begin() verifies arguments"``) to run a single test case. +- Test case name in quotation marks to run a single test case -- Test case index (for example, ``1``) to run a single test case. +- Test case index to run a single test case -- Module name in square brackets (for example, ``[cxx]``) to run all test cases for a specific module. +- Module name in square brackets to run all test cases for a specific module -- An asterisk (``*``) to run all test cases +- An asterisk to run all test cases ``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages test case. These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros. diff --git a/docs/en/get-started-cmake/add-idf_path-to-profile.rst b/docs/en/get-started-cmake/add-idf_path-to-profile.rst deleted file mode 100644 index cdaf9a5b8..000000000 --- a/docs/en/get-started-cmake/add-idf_path-to-profile.rst +++ /dev/null @@ -1,3 +0,0 @@ -:orphan: - -.. Remove this file when the Chinese translation of CMake getting started guide is updated diff --git a/docs/en/get-started-cmake/eclipse-setup.rst b/docs/en/get-started-cmake/eclipse-setup.rst deleted file mode 100644 index 2e2b105bc..000000000 --- a/docs/en/get-started-cmake/eclipse-setup.rst +++ /dev/null @@ -1,12 +0,0 @@ -**************************************** -Build and Flash with Eclipse IDE (CMake) -**************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon. - -.. _eclipse.org: https://www.eclipse.org/ - diff --git a/docs/en/get-started-cmake/index.rst b/docs/en/get-started-cmake/index.rst deleted file mode 100644 index e5f810c09..000000000 --- a/docs/en/get-started-cmake/index.rst +++ /dev/null @@ -1,491 +0,0 @@ -******************* -Get Started (CMake) -******************* - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -.. include:: ../cmake-pending-features.rst - -This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif. - -After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board. - -.. include:: /_build/inc/version-note.inc - -Introduction -============ - -ESP32 is a system on a chip that integrates the following features: - -* Wi-Fi (2.4 GHz band) -* Bluetooth 4.2 -* Dual high performance cores -* Ultra Low Power co-processor -* Several peripherals - -Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. - -Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. - -What You Need -============= - -Hardware: - -* An **ESP32** board -* **USB cable** - USB A / micro USB B -* **Computer** running Windows, Linux, or macOS - -Software: - -* **Toolchain** to compile code for ESP32 -* **Build tools** - CMake and Ninja to build a full **Application** for ESP32 -* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** -* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ - - -.. figure:: ../../_static/what-you-need-cmake.png - :align: center - :alt: Development of applications for ESP32 - :figclass: align-center - - Development of applications for ESP32 - - -Development Board Overviews -=========================== - -If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware. - -.. toctree:: - :maxdepth: 1 - - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> - - -.. _get-started-step-by-step-cmake: - -Installation Step by Step -========================= - -This is a detailed roadmap to walk you through the installation process. - -Setting up Development Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* :ref:`get-started-get-prerequisites-cmake` for :doc:`Windows `, :doc:`Linux ` or :doc:`macOS ` -* :ref:`get-started-get-esp-idf-cmake` -* :ref:`get-started-set-up-tools-cmake` -* :ref:`get-started-set-up-env-cmake` - -Creating Your First Project -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* :ref:`get-started-start-project-cmake` -* :ref:`get-started-connect-cmake` -* :ref:`get-started-configure-cmake` -* :ref:`get-started-build-cmake` -* :ref:`get-started-flash-cmake` -* :ref:`get-started-build-monitor-cmake` - - -.. _get-started-get-prerequisites-cmake: - -Step 1. Install prerequisites -============================= - -Some tools need to be installed on the computer before proceeding to the next steps. Follow the links below for the instructions for your OS: - -.. toctree:: - :hidden: - - Windows - Linux - macOS - -* :doc:`windows-setup` -* :doc:`linux-setup` -* :doc:`macos-setup` - -.. _get-started-get-esp-idf-cmake: - -Step 2. Get ESP-IDF -=================== - -To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository `_. - -Get ESP-IDF in accordance with your operating system. - -To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``. - -.. note:: - - This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths. - -Linux and macOS -~~~~~~~~~~~~~~~ - -Open Terminal, and run the following commands: - -.. include:: /_build/inc/git-clone-bash.inc - -ESP-IDF will be downloaded into ``~/esp/esp-idf``. - -Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. - -Windows -~~~~~~~ - -In addition to installing the tools, :ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF. - -Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. - -If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions `. - -.. _get-started-set-up-tools-cmake: - -Step 3. Set up the tools -======================== - -Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc. - -Windows -~~~~~~~ - -:ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools. - -If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps: - -.. code-block:: batch - - cd %userprofile%\esp\esp-idf - install.bat - -Linux and macOS -~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp/esp-idf - ./install.sh - -Customizing the tools installation path -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user has sufficient permissions to read and write this path. - -If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the ``install.bat``/``install.sh`` and ``export.bat``/``export.sh`` scripts are executed. - -.. _get-started-set-up-env-cmake: - -Step 4. Set up the environment variables -======================================== - -The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-IDF provides another script which does that. - -Windows -~~~~~~~ - -:ref:`get-started-cmake-windows-tools-installer` for Windows creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step. - -Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run: - -.. code-block:: batch - - %userprofile%\esp\esp-idf\export.bat - -Linux and macOS -~~~~~~~~~~~~~~~ - -In the terminal where you are going to use ESP-IDF, run: - -.. code-block:: bash - - . $HOME/esp/esp-idf/export.sh - -Note the space between the leading dot and the path! - -You can also automate this step, making ESP-IDF tools available in every terminal, by adding this line to your ``.profile`` or ``.bash_profile`` script. - -.. _get-started-start-project-cmake: - -Step 5. Start a Project -======================= - -Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. - -Copy :example:`get-started/hello_world` to ``~/esp`` directory: - -Linux and macOS -~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp - cp -r $IDF_PATH/examples/get-started/hello_world . - -Windows -~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp - xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world - -There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. - -It is also possible to build examples in-place, without copying them first. - -.. important:: - - The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. - -.. _get-started-connect-cmake: - -Step 6. Connect Your Device -=========================== - -Now connect your ESP32 board to the computer and check under what serial port the board is visible. - -Serial ports have the following patterns in their names: - -- **Windows**: names like ``COM1`` -- **Linux**: starting with ``/dev/tty`` -- **macOS**: starting with ``/dev/cu.`` - -If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details. - -.. note:: - - Keep the port name handy as you will need it in the next steps. - - -.. _get-started-configure-cmake: - -Step 7. Configure -================= - -Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-cmake` and run the project configuration utility ``menuconfig``. - -Linux and macOS -~~~~~~~~~~~~~~~ - -.. code-block:: bash - - cd ~/esp/hello_world - idf.py menuconfig - -If your default version of Python is 3.x, you may need to run ``python2 $(which idf.py) menuconfig`` instead. - -Windows -~~~~~~~ - -.. code-block:: batch - - cd %userprofile%\esp\hello_world - idf.py menuconfig - -If the previous steps have been done correctly, the following menu appears: - -.. figure:: ../../_static/project-configuration.png - :align: center - :alt: Project configuration - Home window - :figclass: align-center - - Project configuration - Home window - -To navigate and use ``menuconfig``, press the following keys: - -* Arrow keys for navigation -* ``Enter`` to go into a submenu -* ``Esc`` to go up one level or exit -* ``?`` to see a help screen. Enter key exits the help screen -* ``Space``, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``" -* ``?`` while highlighting a configuration item to display help about that item -* ``/`` to find configuration items - -.. attention:: - - If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. - -.. _get-started-build-cmake: - -Step 8. Build the Project -========================= - -Build the project by running:: - - idf.py build - -This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. - -.. code-block:: none - - $ idf.py build - Running cmake in directory /path/to/hello_world/build - Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... - Warn about uninitialized values. - -- Found Git: /usr/bin/git (found version "2.17.0") - -- Building empty aws_iot component due to configuration - -- Component names: ... - -- Component paths: ... - - ... (more lines of build system output) - - [527/527] Generating hello-world.bin - esptool.py v2.3.1 - - Project build complete. To flash, run this command: - ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin - or run 'idf.py -p PORT flash' - -If there are no errors, the build will finish by generating the firmware binary .bin file. - - -.. _get-started-flash-cmake: - -Step 9. Flash onto the Device -============================= - -Flash the binaries that you just built onto your ESP32 board by running:: - - idf.py -p PORT [-b BAUD] flash - -Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect-cmake`. - -You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``. - -For more information on idf.py arguments, see :ref:`idf.py`. - -.. note:: - - The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary. - -.. code-block:: none - - Running esptool.py in directory [...]/esp/hello_world - Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"... - esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin - esptool.py v2.3.1 - Connecting.... - Detecting chip type... ESP32 - Chip is ESP32D0WDQ6 (revision 1) - Features: WiFi, BT, Dual Core - Uploading stub... - Running stub... - Stub running... - Changing baud rate to 460800 - Changed. - Configuring flash size... - Auto-detected Flash size: 4MB - Flash params set to 0x0220 - Compressed 22992 bytes to 13019... - Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)... - Hash of data verified. - Compressed 3072 bytes to 82... - Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)... - Hash of data verified. - Compressed 136672 bytes to 67544... - Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... - Hash of data verified. - - Leaving... - Hard resetting via RTS pin... - -If there are no issues by the end of the flash process, the module will be reset and the “hello_world” application will be running. - -.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide `. - - -.. _get-started-build-monitor-cmake: - -Step 10. Monitor -================ - -To check if "hello_world" is indeed running, type ``idf.py -p PORT monitor`` (Do not forget to replace PORT with your serial port name). - -This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application:: - - $ idf.py -p /dev/ttyUSB0 monitor - Running idf_monitor in directory [...]/esp/hello_world/build - Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"... - --- idf_monitor on /dev/ttyUSB0 115200 --- - --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- - ets Jun 8 2016 00:22:57 - - rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) - ets Jun 8 2016 00:22:57 - ... - -After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application. - -.. code-block:: none - - ... - Hello world! - Restarting in 10 seconds... - I (211) cpu_start: Starting scheduler on APP CPU. - Restarting in 9 seconds... - Restarting in 8 seconds... - Restarting in 7 seconds... - -To exit IDF monitor use the shortcut ``Ctrl+]``. - -If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. - -.. code-block:: none - - e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA - ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp - -If you have such a problem, do the following: - -1. Exit the monitor. -2. Go back to :ref:`menuconfig `. -3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. -4. After that, :ref:`build and flash ` the application again. - -.. note:: - - You can combine building, flashing and monitoring into one step by running:: - - idf.py -p PORT flash monitor - -See also: - -- :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. -- :ref:`idf.py` for a full reference of ``idf.py`` commands and options. - -**That's all that you need to get started with ESP32!** - -Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications. - -Updating ESP-IDF -================ - -You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf-cmake`. - -Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `. - -After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools-cmake`. - -Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env-cmake`. - -Related Documents -================= - -.. toctree:: - :maxdepth: 1 - - establish-serial-connection - eclipse-setup - ../api-guides/tools/idf-monitor - toolchain-setup-scratch - -.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ -.. _Releases page: https://github.com/espressif/esp-idf/releases \ No newline at end of file diff --git a/docs/en/get-started-cmake/linux-setup-scratch.rst b/docs/en/get-started-cmake/linux-setup-scratch.rst deleted file mode 100644 index 51abaf6fd..000000000 --- a/docs/en/get-started-cmake/linux-setup-scratch.rst +++ /dev/null @@ -1,77 +0,0 @@ -****************************************** -Setup Linux Toolchain from Scratch (CMake) -****************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`. - -Install Prerequisites -===================== - -To compile with ESP-IDF you need to get the following packages: - -- CentOS 7:: - - sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - -- Ubuntu and Debian:: - - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache - -.. note:: - CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake". - -Compile the Toolchain from Source -================================= - -- Install dependencies: - - - CentOS 7:: - - sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make - - - Ubuntu pre-16.04:: - - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make - - - Ubuntu 16.04 or newer:: - - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - - Debian 9:: - - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - - Arch:: - - TODO - -Create the working directory and go into it:: - - mkdir -p ~/esp - cd ~/esp - -Download ``crosstool-NG`` and build it: - -.. include:: /_build/inc/scratch-build-code.inc - -Build the toolchain:: - - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf - -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable. - - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started-cmake/linux-setup.rst b/docs/en/get-started-cmake/linux-setup.rst deleted file mode 100644 index 429755b9b..000000000 --- a/docs/en/get-started-cmake/linux-setup.rst +++ /dev/null @@ -1,68 +0,0 @@ -*********************************************** -Installation of Prerequisites for Linux (CMake) -*********************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Install Prerequisites -===================== - -To compile with ESP-IDF you need to get the following packages: - -- CentOS 7:: - - sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - -- Ubuntu and Debian:: - - sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - -- Arch:: - - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache - -.. note:: - CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake". - -Additional Tips -=============== - -Permission issues /dev/ttyUSB0 ------------------------------- - -With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group`. - - -Arch Linux Users ----------------- - -To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. - -Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: - -- https://aur.archlinux.org/packages/ncurses5-compat-libs/ -- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ - -Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above. - -Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. - - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. - - -Related Documents -================= - -.. toctree:: - :maxdepth: 1 - - linux-setup-scratch - - -.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/en/get-started-cmake/macos-setup-scratch.rst b/docs/en/get-started-cmake/macos-setup-scratch.rst deleted file mode 100644 index 45fa4238c..000000000 --- a/docs/en/get-started-cmake/macos-setup-scratch.rst +++ /dev/null @@ -1,88 +0,0 @@ -*********************************************** -Setup Toolchain for Mac OS from Scratch (CMake) -*********************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Package Manager -=============== - -To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain`, you will need to install either the MacPorts_ or homebrew_ package manager. - -MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. - - .. _homebrew: https://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php - -See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. - -Install Prerequisites -===================== - -- install pip:: - - sudo easy_install pip - -- install pyserial:: - - pip install --user pyserial - -- install CMake & Ninja build: - - - If you have HomeBrew, you can run:: - - brew install cmake ninja - - - If you have MacPorts, you can run:: - - sudo port install cmake ninja - -Compile the Toolchain from Source -================================= - -- Install dependencies: - - - with MacPorts:: - - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - - - with homebrew:: - - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make - -Create a case-sensitive filesystem image:: - - hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" - -Mount it:: - - hdiutil mount ~/esp/crosstool.dmg - -Create a symlink to your work directory:: - - mkdir -p ~/esp - ln -s /Volumes/ctng ~/esp/ctng-volume - -Go into the newly created directory:: - - cd ~/esp/ctng-volume - -Download ``crosstool-NG`` and build it: - -.. include:: /_build/inc/scratch-build-code.inc - -Build the toolchain:: - - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf - -Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable. - - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started-cmake/macos-setup.rst b/docs/en/get-started-cmake/macos-setup.rst deleted file mode 100644 index 7926ea9d5..000000000 --- a/docs/en/get-started-cmake/macos-setup.rst +++ /dev/null @@ -1,60 +0,0 @@ -*********************************************** -Installation of Prerequisites for macOS (CMake) -*********************************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -Install Prerequisites -===================== - -ESP-IDF will use the version of Python installed by default on macOS. - -- install pip:: - - sudo easy_install pip - -- install pyserial:: - - pip install --user pyserial - -- install CMake & Ninja build: - - - If you have HomeBrew_, you can run:: - - brew install cmake ninja - - - If you have MacPorts_, you can run:: - - sudo port install cmake ninja - - - Otherwise, consult the CMake_ and Ninja_ home pages for macOS installation downloads. - -- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_. - -.. note:: - If an error like this is shown during any step:: - - xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun - - Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``. - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. - -Related Documents -================= - -.. toctree:: - :maxdepth: 1 - - macos-setup-scratch - -.. _cmake: https://cmake.org/ -.. _ninja: https://ninja-build.org/ -.. _ccache: https://ccache.samba.org/ -.. _homebrew: https://brew.sh/ -.. _MacPorts: https://www.macports.org/install.php diff --git a/docs/en/get-started-cmake/windows-setup-scratch.rst b/docs/en/get-started-cmake/windows-setup-scratch.rst deleted file mode 100644 index 4fa8168fe..000000000 --- a/docs/en/get-started-cmake/windows-setup-scratch.rst +++ /dev/null @@ -1,122 +0,0 @@ -********************************** -Windows Setup from Scratch (CMake) -********************************** - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer ` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install. - -To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`. - -.. note:: - The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment. - -.. _get-esp-idf-windows-command-line-cmake: - -Get ESP-IDF -=========== - -.. note:: - - Previous versions of ESP-IDF used the **MSYS2 bash terminal** command line. The current cmake-based build system can run in the regular **Windows Command Prompt** which is used here. - - If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below. - -Open Command Prompt and run the following commands: - -.. include:: /_build/inc/git-clone-windows.inc - -ESP-IDF will be downloaded into ``%userprofile%\esp\esp-idf``. - -Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. - -.. include:: /_build/inc/git-clone-notes.inc - -.. note:: - - Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: - - cd esp-idf - git submodule update --init - - -Tools -===== - -cmake -^^^^^ - -Download the latest stable release of CMake_ for Windows and run the installer. - -When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user". - -Ninja build -^^^^^^^^^^^ - -.. note:: - Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented. - -Download the ninja_ latest stable Windows release from the (`download page `_). - -The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path `_ (or you can choose a directory which is already on your Path). - - -Python 2.x -^^^^^^^^^^ - -Download the latest Python_ 2.7 for Windows installer, and run it. - -The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed". - -Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command:: - - pip install --user pyserial - -MConf for IDF -^^^^^^^^^^^^^ - -Download the configuration tool mconf-idf from the `kconfig-frontends releases page `_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF. - -This tool will also need to be unzipped to a directory which is then `added to your Path `_. - -Toolchain Setup -=============== - -.. include:: /_build/inc/download-links.inc - -Download the precompiled Windows toolchain: - -|download_link_win32| - -Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``. - -Next, the ``bin`` subdirectory of this directory must be `added to your Path `_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``. - -.. note:: - If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. - - -.. _add-directory-windows-path-cmake: - -Adding Directory to Path -======================== - -To add any new directory to your Windows Path environment variable: - -Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings). - -Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;``. - - -Next Steps -========== - -To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. - -.. _ninja: https://ninja-build.org/ -.. _Python: https://www.python.org/downloads/windows/ -.. _MSYS2: https://msys2.github.io/ -.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ - diff --git a/docs/en/get-started-cmake/windows-setup.rst b/docs/en/get-started-cmake/windows-setup.rst deleted file mode 100644 index d226c5f0f..000000000 --- a/docs/en/get-started-cmake/windows-setup.rst +++ /dev/null @@ -1,70 +0,0 @@ -************************************************* -Installation of Prerequisites for Windows (CMake) -************************************************* - -:link_to_translation:`zh_CN:[中文]` - -.. include:: ../cmake-warning.rst - -.. note:: - The CMake-based build system is only supported on 64-bit versions of Windows. - -Introduction -============ - -ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Python, Git, cross-compilers, menuconfig tool, CMake and Ninja build tools. - -For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse ` or another graphical IDE with CMake support instead. - -.. note:: - The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment. - -.. _get-started-cmake-windows-tools-installer: - -ESP-IDF Tools Installer -======================= - -The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL: - -https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe - -The installer includes the cross-compilers, OpenOCD, cmake_ and Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for Python_ 3.7 and `Git For Windows`_ if they are not already installed on the computer. - -The installer also offers to download one of the ESP-IDF release versions. - -Using the Command Prompt -======================== - -For the remaining Getting Started steps, we're going to use the Windows Command Prompt. - -ESP-IDF Tools Installer creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This shortcut launches the Command Prompt (cmd.exe) and runs ``export.bat`` script to set up the environment variables (``PATH``, ``IDF_PATH`` and others). Inside this command prompt, all the installed tools are available. - -Note that this shortcut is specific to the ESP-IDF directory selected in the ESP-IDF Tools Installer. If you have multiple ESP-IDF directories on the computer (for example, to work with different versions of ESP-IDF), you have two options to use them: - -1. Create a copy of the shortcut created by the ESP-IDF Tools Installer, and change the working directory of the new shortcut to the ESP-IDF directory you wish to use. - -2. Alternatively, run ``cmd.exe``, then change to the ESP-IDF directory you wish to use, and run ``export.bat``. Note that unlike the previous option, this way requires Python and Git to be present in ``PATH``. If you get errors related to Python or Git not being found, use the first option. - -Next Steps -========== - -If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project-cmake`. - -Related Documents -================= - -For advanced users who want to customize the install process: - -.. toctree:: - :maxdepth: 1 - - windows-setup-scratch - windows-setup-update - -.. _MSYS2: https://msys2.github.io/ -.. _cmake: https://cmake.org/download/ -.. _ninja: https://ninja-build.org/ -.. _Python: https://www.python.org/downloads/windows/ -.. _Git for Windows: https://gitforwindows.org/ -.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/ -.. _Github Desktop: https://desktop.github.com/ diff --git a/docs/en/get-started-legacy/get-started/add-idf_path-to-profile.rst b/docs/en/get-started-legacy/get-started/add-idf_path-to-profile.rst new file mode 100644 index 000000000..8ce9a9ae6 --- /dev/null +++ b/docs/en/get-started-legacy/get-started/add-idf_path-to-profile.rst @@ -0,0 +1,65 @@ +Add IDF_PATH to User Profile +============================ +:link_to_translation:`zh_CN:[中文]` + +To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below. + + +.. _add-idf_path-to-profile-windows: + +Windows +------- + +The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window. + +#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``. + +#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf`` + +#. Add the ``export`` command to the script file, e.g.:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + + Remember to replace back-slashes with forward-slashes in the original Windows path. + +#. Save the script file. + +#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing:: + + printenv IDF_PATH + + The path previusly entered in the script file should be printed out. + +If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window:: + + export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" + +If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. + + +.. _add-idf_path-to-profile-linux-macos: + +Linux and MacOS +--------------- + +Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file:: + + export IDF_PATH=~/esp/esp-idf + +Log off and log in back to make this change effective. + +.. note:: + + If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. + +Run the following command to check if ``IDF_PATH`` is set:: + + printenv IDF_PATH + +The path previously entered in ``~/.profile`` file (or set manually) should be printed out. + +If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout:: + + export IDF_PATH=~/esp/esp-idf + +If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. diff --git a/docs/en/get-started-legacy/get-started/eclipse-setup.rst b/docs/en/get-started-legacy/get-started/eclipse-setup.rst new file mode 100644 index 000000000..d03494ddd --- /dev/null +++ b/docs/en/get-started-legacy/get-started/eclipse-setup.rst @@ -0,0 +1,109 @@ +******************************** +Build and Flash with Eclipse IDE +******************************** +:link_to_translation:`zh_CN:[中文]` + +.. _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.) + +Setting up Eclipse +================== + +Once your new Eclipse installation launches, follow these steps: + +Import New Project +------------------ + +* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory. + +* Once Eclipse is running, choose File -> Import... + +* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next. + +* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile). + +* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish. + + +Project Properties +------------------ + +* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu. + +* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``. + +* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. Windows users can copy the ``IDF_PATH`` from windows explorer. + +* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. Windows users will need to prepend ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` to ``PATH`` environment variable (If you installed msys32 to a different directory then you’ll need to change these paths to match). + +* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python. + +**ADDITIONAL NOTE**: If either the IDF_PATH directory or the project directory is located outside ``C:\msys32\home`` directory, you will have to give custom build command in C/C++ Build properties as: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` (Please note that the build time may get significantly increased by this method.) + +Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page: + +* Click the "Providers" tab + +* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``. + +* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` + +Navigate to "C/C++ General" -> "Indexer" property page: + +* Check "Enable project specific settings" to enable the rest of the settings on this page. + +* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories. + +Navigate to "C/C++ Build" -> "Behavior" property page: + +* Check "Enable parallel build" to enable multiple build jobs in parallel. + +.. _eclipse-build-project: + +Building in Eclipse +------------------- + +Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project. + +* Click OK to close the Properties dialog in Eclipse. + +* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse. + +*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.* + +* Back in Eclipse, choose Project -> Build to build your project. + +**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths. + +Flash from Eclipse +------------------ + +You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI: + +* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.) + +* Select Build Targets -> Create... from the context menu. + +* Type "flash" as the target name. Leave the other options as their defaults. + +* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project. + +Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.) + +Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary. + + +.. _eclipse.org: https://www.eclipse.org/ + diff --git a/docs/en/get-started-cmake/establish-serial-connection.rst b/docs/en/get-started-legacy/get-started/establish-serial-connection.rst similarity index 84% rename from docs/en/get-started-cmake/establish-serial-connection.rst rename to docs/en/get-started-legacy/get-started/establish-serial-connection.rst index a02e04c88..7e0e3a91e 100644 --- a/docs/en/get-started-cmake/establish-serial-connection.rst +++ b/docs/en/get-started-legacy/get-started/establish-serial-connection.rst @@ -1,6 +1,5 @@ -Establish Serial Connection with ESP32 (CMake) -============================================== - +Establish Serial Connection with ESP32 +====================================== :link_to_translation:`zh_CN:[中文]` This section provides guidance how to establish serial connection between ESP32 and PC. @@ -11,7 +10,7 @@ Connect ESP32 to PC Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. -Below are the links to drivers for ESP32 boards produced by Espressif: +Below are the links to drivers for ESP32 and other boards produced by Espressif: .. csv-table:: @@ -73,12 +72,8 @@ MacOS :: ls /dev/cu.* -.. note:: - MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI. - - -.. _linux-dialout-group-cmake: +.. _linux-dialout-group: Adding user to ``dialout`` on Linux ----------------------------------- @@ -141,7 +136,7 @@ Then open serial port in terminal and check, if you see any log printed out by E ... -If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. +If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. .. note:: @@ -149,8 +144,9 @@ If you can see readable log output, it means serial connection is working and yo .. note:: - Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal. + Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal. + +If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`. -If you got here from :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure-cmake`. .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/en/get-started-legacy/get-started/index.rst b/docs/en/get-started-legacy/get-started/index.rst new file mode 100644 index 000000000..12ab81c02 --- /dev/null +++ b/docs/en/get-started-legacy/get-started/index.rst @@ -0,0 +1,452 @@ +*********** +Get Started +*********** + +:link_to_translation:`zh_CN:[中文]` + +This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32. + +After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board. + +.. include:: /_build/inc/version-note.inc + +Introduction +============ + +ESP32 is a system on a chip that integrates the following features: + +* Wi-Fi (2.4 GHz band) +* Bluetooth 4.2 +* Dual high performance cores +* Ultra Low Power co-processor +* Several peripherals + +Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. + +Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. + +What You Need +============= + +Hardware: + +* An **ESP32** board +* **USB cable** - USB A / micro USB B +* **Computer** running Windows, Linux, or macOS + +Software: + +* **Toolchain** to build the **Application** for ESP32 +* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** +* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ + + +.. figure:: ../../_static/what-you-need.png + :align: center + :alt: Development of applications for ESP32 + :figclass: align-center + + Development of applications for ESP32 + + +Development Board Overviews +=========================== + +If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware. + +.. toctree:: + :maxdepth: 1 + + ESP32-DevKitC + ESP-WROVER-KIT + ESP32-PICO-KIT + ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + + +.. _get-started-step-by-step: + +Installation Step by Step +========================= + +This is a detailed roadmap to walk you through the installation process. + +Setting up Development Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* :ref:`get-started-setup-toolchain` for :doc:`Windows `, :doc:`Linux ` or :doc:`MacOS ` +* :ref:`get-started-get-esp-idf` +* :ref:`get-started-setup-path` +* :ref:`get-started-get-packages` + +Creating Your First Project +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* :ref:`get-started-start-project` +* :ref:`get-started-connect` +* :ref:`get-started-configure` +* :ref:`get-started-build-and-flash` +* :ref:`get-started-monitor` + + +.. _get-started-setup-toolchain: + +Step 1. Set up the Toolchain +============================ + +The toolchain is a set of programs for compiling code and building applications. + +The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow the provided instructions. + +.. toctree:: + :hidden: + + Windows + Linux + MacOS + ++-------------------+-------------------+-------------------+ +| |windows-logo| | |linux-logo| | |macos-logo| | ++-------------------+-------------------+-------------------+ +| `Windows`_ | `Linux`_ | `Mac OS`_ | ++-------------------+-------------------+-------------------+ + +.. |windows-logo| image:: ../../_static/windows-logo.png + :target: ../get-started/windows-setup.html + +.. |linux-logo| image:: ../../_static/linux-logo.png + :target: ../get-started/linux-setup.html + +.. |macos-logo| image:: ../../_static/macos-logo.png + :target: ../get-started/macos-setup.html + +.. _Windows: ../get-started/windows-setup.html +.. _Linux: ../get-started/linux-setup.html +.. _Mac OS: ../get-started/macos-setup.html + +.. note:: + + This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths. + +Depending on your experience and preferences, you may want to customize your environment instead of using a prebuilt toolchain. To set up the system your own way go to Section :ref:`get-started-customized-setup`. + + +.. _get-started-get-esp-idf: + +Step 2. Get ESP-IDF +=================== + +Besides the toolchain, you also need ESP32-specific API (software libraries and source code). They are provided by Espressif in `ESP-IDF repository `_. + +To get a local copy of ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``. + +Open Terminal, and run the following commands: + +.. include:: /_build/inc/git-clone-bash.inc + +ESP-IDF will be downloaded into ``~/esp/esp-idf``. + +Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. + +.. include:: /_build/inc/git-clone-notes.inc + +.. note:: + + Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: + + cd esp-idf + git submodule update --init + + +.. _get-started-setup-path: + +Step 3. Set Environment Variables +================================= + +The toolchain uses the environment variable ``IDF_PATH`` to access the ESP-IDF directory. This variable should be set up on your computer, otherwise projects will not build. + +These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in Section :doc:`add-idf_path-to-profile`. + + +.. _get-started-get-packages: + +Step 4. Install the Required Python Packages +============================================ + +The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running:: + + python -m pip install --user -r $IDF_PATH/requirements.txt + +.. note:: + + Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run + the command ``python --version`` and depending on the result, you might want to use ``python2``, ``python2.7`` + or similar instead of just ``python``, e.g.:: + + python2.7 -m pip install --user -r $IDF_PATH/requirements.txt + + +.. _get-started-start-project: + +Step 5. Start a Project +======================= + +Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. + +Copy :example:`get-started/hello_world` to the ``~/esp`` directory: + +Linux and MacOS +~~~~~~~~~~~~~~~ + +.. code-block:: bash + + cd ~/esp + cp -r $IDF_PATH/examples/get-started/hello_world . + +Windows +~~~~~~~ + +.. code-block:: batch + + cd %userprofile%\esp + xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world + +There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it. + +It is also possible to build examples in-place, without copying them first. + +.. important:: + + The esp-idf build system does not support spaces in the paths to either esp-idf or to projects. + +.. _get-started-connect: + +Step 6. Connect Your Device +=========================== + +Now connect your ESP32 board to the computer and check under what serial port the board is visible. + +Serial ports have the following patterns in their names: + +- **Windows**: names like ``COM1`` +- **Linux**: starting with ``/dev/tty`` +- **macOS**: starting with ``/dev/cu.`` + +If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details. + +.. note:: + + Keep the port name handy as you will need it in the next steps. + + +.. _get-started-configure: + +Step 7. Configure +================= + +Navigate to your ``hello_world`` directory from :ref:`get-started-start-project` and run the project configuration utility ``menuconfig``. + +Linux and MacOS +~~~~~~~~~~~~~~~ + +.. code-block:: bash + + cd ~/esp/hello_world + make menuconfig + +Windows +~~~~~~~ + +.. code-block:: batch + + cd %userprofile%\esp\hello_world + make menuconfig + +If the previous steps have been done correctly, the following menu appears: + +.. figure:: ../../_static/project-configuration.png + :align: center + :alt: Project configuration - Home window + :figclass: align-center + + Project configuration - Home window + +In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit ``menuconfig`` by selecting ``< Exit >``. + +To navigate and use ``menuconfig``, press the following keys: + +* Arrow keys for navigation +* ``Enter`` to go into a submenu +* ``Esc`` to go up one level or exit +* ``?`` to see a help screen. Enter key exits the help screen +* ``Space``, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``" +* ``?`` while highlighting a configuration item to display help about that item +* ``/`` to find configuration items + +.. note:: + + If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``. + +.. attention:: + + If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. + +.. _get-started-build-and-flash: + +Step 8. Build and Flash +======================= + +Build and flash the project by running:: + + make flash + +This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. After that, these binaries will be flashed onto your ESP32 board. + +If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up. + +.. highlight:: none + +:: + + esptool.py v2.0-beta2 + Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... + esptool.py v2.0-beta2 + Connecting........___ + Uploading stub... + Running stub... + Stub running... + Changing baud rate to 921600 + Changed. + Attaching SPI flash... + Configuring flash size... + Auto-detected Flash size: 4MB + Flash params set to 0x0220 + Compressed 11616 bytes to 6695... + Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... + Hash of data verified. + Compressed 408096 bytes to 171625... + Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... + Hash of data verified. + Compressed 3072 bytes to 82... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... + Hash of data verified. + + Leaving... + Hard resetting... + + +If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. + + +.. _get-started-monitor: + +Step 9. Monitor +=============== + +To check if "hello_world" is indeed running, type ``make monitor``. + +This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application:: + + $ make monitor + MONITOR + --- idf_monitor on /dev/ttyUSB0 115200 --- + --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- + ets Jun 8 2016 00:22:57 + + rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) + ets Jun 8 2016 00:22:57 + ... + +After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application. + +.. code-block:: none + + ... + Hello world! + Restarting in 10 seconds... + I (211) cpu_start: Starting scheduler on APP CPU. + Restarting in 9 seconds... + Restarting in 8 seconds... + Restarting in 7 seconds... + +To exit IDF monitor use the shortcut ``Ctrl+]``. + +If IDF monitor fails shortly after the upload, or if instead of the messages above you see a random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. + +.. code-block:: none + + e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA + ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp + +If you have such a problem, do the following: + +1. Exit the monitor. +2. Go back to :ref:`menuconfig `. +3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. +4. After that, :ref:`build and flash ` the application again. + +.. note:: + + You can combine building, flashing and monitoring into one step by running:: + + make flash monitor + +See also :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. + +**That's all that you need to get started with ESP32!** + +Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications. + + +Environment Variables +===================== + +Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without the need to reconfigure them using** ``make menuconfig``. + ++-----------------+--------------------------------------------------------------+ +| Variables | Description & Usage | ++=================+==============================================================+ +| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. | +| | | +| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, | +| | ``make monitor ESPPORT=COM1`` | ++-----------------+--------------------------------------------------------------+ +| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. | +| | | +| | Example: ``make flash ESPBAUD=9600`` | ++-----------------+--------------------------------------------------------------+ +| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. | +| | | +| | Example: ``make monitor MONITORBAUD=9600`` | ++-----------------+--------------------------------------------------------------+ + +.. note:: + + You can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``). + All subsequent calls of ``make`` within the same terminal session will use + the exported value given that the variable is not simultaneously overridden. + + +Updating ESP-IDF +================ + +You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`. + +If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts can find ESP-IDF in its release specific location. + +Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `. + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + add-idf_path-to-profile + establish-serial-connection + make-project + eclipse-setup + ../api-guides/tools/idf-monitor + toolchain-setup-scratch + +.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ +.. _Releases page: https://github.com/espressif/esp-idf/releases diff --git a/docs/en/get-started-legacy/get-started/linux-setup-scratch.rst b/docs/en/get-started-legacy/get-started/linux-setup-scratch.rst new file mode 100644 index 000000000..395458153 --- /dev/null +++ b/docs/en/get-started-legacy/get-started/linux-setup-scratch.rst @@ -0,0 +1,75 @@ +********************************** +Setup Linux Toolchain from Scratch +********************************** +:link_to_translation:`zh_CN:[中文]` + +.. note:: + + Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. + +Install Prerequisites +===================== + +To compile with ESP-IDF you need to get the following packages: + +- Ubuntu and Debian:: + + sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + +.. note:: + + Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF. + In this case please install a supported version via ``pip`` as it is described in section + :ref:`get-started-get-packages`. + +Compile the Toolchain from Source +================================= + +- Install dependencies: + + - CentOS 7:: + + sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool + + - Ubuntu pre-16.04:: + + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool + + - Ubuntu 16.04 or newer:: + + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin + + - Debian 9:: + + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin + + - Arch:: + + TODO + +Create the working directory and go into it:: + + mkdir -p ~/esp + cd ~/esp + +Download ``crosstool-NG`` and build it: + +.. include:: /_build/inc/scratch-build-code.inc + +Build the toolchain:: + + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf + +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. diff --git a/docs/en/get-started-legacy/get-started/linux-setup.rst b/docs/en/get-started-legacy/get-started/linux-setup.rst new file mode 100644 index 000000000..7484b4c62 --- /dev/null +++ b/docs/en/get-started-legacy/get-started/linux-setup.rst @@ -0,0 +1,118 @@ +************************************* +Standard Setup of Toolchain for Linux +************************************* +:link_to_translation:`zh_CN:[中文]` + +Install Prerequisites +===================== + +To compile with ESP-IDF you need to get the following packages: + +- CentOS 7:: + + sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography + +- Ubuntu and Debian:: + + sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + +- Arch:: + + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + +.. note:: + + Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`. + +Toolchain Setup +=============== + +.. include:: /_build/inc/download-links.inc + +ESP32 toolchain for Linux is available for download from Espressif website: + +- for 64-bit Linux: + + |download_link_linux64| + +- for 32-bit Linux: + + |download_link_linux32| + +1. Download this file, then extract it in ``~/esp`` directory: + + - for 64-bit Linux: + + .. include:: /_build/inc/unpack-code-linux64.inc + + - for 32-bit Linux: + + .. include:: /_build/inc/unpack-code-linux32.inc + +.. _setup-linux-toolchain-add-it-to-path: + +2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. + + To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: + + export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" + + Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: + + alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' + + Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. + + .. note:: + + If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. In CentOS, ``alias`` should set in ``.bashrc``. + +3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set:: + + printenv PATH + + You are looking for similar result containing toolchain's path at the beginning of displayed string:: + + $ printenv PATH + /home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin + + Instead of ``/home/user-name`` there should be a home path specific to your installation. + + +Permission issues /dev/ttyUSB0 +------------------------------ + +With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group`. + + +Arch Linux Users +---------------- + +To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. + +Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: + +- https://aur.archlinux.org/packages/ncurses5-compat-libs/ +- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ + +Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above. + +Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + linux-setup-scratch + + +.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository diff --git a/docs/en/get-started-legacy/get-started/macos-setup-scratch.rst b/docs/en/get-started-legacy/get-started/macos-setup-scratch.rst new file mode 100644 index 000000000..a4dfe9d7f --- /dev/null +++ b/docs/en/get-started-legacy/get-started/macos-setup-scratch.rst @@ -0,0 +1,72 @@ +*************************************** +Setup Toolchain for Mac OS from Scratch +*************************************** +:link_to_translation:`zh_CN:[中文]` + +.. note:: + + Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. + +Install Prerequisites +===================== + +- install pip:: + + sudo easy_install pip + +.. note:: + + ``pip`` will be used later for installing :ref:`the required Python packages `. + +Compile the Toolchain from Source +================================= + +- Install dependencies: + + - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. + + .. _homebrew: https://brew.sh/ + .. _MacPorts: https://www.macports.org/install.php + + - with MacPorts:: + + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake + + - with homebrew:: + + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake + +Create a case-sensitive filesystem image:: + + hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" + +Mount it:: + + hdiutil mount ~/esp/crosstool.dmg + +Create a symlink to your work directory:: + + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume + +Go into the newly created directory:: + + cd ~/esp/ctng-volume + +Download ``crosstool-NG`` and build it: + +.. include:: /_build/inc/scratch-build-code.inc + +Build the toolchain:: + + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf + +Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. diff --git a/docs/en/get-started-legacy/get-started/macos-setup.rst b/docs/en/get-started-legacy/get-started/macos-setup.rst new file mode 100644 index 000000000..7e1921a6c --- /dev/null +++ b/docs/en/get-started-legacy/get-started/macos-setup.rst @@ -0,0 +1,57 @@ +************************************** +Standard Setup of Toolchain for Mac OS +************************************** +:link_to_translation:`zh_CN:[中文]` + +Install Prerequisites +===================== + +- install pip:: + + sudo easy_install pip + +.. note:: + + ``pip`` will be used later for installing :ref:`the required Python packages `. + +Toolchain Setup +=============== + +.. include:: /_build/inc/download-links.inc + +ESP32 toolchain for macOS is available for download from Espressif website: + +|download_link_osx| + +Download this file, then extract it in ``~/esp`` directory: + +.. include:: /_build/inc/unpack-code-osx.inc + +.. _setup-macos-toolchain-add-it-to-path: + +The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. + +To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: + + export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH + +Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: + + alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" + +Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + macos-setup-scratch diff --git a/docs/en/get-started/make-project.rst b/docs/en/get-started-legacy/get-started/make-project.rst similarity index 100% rename from docs/en/get-started/make-project.rst rename to docs/en/get-started-legacy/get-started/make-project.rst diff --git a/docs/en/get-started-cmake/toolchain-setup-scratch.rst b/docs/en/get-started-legacy/get-started/toolchain-setup-scratch.rst similarity index 72% rename from docs/en/get-started-cmake/toolchain-setup-scratch.rst rename to docs/en/get-started-legacy/get-started/toolchain-setup-scratch.rst index c7b0ee32d..c5f2b5ae4 100644 --- a/docs/en/get-started-cmake/toolchain-setup-scratch.rst +++ b/docs/en/get-started-legacy/get-started/toolchain-setup-scratch.rst @@ -1,12 +1,10 @@ -.. _get-started-customized-setup-cmake: +.. _get-started-customized-setup: -************************************* -Customized Setup of Toolchain (CMake) -************************************* +***************************** +Customized Setup of Toolchain +***************************** -:link_to_translation:`zh_CN:[中文]` - -Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-set-up-tools-cmake`) you may build the toolchain yourself. +Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain`) you may build the toolchain yourself. If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source: diff --git a/docs/en/get-started-legacy/get-started/windows-setup-scratch.rst b/docs/en/get-started-legacy/get-started/windows-setup-scratch.rst new file mode 100644 index 000000000..fc64e2a23 --- /dev/null +++ b/docs/en/get-started-legacy/get-started/windows-setup-scratch.rst @@ -0,0 +1,117 @@ +************************************ +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. + +To quickly setup the toolchain in standard way, using a prebuilt environment, 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 +============================================ + +.. include:: /_build/inc/download-links.inc + +If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: + +|download_link_win32| + +.. note:: + + If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download. + +.. important:: + + Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support). + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + +.. _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 diff --git a/docs/en/get-started-legacy/get-started/windows-setup.rst b/docs/en/get-started-legacy/get-started/windows-setup.rst new file mode 100644 index 000000000..d2a267828 --- /dev/null +++ b/docs/en/get-started-legacy/get-started/windows-setup.rst @@ -0,0 +1,70 @@ +*************************************** +Standard Setup of Toolchain for Windows +*************************************** +:link_to_translation:`zh_CN:[中文]` + +Introduction +============ + +Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse ` or some other front-end), but it runs behind the scenes. + + +Toolchain Setup +=============== + +The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com: + +https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip + +Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment. + + +Check it Out +============ + +Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command:: + + mkdir -p ~/esp + +By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step. + +.. figure:: ../../_static/msys2-terminal-window.png + :align: center + :alt: MSYS2 MINGW32 shell window + :figclass: align-center + + MSYS2 MINGW32 shell window + +Use this window in the following steps setting up development environment for ESP32. + + +Next Steps +========== + +To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. + +Updating The Environment +======================== + +When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one: + +- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``). +- Download the new precompiled environment using the steps above. +- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location). +- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``. +- You can now delete the ``C:\msys32_old`` directory if you no longer need it. + +You can have independent different MSYS2 environments on your system, as long as they are in different directories. + +There are :ref:`also steps to update the existing environment without downloading a new one `, although this is more complex. + +Related Documents +================= + +.. toctree:: + :maxdepth: 1 + + windows-setup-scratch + + +.. _MSYS2: https://msys2.github.io/ diff --git a/docs/en/get-started/add-idf_path-to-profile.rst b/docs/en/get-started/add-idf_path-to-profile.rst index 8ce9a9ae6..cdaf9a5b8 100644 --- a/docs/en/get-started/add-idf_path-to-profile.rst +++ b/docs/en/get-started/add-idf_path-to-profile.rst @@ -1,65 +1,3 @@ -Add IDF_PATH to User Profile -============================ -:link_to_translation:`zh_CN:[中文]` +:orphan: -To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below. - - -.. _add-idf_path-to-profile-windows: - -Windows -------- - -The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window. - -#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``. - -#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf`` - -#. Add the ``export`` command to the script file, e.g.:: - - export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" - - Remember to replace back-slashes with forward-slashes in the original Windows path. - -#. Save the script file. - -#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing:: - - printenv IDF_PATH - - The path previusly entered in the script file should be printed out. - -If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window:: - - export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf" - -If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. - - -.. _add-idf_path-to-profile-linux-macos: - -Linux and MacOS ---------------- - -Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file:: - - export IDF_PATH=~/esp/esp-idf - -Log off and log in back to make this change effective. - -.. note:: - - If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. - -Run the following command to check if ``IDF_PATH`` is set:: - - printenv IDF_PATH - -The path previously entered in ``~/.profile`` file (or set manually) should be printed out. - -If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout:: - - export IDF_PATH=~/esp/esp-idf - -If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. +.. Remove this file when the Chinese translation of CMake getting started guide is updated diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst index d03494ddd..2e2b105bc 100644 --- a/docs/en/get-started/eclipse-setup.rst +++ b/docs/en/get-started/eclipse-setup.rst @@ -1,109 +1,12 @@ -******************************** -Build and Flash with Eclipse IDE -******************************** +**************************************** +Build and Flash with Eclipse IDE (CMake) +**************************************** + :link_to_translation:`zh_CN:[中文]` -.. _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.) - -Setting up Eclipse -================== - -Once your new Eclipse installation launches, follow these steps: - -Import New Project ------------------- - -* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory. - -* Once Eclipse is running, choose File -> Import... - -* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next. - -* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile). - -* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish. - - -Project Properties ------------------- - -* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu. - -* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``. - -* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. Windows users can copy the ``IDF_PATH`` from windows explorer. - -* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. Windows users will need to prepend ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` to ``PATH`` environment variable (If you installed msys32 to a different directory then you’ll need to change these paths to match). - -* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python. - -**ADDITIONAL NOTE**: If either the IDF_PATH directory or the project directory is located outside ``C:\msys32\home`` directory, you will have to give custom build command in C/C++ Build properties as: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` (Please note that the build time may get significantly increased by this method.) - -Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page: - -* Click the "Providers" tab - -* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``. - -* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)`` - -Navigate to "C/C++ General" -> "Indexer" property page: - -* Check "Enable project specific settings" to enable the rest of the settings on this page. - -* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories. - -Navigate to "C/C++ Build" -> "Behavior" property page: - -* Check "Enable parallel build" to enable multiple build jobs in parallel. - -.. _eclipse-build-project: - -Building in Eclipse -------------------- - -Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project. - -* Click OK to close the Properties dialog in Eclipse. - -* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse. - -*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.* - -* Back in Eclipse, choose Project -> Build to build your project. - -**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths. - -Flash from Eclipse ------------------- - -You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI: - -* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.) - -* Select Build Targets -> Create... from the context menu. - -* Type "flash" as the target name. Leave the other options as their defaults. - -* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project. - -Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.) - -Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary. +.. include:: ../cmake-warning.rst +Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon. .. _eclipse.org: https://www.eclipse.org/ diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst index 7e0e3a91e..a02e04c88 100644 --- a/docs/en/get-started/establish-serial-connection.rst +++ b/docs/en/get-started/establish-serial-connection.rst @@ -1,5 +1,6 @@ -Establish Serial Connection with ESP32 -====================================== +Establish Serial Connection with ESP32 (CMake) +============================================== + :link_to_translation:`zh_CN:[中文]` This section provides guidance how to establish serial connection between ESP32 and PC. @@ -10,7 +11,7 @@ Connect ESP32 to PC Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. -Below are the links to drivers for ESP32 and other boards produced by Espressif: +Below are the links to drivers for ESP32 boards produced by Espressif: .. csv-table:: @@ -72,8 +73,12 @@ MacOS :: ls /dev/cu.* +.. note:: -.. _linux-dialout-group: + MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI. + + +.. _linux-dialout-group-cmake: Adding user to ``dialout`` on Linux ----------------------------------- @@ -136,7 +141,7 @@ Then open serial port in terminal and check, if you see any log printed out by E ... -If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. +If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. .. note:: @@ -144,9 +149,8 @@ If you see some legible log, it means serial connection is working and you are r .. note:: - Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal. - -If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`. + Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal. +If you got here from :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure-cmake`. .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index ffcc6f079..e5f810c09 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -1,12 +1,16 @@ -*********** -Get Started -*********** +******************* +Get Started (CMake) +******************* :link_to_translation:`zh_CN:[中文]` -This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32. +.. include:: ../cmake-warning.rst -After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board. +.. include:: ../cmake-pending-features.rst + +This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif. + +After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board. .. include:: /_build/inc/version-note.inc @@ -36,12 +40,13 @@ Hardware: Software: -* **Toolchain** to build the **Application** for ESP32 +* **Toolchain** to compile code for ESP32 +* **Build tools** - CMake and Ninja to build a full **Application** for ESP32 * **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** * **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ -.. figure:: ../../_static/what-you-need.png +.. figure:: ../../_static/what-you-need-cmake.png :align: center :alt: Development of applications for ESP32 :figclass: align-center @@ -61,9 +66,9 @@ If you have one of ESP32 development boards listed below, you can click on the l ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + - -.. _get-started-step-by-step: +.. _get-started-step-by-step-cmake: Installation Step by Step ========================= @@ -73,71 +78,57 @@ This is a detailed roadmap to walk you through the installation process. Setting up Development Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* :ref:`get-started-setup-toolchain` for :doc:`Windows `, :doc:`Linux ` or :doc:`MacOS ` -* :ref:`get-started-get-esp-idf` -* :ref:`get-started-setup-path` -* :ref:`get-started-get-packages` +* :ref:`get-started-get-prerequisites-cmake` for :doc:`Windows `, :doc:`Linux ` or :doc:`macOS ` +* :ref:`get-started-get-esp-idf-cmake` +* :ref:`get-started-set-up-tools-cmake` +* :ref:`get-started-set-up-env-cmake` Creating Your First Project ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* :ref:`get-started-start-project` -* :ref:`get-started-connect` -* :ref:`get-started-configure` -* :ref:`get-started-build-and-flash` -* :ref:`get-started-monitor` +* :ref:`get-started-start-project-cmake` +* :ref:`get-started-connect-cmake` +* :ref:`get-started-configure-cmake` +* :ref:`get-started-build-cmake` +* :ref:`get-started-flash-cmake` +* :ref:`get-started-build-monitor-cmake` -.. _get-started-setup-toolchain: +.. _get-started-get-prerequisites-cmake: -Step 1. Set up the Toolchain -============================ +Step 1. Install prerequisites +============================= -The toolchain is a set of programs for compiling code and building applications. - -The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow the provided instructions. +Some tools need to be installed on the computer before proceeding to the next steps. Follow the links below for the instructions for your OS: .. toctree:: :hidden: Windows - Linux - MacOS + Linux + macOS -+-------------------+-------------------+-------------------+ -| |windows-logo| | |linux-logo| | |macos-logo| | -+-------------------+-------------------+-------------------+ -| `Windows`_ | `Linux`_ | `Mac OS`_ | -+-------------------+-------------------+-------------------+ +* :doc:`windows-setup` +* :doc:`linux-setup` +* :doc:`macos-setup` -.. |windows-logo| image:: ../../_static/windows-logo.png - :target: ../get-started/windows-setup.html +.. _get-started-get-esp-idf-cmake: -.. |linux-logo| image:: ../../_static/linux-logo.png - :target: ../get-started/linux-setup.html +Step 2. Get ESP-IDF +=================== -.. |macos-logo| image:: ../../_static/macos-logo.png - :target: ../get-started/macos-setup.html +To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository `_. -.. _Windows: ../get-started/windows-setup.html -.. _Linux: ../get-started/linux-setup.html -.. _Mac OS: ../get-started/macos-setup.html +Get ESP-IDF in accordance with your operating system. + +To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``. .. note:: This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths. -Depending on your experience and preferences, you may want to customize your environment instead of using a prebuilt toolchain. To set up the system your own way go to Section :ref:`get-started-customized-setup`. - - -.. _get-started-get-esp-idf: - -Step 2. Get ESP-IDF -=================== - -Besides the toolchain, you also need ESP32-specific API (software libraries and source code). They are provided by Espressif in `ESP-IDF repository `_. - -To get a local copy of ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``. +Linux and macOS +~~~~~~~~~~~~~~~ Open Terminal, and run the following commands: @@ -147,54 +138,90 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``. Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. -.. include:: /_build/inc/git-clone-notes.inc +Windows +~~~~~~~ -.. note:: +In addition to installing the tools, :ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 can also download a copy of ESP-IDF. - Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: +Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. - cd esp-idf - git submodule update --init +If you wish to download ESP-IDF without the help of ESP-IDF Tools Installer, refer to these :ref:`instructions `. +.. _get-started-set-up-tools-cmake: -.. _get-started-setup-path: +Step 3. Set up the tools +======================== -Step 3. Set Environment Variables -================================= +Aside from the ESP-IDF, you also need to install the tools used by ESP-IDF, such as the compiler, debugger, Python packages, etc. -The toolchain uses the environment variable ``IDF_PATH`` to access the ESP-IDF directory. This variable should be set up on your computer, otherwise projects will not build. +Windows +~~~~~~~ -These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in Section :doc:`add-idf_path-to-profile`. +:ref:`get-started-cmake-windows-tools-installer` for Windows introduced in Step 1 installs all the required tools. +If you want to install the tools without the help of ESP-IDF Tools Installer, open the Command Prompt and follow these steps: -.. _get-started-get-packages: +.. code-block:: batch -Step 4. Install the Required Python Packages -============================================ + cd %userprofile%\esp\esp-idf + install.bat -The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running:: +Linux and macOS +~~~~~~~~~~~~~~~ - python -m pip install --user -r $IDF_PATH/requirements.txt +.. code-block:: bash -.. note:: + cd ~/esp/esp-idf + ./install.sh - Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run - the command ``python --version`` and depending on the result, you might want to use ``python2``, ``python2.7`` - or similar instead of just ``python``, e.g.:: +Customizing the tools installation path +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - python2.7 -m pip install --user -r $IDF_PATH/requirements.txt +The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user has sufficient permissions to read and write this path. +If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the ``install.bat``/``install.sh`` and ``export.bat``/``export.sh`` scripts are executed. -.. _get-started-start-project: +.. _get-started-set-up-env-cmake: + +Step 4. Set up the environment variables +======================================== + +The installed tools are not yet added to the PATH environment variable. To make the tools usable from the command line, some environment variables must be set. ESP-IDF provides another script which does that. + +Windows +~~~~~~~ + +:ref:`get-started-cmake-windows-tools-installer` for Windows creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables. You can open this shortcut and proceed to the next step. + +Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, you can run: + +.. code-block:: batch + + %userprofile%\esp\esp-idf\export.bat + +Linux and macOS +~~~~~~~~~~~~~~~ + +In the terminal where you are going to use ESP-IDF, run: + +.. code-block:: bash + + . $HOME/esp/esp-idf/export.sh + +Note the space between the leading dot and the path! + +You can also automate this step, making ESP-IDF tools available in every terminal, by adding this line to your ``.profile`` or ``.bash_profile`` script. + +.. _get-started-start-project-cmake: Step 5. Start a Project ======================= Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. -Copy :example:`get-started/hello_world` to the ``~/esp`` directory: +Copy :example:`get-started/hello_world` to ``~/esp`` directory: -Linux and MacOS +Linux and macOS ~~~~~~~~~~~~~~~ .. code-block:: bash @@ -216,9 +243,9 @@ It is also possible to build examples in-place, without copying them first. .. important:: - The esp-idf build system does not support spaces in the paths to either esp-idf or to projects. + The ESP-IDF build system does not support spaces in the paths to either ESP-IDF or to projects. -.. _get-started-connect: +.. _get-started-connect-cmake: Step 6. Connect Your Device =========================== @@ -238,20 +265,22 @@ If you are not sure how to check the serial port name, please refer to :doc:`est Keep the port name handy as you will need it in the next steps. -.. _get-started-configure: +.. _get-started-configure-cmake: Step 7. Configure ================= -Navigate to your ``hello_world`` directory from :ref:`get-started-start-project` and run the project configuration utility ``menuconfig``. +Navigate to your ``hello_world`` directory from :ref:`get-started-start-project-cmake` and run the project configuration utility ``menuconfig``. -Linux and MacOS +Linux and macOS ~~~~~~~~~~~~~~~ .. code-block:: bash cd ~/esp/hello_world - make menuconfig + idf.py menuconfig + +If your default version of Python is 3.x, you may need to run ``python2 $(which idf.py) menuconfig`` instead. Windows ~~~~~~~ @@ -259,7 +288,7 @@ Windows .. code-block:: batch cd %userprofile%\esp\hello_world - make menuconfig + idf.py menuconfig If the previous steps have been done correctly, the following menu appears: @@ -270,8 +299,6 @@ If the previous steps have been done correctly, the following menu appears: Project configuration - Home window -In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit ``menuconfig`` by selecting ``< Exit >``. - To navigate and use ``menuconfig``, press the following keys: * Arrow keys for navigation @@ -282,72 +309,111 @@ To navigate and use ``menuconfig``, press the following keys: * ``?`` while highlighting a configuration item to display help about that item * ``/`` to find configuration items -.. note:: - - If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``. - .. attention:: If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. -.. _get-started-build-and-flash: +.. _get-started-build-cmake: -Step 8. Build and Flash -======================= +Step 8. Build the Project +========================= -Build and flash the project by running:: +Build the project by running:: - make flash + idf.py build -This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. After that, these binaries will be flashed onto your ESP32 board. +This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. -If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up. +.. code-block:: none -.. highlight:: none + $ idf.py build + Running cmake in directory /path/to/hello_world/build + Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"... + Warn about uninitialized values. + -- Found Git: /usr/bin/git (found version "2.17.0") + -- Building empty aws_iot component due to configuration + -- Component names: ... + -- Component paths: ... + + ... (more lines of build system output) + + [527/527] Generating hello-world.bin + esptool.py v2.3.1 + + Project build complete. To flash, run this command: + ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin + or run 'idf.py -p PORT flash' -:: +If there are no errors, the build will finish by generating the firmware binary .bin file. - esptool.py v2.0-beta2 - Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)... - esptool.py v2.0-beta2 - Connecting........___ + +.. _get-started-flash-cmake: + +Step 9. Flash onto the Device +============================= + +Flash the binaries that you just built onto your ESP32 board by running:: + + idf.py -p PORT [-b BAUD] flash + +Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect-cmake`. + +You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``. + +For more information on idf.py arguments, see :ref:`idf.py`. + +.. note:: + + The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary. + +.. code-block:: none + + Running esptool.py in directory [...]/esp/hello_world + Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"... + esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin + esptool.py v2.3.1 + Connecting.... + Detecting chip type... ESP32 + Chip is ESP32D0WDQ6 (revision 1) + Features: WiFi, BT, Dual Core Uploading stub... Running stub... Stub running... - Changing baud rate to 921600 + Changing baud rate to 460800 Changed. - Attaching SPI flash... Configuring flash size... Auto-detected Flash size: 4MB Flash params set to 0x0220 - Compressed 11616 bytes to 6695... - Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)... - Hash of data verified. - Compressed 408096 bytes to 171625... - Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)... + Compressed 22992 bytes to 13019... + Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)... Hash of data verified. Compressed 3072 bytes to 82... - Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)... + Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)... Hash of data verified. - + Compressed 136672 bytes to 67544... + Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... + Hash of data verified. + Leaving... - Hard resetting... + Hard resetting via RTS pin... + +If there are no issues by the end of the flash process, the module will be reset and the “hello_world” application will be running. + +.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide `. -If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `. +.. _get-started-build-monitor-cmake: +Step 10. Monitor +================ -.. _get-started-monitor: - -Step 9. Monitor -=============== - -To check if "hello_world" is indeed running, type ``make monitor``. +To check if "hello_world" is indeed running, type ``idf.py -p PORT monitor`` (Do not forget to replace PORT with your serial port name). This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application:: - $ make monitor - MONITOR + $ idf.py -p /dev/ttyUSB0 monitor + Running idf_monitor in directory [...]/esp/hello_world/build + Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"... --- idf_monitor on /dev/ttyUSB0 115200 --- --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- ets Jun 8 2016 00:22:57 @@ -370,7 +436,7 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print To exit IDF monitor use the shortcut ``Ctrl+]``. -If IDF monitor fails shortly after the upload, or if instead of the messages above you see a random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. +If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value. .. code-block:: none @@ -380,73 +446,46 @@ If IDF monitor fails shortly after the upload, or if instead of the messages abo If you have such a problem, do the following: 1. Exit the monitor. -2. Go back to :ref:`menuconfig `. +2. Go back to :ref:`menuconfig `. 3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. -4. After that, :ref:`build and flash ` the application again. +4. After that, :ref:`build and flash ` the application again. .. note:: You can combine building, flashing and monitoring into one step by running:: - make flash monitor + idf.py -p PORT flash monitor -See also :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. +See also: + +- :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor. +- :ref:`idf.py` for a full reference of ``idf.py`` commands and options. **That's all that you need to get started with ESP32!** Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications. - -Environment Variables -===================== - -Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without the need to reconfigure them using** ``make menuconfig``. - -+-----------------+--------------------------------------------------------------+ -| Variables | Description & Usage | -+=================+==============================================================+ -| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. | -| | | -| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, | -| | ``make monitor ESPPORT=COM1`` | -+-----------------+--------------------------------------------------------------+ -| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. | -| | | -| | Example: ``make flash ESPBAUD=9600`` | -+-----------------+--------------------------------------------------------------+ -| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. | -| | | -| | Example: ``make monitor MONITORBAUD=9600`` | -+-----------------+--------------------------------------------------------------+ - -.. note:: - - You can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``). - All subsequent calls of ``make`` within the same terminal session will use - the exported value given that the variable is not simultaneously overridden. - - Updating ESP-IDF ================ -You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`. - -If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts can find ESP-IDF in its release specific location. +You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf-cmake`. Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `. +After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools-cmake`. + +Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env-cmake`. + Related Documents ================= .. toctree:: :maxdepth: 1 - add-idf_path-to-profile establish-serial-connection - make-project eclipse-setup ../api-guides/tools/idf-monitor toolchain-setup-scratch .. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ -.. _Releases page: https://github.com/espressif/esp-idf/releases +.. _Releases page: https://github.com/espressif/esp-idf/releases \ No newline at end of file diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst index 395458153..51abaf6fd 100644 --- a/docs/en/get-started/linux-setup-scratch.rst +++ b/docs/en/get-started/linux-setup-scratch.rst @@ -1,30 +1,32 @@ -********************************** -Setup Linux Toolchain from Scratch -********************************** +****************************************** +Setup Linux Toolchain from Scratch (CMake) +****************************************** + :link_to_translation:`zh_CN:[中文]` -.. note:: - - Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. +.. include:: ../cmake-warning.rst + +The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`. Install Prerequisites ===================== To compile with ESP-IDF you need to get the following packages: +- CentOS 7:: + + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache + - Ubuntu and Debian:: - sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache .. note:: - - Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF. - In this case please install a supported version via ``pip`` as it is described in section - :ref:`get-started-get-packages`. + CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake". Compile the Toolchain from Source ================================= @@ -33,19 +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 or newer:: - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make - Debian 9:: - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make - Arch:: @@ -66,10 +68,10 @@ Build the toolchain:: ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst index 7484b4c62..429755b9b 100644 --- a/docs/en/get-started/linux-setup.rst +++ b/docs/en/get-started/linux-setup.rst @@ -1,8 +1,11 @@ -************************************* -Standard Setup of Toolchain for Linux -************************************* +*********************************************** +Installation of Prerequisites for Linux (CMake) +*********************************************** + :link_to_translation:`zh_CN:[中文]` +.. include:: ../cmake-warning.rst + Install Prerequisites ===================== @@ -10,85 +13,32 @@ To compile with ESP-IDF you need to get the following packages: - CentOS 7:: - sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography + sudo yum install git wget ncurses-devel flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache - Ubuntu and Debian:: - sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - Arch:: - sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools + sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache .. note:: + CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake". - Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`. - -Toolchain Setup +Additional Tips =============== -.. include:: /_build/inc/download-links.inc - -ESP32 toolchain for Linux is available for download from Espressif website: - -- for 64-bit Linux: - - |download_link_linux64| - -- for 32-bit Linux: - - |download_link_linux32| - -1. Download this file, then extract it in ``~/esp`` directory: - - - for 64-bit Linux: - - .. include:: /_build/inc/unpack-code-linux64.inc - - - for 32-bit Linux: - - .. include:: /_build/inc/unpack-code-linux32.inc - -.. _setup-linux-toolchain-add-it-to-path: - -2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. - - To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: - - export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" - - Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: - - alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' - - Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. - - .. note:: - - If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. In CentOS, ``alias`` should set in ``.bashrc``. - -3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set:: - - printenv PATH - - You are looking for similar result containing toolchain's path at the beginning of displayed string:: - - $ printenv PATH - /home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin - - Instead of ``/home/user-name`` there should be a home path specific to your installation. - - Permission issues /dev/ttyUSB0 ------------------------------ -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`. +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. +To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. Backwards compatibility libraries are available in AUR_ for native and lib32 configurations: @@ -103,7 +53,7 @@ Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. Related Documents diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index a4dfe9d7f..45fa4238c 100644 --- a/docs/en/get-started/macos-setup-scratch.rst +++ b/docs/en/get-started/macos-setup-scratch.rst @@ -1,11 +1,22 @@ -*************************************** -Setup Toolchain for Mac OS from Scratch -*************************************** +*********************************************** +Setup Toolchain for Mac OS from Scratch (CMake) +*********************************************** + :link_to_translation:`zh_CN:[中文]` -.. note:: - - Standard process for installing the toolchain is described :doc:`here `. See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. +.. include:: ../cmake-warning.rst + +Package Manager +=============== + +To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain`, you will need to install either the MacPorts_ or homebrew_ package manager. + +MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. + + .. _homebrew: https://brew.sh/ + .. _MacPorts: https://www.macports.org/install.php + +See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. Install Prerequisites ===================== @@ -14,27 +25,32 @@ Install Prerequisites sudo easy_install pip -.. note:: +- install pyserial:: - ``pip`` will be used later for installing :ref:`the required Python packages `. + pip install --user pyserial + +- install CMake & Ninja build: + + - If you have HomeBrew, you can run:: + + brew install cmake ninja + + - If you have MacPorts, you can run:: + + sudo port install cmake ninja Compile the Toolchain from Source ================================= - Install dependencies: - - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. - - .. _homebrew: https://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php - - with MacPorts:: - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - with homebrew:: - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make Create a case-sensitive filesystem image:: @@ -63,10 +79,10 @@ Build the toolchain:: ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup ` to add the toolchain to your ``PATH``. +Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst index 7e1921a6c..7926ea9d5 100644 --- a/docs/en/get-started/macos-setup.rst +++ b/docs/en/get-started/macos-setup.rst @@ -1,52 +1,49 @@ -************************************** -Standard Setup of Toolchain for Mac OS -************************************** +*********************************************** +Installation of Prerequisites for macOS (CMake) +*********************************************** + :link_to_translation:`zh_CN:[中文]` +.. include:: ../cmake-warning.rst + Install Prerequisites ===================== +ESP-IDF will use the version of Python installed by default on macOS. + - install pip:: sudo easy_install pip +- install pyserial:: + + pip install --user pyserial + +- install CMake & Ninja build: + + - If you have HomeBrew_, you can run:: + + brew install cmake ninja + + - If you have MacPorts_, you can run:: + + sudo port install cmake ninja + + - Otherwise, consult the CMake_ and Ninja_ home pages for macOS installation downloads. + +- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_. + .. note:: + If an error like this is shown during any step:: - ``pip`` will be used later for installing :ref:`the required Python packages `. - -Toolchain Setup -=============== - -.. include:: /_build/inc/download-links.inc - -ESP32 toolchain for macOS is available for download from Espressif website: - -|download_link_osx| - -Download this file, then extract it in ``~/esp`` directory: - -.. include:: /_build/inc/unpack-code-osx.inc - -.. _setup-macos-toolchain-add-it-to-path: - -The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory. - -To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: - - export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH - -Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file:: - - alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" - -Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``. + xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun + Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. - +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. Related Documents ================= @@ -55,3 +52,9 @@ Related Documents :maxdepth: 1 macos-setup-scratch + +.. _cmake: https://cmake.org/ +.. _ninja: https://ninja-build.org/ +.. _ccache: https://ccache.samba.org/ +.. _homebrew: https://brew.sh/ +.. _MacPorts: https://www.macports.org/install.php diff --git a/docs/en/get-started/toolchain-setup-scratch.rst b/docs/en/get-started/toolchain-setup-scratch.rst index c5f2b5ae4..c7b0ee32d 100644 --- a/docs/en/get-started/toolchain-setup-scratch.rst +++ b/docs/en/get-started/toolchain-setup-scratch.rst @@ -1,10 +1,12 @@ -.. _get-started-customized-setup: +.. _get-started-customized-setup-cmake: -***************************** -Customized Setup of Toolchain -***************************** +************************************* +Customized Setup of Toolchain (CMake) +************************************* -Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain`) you may build the toolchain yourself. +:link_to_translation:`zh_CN:[中文]` + +Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-set-up-tools-cmake`) you may build the toolchain yourself. If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source: diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst index fc64e2a23..4fa8168fe 100644 --- a/docs/en/get-started/windows-setup-scratch.rst +++ b/docs/en/get-started/windows-setup-scratch.rst @@ -1,117 +1,122 @@ -************************************ -Setup Windows Toolchain from Scratch -************************************ +********************************** +Windows Setup from Scratch (CMake) +********************************** -Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment `, addressed to less experienced users, has been prepared by following these steps. +:link_to_translation:`zh_CN:[中文]` -To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`. +.. include:: ../cmake-warning.rst +This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer ` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install. -.. _configure-windows-toolchain-from-scratch: +To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`. -Configure Toolchain & Environment from Scratch -============================================== +.. note:: + The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment. -This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain. +.. _get-esp-idf-windows-command-line-cmake: -* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``. - -* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.** - -* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal. - - *(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)* - -* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer. - -* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does. - -* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain. - - -Troubleshooting -~~~~~~~~~~~~~~~ - -* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following:: - - *** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL. - - If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step. - -* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_. - - -MSYS2 Mirrors in China -~~~~~~~~~~~~~~~~~~~~~~ - -There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China. - -To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``). - -Add these lines at the top of ``mirrorlist.mingw32``:: - - Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/ - Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686 - -Add these lines at the top of ``mirrorlist.msys``:: - - Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch - Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch - - -HTTP Proxy -~~~~~~~~~~ - -You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script:: - - export http_proxy='http://http.proxy.server:PORT' - -Or with credentials:: - - export http_proxy='http://user:password@http.proxy.server:PORT' - -Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS. - - -Alternative Setup: Just download a toolchain -============================================ - -.. include:: /_build/inc/download-links.inc - -If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: - -|download_link_win32| +Get ESP-IDF +=========== .. note:: - If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download. + Previous versions of ESP-IDF used the **MSYS2 bash terminal** command line. The current cmake-based build system can run in the regular **Windows Command Prompt** which is used here. -.. important:: + If you use a bash-based terminal or PowerShell, please note that some command syntax will be different to what is shown below. - Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support). +Open Command Prompt and run the following commands: + +.. include:: /_build/inc/git-clone-windows.inc + +ESP-IDF will be downloaded into ``%userprofile%\esp\esp-idf``. + +Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation. + +.. include:: /_build/inc/git-clone-notes.inc + +.. note:: + + Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules:: + + cd esp-idf + git submodule update --init + + +Tools +===== + +cmake +^^^^^ + +Download the latest stable release of CMake_ for Windows and run the installer. + +When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user". + +Ninja build +^^^^^^^^^^^ + +.. note:: + Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented. + +Download the ninja_ latest stable Windows release from the (`download page `_). + +The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path `_ (or you can choose a directory which is already on your Path). + + +Python 2.x +^^^^^^^^^^ + +Download the latest Python_ 2.7 for Windows installer, and run it. + +The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed". + +Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command:: + + pip install --user pyserial + +MConf for IDF +^^^^^^^^^^^^^ + +Download the configuration tool mconf-idf from the `kconfig-frontends releases page `_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF. + +This tool will also need to be unzipped to a directory which is then `added to your Path `_. + +Toolchain Setup +=============== + +.. include:: /_build/inc/download-links.inc + +Download the precompiled Windows toolchain: + +|download_link_win32| + +Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``. + +Next, the ``bin`` subdirectory of this directory must be `added to your Path `_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``. + +.. note:: + If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. + + +.. _add-directory-windows-path-cmake: + +Adding Directory to Path +======================== + +To add any new directory to your Windows Path environment variable: + +Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings). + +Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;``. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. - -.. _updating-existing-windows-environment: - -Updating The Environment -======================== - -When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment. - -Rather than setting up a new environment, you can update an existing Windows environment & toolchain: - -- Update IDF to the new version you want to use. -- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version. - -The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_. - -If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. +.. _ninja: https://ninja-build.org/ +.. _Python: https://www.python.org/downloads/windows/ .. _MSYS2: https://msys2.github.io/ -.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/ -.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new +.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/ + diff --git a/docs/en/get-started-cmake/windows-setup-update.rst b/docs/en/get-started/windows-setup-update.rst similarity index 100% rename from docs/en/get-started-cmake/windows-setup-update.rst rename to docs/en/get-started/windows-setup-update.rst diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst index d2a267828..d226c5f0f 100644 --- a/docs/en/get-started/windows-setup.rst +++ b/docs/en/get-started/windows-setup.rst @@ -1,70 +1,70 @@ -*************************************** -Standard Setup of Toolchain for Windows -*************************************** +************************************************* +Installation of Prerequisites for Windows (CMake) +************************************************* + :link_to_translation:`zh_CN:[中文]` +.. include:: ../cmake-warning.rst + +.. note:: + The CMake-based build system is only supported on 64-bit versions of Windows. + Introduction ============ -Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse ` or some other front-end), but it runs behind the scenes. +ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Python, Git, cross-compilers, menuconfig tool, CMake and Ninja build tools. +For this Getting Started we're going to use the Command Prompt, but after ESP-IDF is installed you can use :doc:`Eclipse ` or another graphical IDE with CMake support instead. -Toolchain Setup -=============== +.. note:: + The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment. -The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com: +.. _get-started-cmake-windows-tools-installer: -https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip +ESP-IDF Tools Installer +======================= -Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment. +The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL: +https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe -Check it Out -============ +The installer includes the cross-compilers, OpenOCD, cmake_ and Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for Python_ 3.7 and `Git For Windows`_ if they are not already installed on the computer. -Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command:: +The installer also offers to download one of the ESP-IDF release versions. - mkdir -p ~/esp +Using the Command Prompt +======================== -By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step. +For the remaining Getting Started steps, we're going to use the Windows Command Prompt. -.. figure:: ../../_static/msys2-terminal-window.png - :align: center - :alt: MSYS2 MINGW32 shell window - :figclass: align-center +ESP-IDF Tools Installer creates a shortcut in the Start menu to launch the ESP-IDF Command Prompt. This shortcut launches the Command Prompt (cmd.exe) and runs ``export.bat`` script to set up the environment variables (``PATH``, ``IDF_PATH`` and others). Inside this command prompt, all the installed tools are available. - MSYS2 MINGW32 shell window +Note that this shortcut is specific to the ESP-IDF directory selected in the ESP-IDF Tools Installer. If you have multiple ESP-IDF directories on the computer (for example, to work with different versions of ESP-IDF), you have two options to use them: -Use this window in the following steps setting up development environment for ESP32. +1. Create a copy of the shortcut created by the ESP-IDF Tools Installer, and change the working directory of the new shortcut to the ESP-IDF directory you wish to use. +2. Alternatively, run ``cmd.exe``, then change to the ESP-IDF directory you wish to use, and run ``export.bat``. Note that unlike the previous option, this way requires Python and Git to be present in ``PATH``. If you get errors related to Python or Git not being found, use the first option. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`. - -Updating The Environment -======================== - -When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one: - -- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``). -- Download the new precompiled environment using the steps above. -- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location). -- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``. -- You can now delete the ``C:\msys32_old`` directory if you no longer need it. - -You can have independent different MSYS2 environments on your system, as long as they are in different directories. - -There are :ref:`also steps to update the existing environment without downloading a new one `, although this is more complex. +If the ESP-IDF Tools Installer has finished successfully, then the development environment setup is complete. Proceed directly to :ref:`get-started-start-project-cmake`. Related Documents ================= +For advanced users who want to customize the install process: + .. toctree:: :maxdepth: 1 windows-setup-scratch - + windows-setup-update .. _MSYS2: https://msys2.github.io/ +.. _cmake: https://cmake.org/download/ +.. _ninja: https://ninja-build.org/ +.. _Python: https://www.python.org/downloads/windows/ +.. _Git for Windows: https://gitforwindows.org/ +.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/ +.. _Github Desktop: https://desktop.github.com/ diff --git a/docs/en/hw-reference/get-started-devkitc-v2.rst b/docs/en/hw-reference/get-started-devkitc-v2.rst index 2b558f6e9..bef33a278 100644 --- a/docs/en/hw-reference/get-started-devkitc-v2.rst +++ b/docs/en/hw-reference/get-started-devkitc-v2.rst @@ -9,7 +9,7 @@ This guide shows how to start using the ESP32-DevKitC V2 development board. What You Need ------------- -* :ref:`ESP32-DevKitC V2 board ` +* ESP32-DevKitC V2 board * USB A / micro USB B cable * Computer running Windows, Linux, or macOS @@ -27,7 +27,7 @@ Functional Description The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitC V2 board. -.. _get-started-esp32-devkitc-v2-board-front-cmake: +.. _get-started-esp32-devkitc-v2-board-front-make: .. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png :align: center @@ -71,9 +71,7 @@ Start Application Development Before powering up your ESP32-DevKitC V2, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents diff --git a/docs/en/hw-reference/get-started-devkitc.rst b/docs/en/hw-reference/get-started-devkitc.rst index d15807dbc..3d1064025 100644 --- a/docs/en/hw-reference/get-started-devkitc.rst +++ b/docs/en/hw-reference/get-started-devkitc.rst @@ -1,5 +1,5 @@ ESP32-DevKitC V4 Getting Started Guide -============================================== +====================================== :link_to_translation:`zh_CN:[中文]` @@ -9,19 +9,19 @@ This guide shows how to start using the ESP32-DevKitC V4 development board. For What You Need ------------- -* :ref:`ESP32-DevKitC V4 board ` +* ESP32-DevKitC V4 board * USB A / micro USB B cable * Computer running Windows, Linux, or macOS You can skip the introduction sections and go directly to Section `Start Application Development`_. -.. _DevKitC-Overview-cmake: +.. _DevKitC-Overview: Overview -------- -ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif `_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard. +ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif `_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can either connect peripherals with jumper wires or mount ESP32-DevKitC V4 on a breadboard. To cover a wide range of user requirements, the following versions of ESP32-DevKitC V4 are available: @@ -46,7 +46,7 @@ Functional Description The following figure and the table below describe the key components, interfaces and controls of the ESP32-DevKitC V4 board. -.. _get-started-esp32-devkitc-board-front-cmake: +.. _get-started-esp32-devkitc-board-front: .. figure:: ../../_static/esp32-devkitc-functional-overview.jpg :align: center @@ -107,6 +107,7 @@ The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boa In case these issues occur, please remove the component. The figure below shows C15 highlighted in yellow. + .. figure:: ../../_static/esp32-devkitc-c15-location.png :align: center :alt: Location of C15 (colored yellow) on ESP32-DevKitC V4 board @@ -121,9 +122,7 @@ Start Application Development Before powering up your ESP32-DevKitC V4, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Board Dimensions diff --git a/docs/en/hw-reference/get-started-pico-kit-v3.rst b/docs/en/hw-reference/get-started-pico-kit-v3.rst index a124582a5..b8b2366f6 100644 --- a/docs/en/hw-reference/get-started-pico-kit-v3.rst +++ b/docs/en/hw-reference/get-started-pico-kit-v3.rst @@ -1,5 +1,5 @@ ESP32-PICO-KIT V3 Getting Started Guide -=============================================== +======================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For the description of other ESP32-PICO-KIT versions, please check :doc:`../hw-reference/index`. @@ -65,9 +65,7 @@ Start Application Development Before powering up your ESP32-PICO-KIT V3, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents diff --git a/docs/en/hw-reference/get-started-pico-kit.rst b/docs/en/hw-reference/get-started-pico-kit.rst index 7c7ff7304..73c4b5ef6 100644 --- a/docs/en/hw-reference/get-started-pico-kit.rst +++ b/docs/en/hw-reference/get-started-pico-kit.rst @@ -10,7 +10,7 @@ This particular description covers ESP32-PICO-KIT V4 and V4.1. The difference is What You Need ------------- -* :ref:`ESP32-PICO-KIT mini development board ` +* :ref:`ESP32-PICO-KIT mini development board ` * USB 2.0 A to Micro B cable * Computer running Windows, Linux, or macOS @@ -58,7 +58,7 @@ Functional Description The following figure and the table below describe the key components, interfaces, and controls of the ESP32-PICO-KIT board. -.. _get-started-pico-kit-v4-board-front-cmake: +.. _get-started-pico-kit-v4-board-front: .. figure:: ../../_static/esp32-pico-kit-v4.1-f-layout.jpeg :align: center @@ -107,7 +107,7 @@ There are three mutually exclusive ways to provide power to the board: Pin Descriptions ---------------- -The two tables below provide the **Name** and **Function** of I/O header pins on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front-cmake`. The pin numbering and header names are the same as in the schematic given in `Related Documents`_. +The two tables below provide the **Name** and **Function** of I/O header pins on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front`. The pin numbering and header names are the same as in the schematic given in `Related Documents`_. Header J2 @@ -116,9 +116,9 @@ Header J2 ====== ================= ====== ====================================================== No. Name Type Function ====== ================= ====== ====================================================== -1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(See 1) ` , U2CTS -2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(See 1) ` , U2RTS -3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) ` , U1CTS +1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(See 1) ` , U2CTS +2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(See 1) ` , U2RTS +3 FLASH_CLK (FCLK) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(See 1) ` , U1CTS 4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN 5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1 6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0 @@ -127,8 +127,8 @@ No. Name Type Function 9 IO5 I/O | GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK 10 IO10 I/O | GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD 11 IO9 I/O | GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD -12 RXD0 I/O | GPIO3, U0RXD :ref:`(See 3) ` , CLK_OUT2 -13 TXD0 I/O | GPIO1, U0TXD :ref:`(See 3) ` , CLK_OUT3, EMAC_RXD2 +12 RXD0 I/O | GPIO3, U0RXD :ref:`(See 3) ` , CLK_OUT2 +13 TXD0 I/O | GPIO1, U0TXD :ref:`(See 3) ` , CLK_OUT3, EMAC_RXD2 14 IO35 I | ADC1_CH7, RTC_GPIO5 15 IO34 I | ADC1_CH6, RTC_GPIO4 16 IO38 I | GPIO38, ADC1_CH2, RTC_GPIO2 @@ -145,20 +145,20 @@ Header J3 ====== ================= ====== ====================================================== No. Name Type Function ====== ================= ====== ====================================================== -1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(See 1) ` , U2RXD, EMAC_CLK_OUT -2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(See 1) ` , U2TXD, EMAC_CLK_OUT_180 -3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(See 1) ` , U1RTS +1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(See 1) ` , U2RXD, EMAC_CLK_OUT +2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(See 1) ` , U2TXD, EMAC_CLK_OUT_180 +3 FLASH_SD2 (FSD2) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(See 1) ` , U1RTS 4 SENSOR_VP (FSVP) I | GPIO36, ADC1_CH0, RTC_GPIO0 5 SENSOR_VN (FSVN) I | GPIO39, ADC1_CH3, RTC_GPIO3 6 IO25 I/O | GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0 7 IO26 I/O | GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1 -8 IO32 I/O | 32K_XP :ref:`(See 2a) ` , ADC1_CH4, TOUCH9, RTC_GPIO9 -9 IO33 I/O | 32K_XN :ref:`(See 2b) ` , ADC1_CH5, TOUCH8, RTC_GPIO8 +8 IO32 I/O | 32K_XP :ref:`(See 2a) ` , ADC1_CH4, TOUCH9, RTC_GPIO9 +9 IO33 I/O | 32K_XN :ref:`(See 2b) ` , ADC1_CH5, TOUCH8, RTC_GPIO8 10 IO27 I/O | GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17 | EMAC_RX_DV 11 IO14 I/O | ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK, | HS2_CLK, SD_CLK, EMAC_TXD2 -12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(See 4) ` , HSPIQ, +12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(See 4) ` , HSPIQ, | HS2_DATA2, SD_DATA2, EMAC_TXD3 13 IO13 I/O | ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID, | HS2_DATA3, SD_DATA3, EMAC_RX_ER @@ -176,7 +176,7 @@ No. Name Type Function ====== ================= ====== ====================================================== -.. _get-started-pico-kit-v4-pin-notes-cmake: +.. _get-started-pico-kit-v4-pin-notes: The following notes give more information about the items in the tables above. @@ -193,9 +193,7 @@ Start Application Development Before powering up your ESP32-PICO-KIT, please make sure that the board is in good condition with no obvious signs of damage. -After that, proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +After that, proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Board Dimensions diff --git a/docs/en/hw-reference/get-started-wrover-kit-v2.rst b/docs/en/hw-reference/get-started-wrover-kit-v2.rst index 08da1d59f..1aa0c6b59 100644 --- a/docs/en/hw-reference/get-started-wrover-kit-v2.rst +++ b/docs/en/hw-reference/get-started-wrover-kit-v2.rst @@ -1,5 +1,5 @@ ESP-WROVER-KIT V2 Getting Started Guide -=============================================== +======================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP-WROVER-KIT V2 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. @@ -52,7 +52,7 @@ Functional Description The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board. -.. _get-started-esp-wrover-kit-v2-board-front-cmake: +.. _get-started-esp-wrover-kit-v2-board-front: .. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png :align: center @@ -61,7 +61,7 @@ The following two figures and the table below describe the key components, inter ESP-WROVER-KIT board layout - front -.. _get-started-esp-wrover-kit-v2-board-back-cmake: +.. _get-started-esp-wrover-kit-v2-board-back: .. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png :align: center @@ -116,11 +116,11 @@ I/O All the pins on the ESP32 module are broken out to pin heade MicroSD Card MicroSD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the MicroSD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in Section `Setup Options`_. -LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v2-board-back-cmake`. +LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v2-board-back`. ================== ================================================================================================================================= -.. _get-started-esp-wrover-kit-v2-setup-options-cmake: +.. _get-started-esp-wrover-kit-v2-setup-options: Setup Options ------------- @@ -140,7 +140,7 @@ JP14 |jp14| Enable RTS/CTS flow control for serial communication ======= ================ ========================================================= -.. _get-started-esp-wrover-kit-v2-start-development-cmake: +.. _get-started-esp-wrover-kit-v2-start-development: Start Application Development ----------------------------- @@ -170,9 +170,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -194,4 +192,4 @@ Related Documents .. |jp11-tx-rx| image:: ../../_static/wrover-jp11-tx-rx.png .. |jp14| image:: ../../_static/wrover-jp14.png -.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf \ No newline at end of file +.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf diff --git a/docs/en/hw-reference/get-started-wrover-kit-v3.rst b/docs/en/hw-reference/get-started-wrover-kit-v3.rst index e64e50d7d..276c6877b 100644 --- a/docs/en/hw-reference/get-started-wrover-kit-v3.rst +++ b/docs/en/hw-reference/get-started-wrover-kit-v3.rst @@ -1,5 +1,6 @@ + ESP-WROVER-KIT V3 Getting Started Guide -=============================================== +======================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP-WROVER-KIT V3 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. @@ -8,7 +9,7 @@ This guide shows how to get started with the ESP-WROVER-KIT V3 development board What You Need ------------- -* :ref:`ESP-WROVER-KIT V3 board ` +* :ref:`ESP-WROVER-KIT V3 board ` * USB 2.0 cable（A to Micro-B） * Computer running Windows, Linux, or macOS @@ -52,7 +53,7 @@ Functional Description The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board. -.. _get-started-esp-wrover-kit-v3-board-front-cmake: +.. _get-started-esp-wrover-kit-v3-board-front: .. figure:: ../../_static/esp-wrover-kit-v3-layout-front.jpg :align: center @@ -61,7 +62,7 @@ The following two figures and the table below describe the key components, inter ESP-WROVER-KIT board layout - front -.. _get-started-esp-wrover-kit-v3-board-back-cmake: +.. _get-started-esp-wrover-kit-v3-board-back: .. figure:: ../../_static/esp-wrover-kit-v3-layout-back.jpg :align: center @@ -118,11 +119,11 @@ I/O All the pins on the ESP32 module are broken out to pin heade MicroSD Card Slot Useful for developing applications that access MicroSD card for data storage and retrieval. -LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v3-board-back-cmake`. +LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v3-board-back`. ================== ================================================================================================================================= -.. _get-started-esp-wrover-kit-v3-setup-options-cmake: +.. _get-started-esp-wrover-kit-v3-setup-options: Setup Options ------------- @@ -178,17 +179,17 @@ JTAG, MicroSD IO15 5V Legend: -* NC/XTAL - :ref:`32.768 kHz Oscillator ` -* JTAG - :ref:`JTAG / JP8 ` +* NC/XTAL - :ref:`32.768 kHz Oscillator ` +* JTAG - :ref:`JTAG / JP8 ` * Boot - Boot button / SW2 -* Camera - :ref:`Camera / JP4 ` -* LED - :ref:`RGB LED ` -* MicroSD - :ref:`MicroSD Card / J4 ` -* LCD - :ref:`LCD / U5 ` +* Camera - :ref:`Camera / JP4 ` +* LED - :ref:`RGB LED ` +* MicroSD - :ref:`MicroSD Card / J4 ` +* LCD - :ref:`LCD / U5 ` * PSRAM - only in case ESP32-WROVER is installed -.. _get-started-esp-wrover-kit-v3-xtal-cmake: +.. _get-started-esp-wrover-kit-v3-xtal: 32.768 kHz Oscillator ^^^^^^^^^^^^^^^^^^^^^ @@ -205,7 +206,7 @@ Legend: Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24. -.. _get-started-esp-wrover-kit-v3-spi-flash-header-cmake: +.. _get-started-esp-wrover-kit-v3-spi-flash-header: SPI Flash / JP13 ^^^^^^^^^^^^^^^^ @@ -223,10 +224,10 @@ SPI Flash / JP13 .. important:: - The module's flash bus is connected to the jumper block JP13 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can disolder these resistors to disconnect the module's flash bus from the pin header JP13. + The module's flash bus is connected to the jumper block JP13 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can desolder these resistors to disconnect the module's flash bus from the pin header JP13. -.. _get-started-esp-wrover-kit-v3-jtag-header-cmake: +.. _get-started-esp-wrover-kit-v3-jtag-header: JTAG / JP8 ^^^^^^^^^^ @@ -242,7 +243,7 @@ JTAG / JP8 ==== ============== ============= -.. _get-started-esp-wrover-kit-v3-camera-header-cmake: +.. _get-started-esp-wrover-kit-v3-camera-header: Camera / JP4 ^^^^^^^^^^^^ @@ -273,7 +274,7 @@ Camera / JP4 * Signals D0 .. D7 denote camera data bus -.. _get-started-esp-wrover-kit-v3-rgb-led-connections-cmake: +.. _get-started-esp-wrover-kit-v3-rgb-led-connections: RGB LED ^^^^^^^ @@ -287,7 +288,7 @@ RGB LED ==== ========== ========= -.. _get-started-esp-wrover-kit-v3-microsd-card-slot-cmake: +.. _get-started-esp-wrover-kit-v3-microsd-card-slot: MicroSD Card ^^^^^^^^^^^^ @@ -305,7 +306,7 @@ MicroSD Card ==== ============== =============== -.. _get-started-esp-wrover-kit-v3-lcd-connector-cmake: +.. _get-started-esp-wrover-kit-v3-lcd-connector: LCD / U5 ^^^^^^^^ @@ -323,7 +324,7 @@ LCD / U5 ==== ============== =============== -.. _get-started-esp-wrover-kit-v3-start-development-cmake: +.. _get-started-esp-wrover-kit-v3-start-development: Start Application Development ----------------------------- @@ -353,9 +354,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -379,4 +378,4 @@ Related Documents .. toctree:: :hidden: - get-started-wrover-kit-v2.rst \ No newline at end of file + get-started-wrover-kit-v2.rst diff --git a/docs/en/hw-reference/get-started-wrover-kit.rst b/docs/en/hw-reference/get-started-wrover-kit.rst index 5a40efeb5..0be440976 100644 --- a/docs/en/hw-reference/get-started-wrover-kit.rst +++ b/docs/en/hw-reference/get-started-wrover-kit.rst @@ -1,5 +1,5 @@ ESP-WROVER-KIT V4.1 Getting Started Guide -================================================= +========================================= :link_to_translation:`zh_CN:[中文]` This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides information about its functionality and configuration options. For the description of other ESP-WROVER-KIT versions, please check :doc:`../hw-reference/index`. @@ -8,7 +8,7 @@ This guide shows how to get started with the ESP-WROVER-KIT V4.1 development boa What You Need ------------- -* :ref:`ESP-WROVER-KIT V4.1 board ` +* :ref:`ESP-WROVER-KIT V4.1 board ` * USB 2.0 cable（A to Micro-B） * Computer running Windows, Linux, or macOS @@ -51,9 +51,9 @@ The block diagram below shows the main components of ESP-WROVER-KIT and their in Functional Description ---------------------- -The following two figures and the table below describe the key components, interfaces and controls of the ESP-WROVER-KIT board. +The following two figures and the table below describe the key components, interfaces, and controls of the ESP-WROVER-KIT board. -.. _get-started-esp-wrover-kit-v4.1-board-front-cmake: +.. _get-started-esp-wrover-kit-v4.1-board-front: .. figure:: ../../_static/esp-wrover-kit-v4.1-layout-front.png :align: center @@ -62,7 +62,7 @@ The following two figures and the table below describe the key components, inter ESP-WROVER-KIT board layout - front -.. _get-started-esp-wrover-kit-v4.1-board-back-cmake: +.. _get-started-esp-wrover-kit-v4.1-board-back: .. figure:: ../../_static/esp-wrover-kit-v4.1-layout-back.png :align: center @@ -123,11 +123,11 @@ I/O Connector All the pins on the ESP32 module are broken out to pin heade MicroSD Card Slot Useful for developing applications that access MicroSD card for data storage and retrieval. -LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v4.1-board-back-cmake`. +LCD Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-v4.1-board-back`. ================== ================================================================================================================================= -.. _get-started-esp-wrover-kit-v4.1-setup-options-cmake: +.. _get-started-esp-wrover-kit-v4.1-setup-options: Setup Options ------------- @@ -183,17 +183,17 @@ JTAG, MicroSD IO15 5V Legend: -* NC/XTAL - :ref:`32.768 kHz Oscillator ` -* JTAG - :ref:`JTAG / JP8 ` +* NC/XTAL - :ref:`32.768 kHz Oscillator ` +* JTAG - :ref:`JTAG / JP8 ` * Boot - Boot button / SW2 -* Camera - :ref:`Camera / JP4 ` -* LED - :ref:`RGB LED ` -* MicroSD - :ref:`MicroSD Card / J4 ` -* LCD - :ref:`LCD / U5 ` +* Camera - :ref:`Camera / JP4 ` +* LED - :ref:`RGB LED ` +* MicroSD - :ref:`MicroSD Card / J4 ` +* LCD - :ref:`LCD / U5 ` * PSRAM - ESP32-WROVER-B's PSRAM -.. _get-started-esp-wrover-kit-v4.1-xtal-cmake: +.. _get-started-esp-wrover-kit-v4.1-xtal: 32.768 kHz Oscillator ^^^^^^^^^^^^^^^^^^^^^ @@ -210,7 +210,7 @@ Legend: Since GPIO32 and GPIO33 are connected to the oscillator by default, they are not connected to the JP1 I/O connector to maintain signal integrity. This allocation may be changed from the oscillator to JP1 by desoldering the zero-ohm resistors from positions R11 / R23 and re-soldering them to positions R12 / R24. -.. _get-started-esp-wrover-kit-v4.1-spi-flash-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-spi-flash-header: SPI Flash / JP2 ^^^^^^^^^^^^^^^ @@ -231,7 +231,7 @@ SPI Flash / JP2 The module's flash bus is connected to the jumper block JP2 through zero-ohm resistors R140 ~ R145. If the flash memory needs to operate at the frequency of 80 MHz, for reasons such as improving the integrity of bus signals, you can desolder these resistors to disconnect the module's flash bus from the pin header JP2. -.. _get-started-esp-wrover-kit-v4.1-jtag-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-jtag-header: JTAG / JP2 ^^^^^^^^^^ @@ -247,7 +247,7 @@ JTAG / JP2 ==== ============== ============= -.. _get-started-esp-wrover-kit-v4.1-camera-header-cmake: +.. _get-started-esp-wrover-kit-v4.1-camera-header: Camera / JP4 ^^^^^^^^^^^^ @@ -278,7 +278,7 @@ Camera / JP4 * Signals D0 .. D7 denote camera data bus -.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections-cmake: +.. _get-started-esp-wrover-kit-v4.1-rgb-led-connections: RGB LED ^^^^^^^ @@ -292,7 +292,7 @@ RGB LED ==== ========== ========= -.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot-cmake: +.. _get-started-esp-wrover-kit-v4.1-microsd-card-slot: MicroSD Card ^^^^^^^^^^^^ @@ -310,7 +310,7 @@ MicroSD Card ==== ============== =============== -.. _get-started-esp-wrover-kit-v4.1-lcd-connector-cmake: +.. _get-started-esp-wrover-kit-v4.1-lcd-connector: LCD / U5 ^^^^^^^^ @@ -328,7 +328,7 @@ LCD / U5 ==== ============== =============== -.. _get-started-esp-wrover-kit-start-development-cmake: +.. _get-started-esp-wrover-kit-start-development: Start Application Development ----------------------------- @@ -358,9 +358,7 @@ Turn the **Power Switch** to ON, the **5V Power On LED** should light up. Now to Development ^^^^^^^^^^^^^^^^^^ -Proceed to :doc:`../get-started-cmake/index`, where Section :ref:`get-started-step-by-step-cmake` will quickly help you set up the development environment and then flash an example project onto your board. - -If you prefer using an older GNU Make build system, then proceed to respective :ref:`get-started-step-by-step` for the GNU Make. +Please proceed to :doc:`index`, where Section :ref:`get-started-step-by-step` will quickly help you set up the development environment and then flash an example project onto your board. Related Documents @@ -384,4 +382,4 @@ Related Documents :hidden: get-started-wrover-kit-v3.rst - get-started-wrover-kit-v2.rst \ No newline at end of file + get-started-wrover-kit-v2.rst