Lines Matching +full:- +full:- +full:non +full:- +full:interactive
5 .. include:: ../gnu-make-legacy.rst
9 Read this document if you want to know how to organise an ESP-IDF project using GNU Make build syst…
11 We recommend using the esp-idf-template_ project as a starting point for your project.
16 The esp-idf README file contains a description of how to use the build system to build your project.
21 An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a web…
23 - The {IDF_TARGET_NAME} base libraries (libc, rom bindings etc)
24 - The Wi-Fi drivers
25 - A TCP/IP stack
26 - The FreeRTOS operating system
27 - A webserver
28 - A driver for the humidity sensor
29 - Main code tying it all together
31 …-IDF makes these components explicit and configurable. To do that, when a project is compiled, the…
34 --------
36 - A "project" is a directory that contains all the files and configuration to build a single "app" …
38 - "Project configuration" is held in a single file called sdkconfig in the root directory of the pr…
40 - An "app" is an executable which is built by esp-idf. A single project will usually build two apps…
42 - "components" are modular pieces of standalone code which are compiled into static libraries (.a f…
46 - "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the…
48 - The toolchain for compilation is not part of the project. The toolchain should be installed in th…
51 ---------------
55 - myProject/
56 - Makefile
57 - sdkconfig
58 - components/ - component1/ - component.mk
59 - Kconfig
60 - src1.c
61 - component2/ - component.mk
62 - Kconfig
63 - src1.c
64 - include/ - component2.h
65 - main/ - src1.c
66 - src2.c
67 - component.mk
69 - build/
73 - A top-level project Makefile. This Makefile sets the ``PROJECT_NAME`` variable and (optionally) d…
75 - "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs,…
77 - Optional "components" directory contains components that are part of the project. A project does …
79 - "main" directory is a special "pseudo-component" that contains source code for the project itself…
81 - "build" directory is where build output is created. After the make process is run, this directory…
83 Component directories contain a component makefile - ``component.mk``. This may contain variable de…
88 -----------------
104 - ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin,…
111 - ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile.…
112 - ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJE…
113 - ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `…
114 - ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components.
115 - ``COMPONENTS``: A list of component names to build into the project. Defaults to all components f…
116 - ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Not…
117 - ``TEST_EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process…
126 -------------------
128 Each project contains one or more components, which can either be part of esp-idf or added from oth…
133 ------------------------
135 …nents themselves (ie they contain a `component.mk` file), or they can be top-level directories who…
137 Running the ``make list-components`` target dumps many of these variables and can help debug the di…
142 …-idf is collecting all the components to compile, it will do this in the order specified by ``COMP…
143 If used in this way, the esp-idf directory itself can remain untouched.
151 - All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) wi…
152 - A sub-directory "include" will be added to the global include search path for all other component…
153 - The component library will be linked into the project app.
164 The following component-specific variables are available for use inside ``component.mk``, but shoul…
166 - ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory cont…
167 - ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory.
168 - ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a direc…
169 - ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory…
173 - ``PROJECT_NAME``: Name of the project, as set in project Makefile
174 - ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile.
175 - ``COMPONENTS``: Name of all components that are included in this build.
176 - ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in m…
177 - ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain.
178 - ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain.
179 - ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present)…
180 - ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF versio…
181 - ``PROJECT_VER``: Project version.
193 Optional Project-Wide Component Variables
198 - ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component directory, which will be added to…
199 - ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for the app executable. Defaults t…
200 - ``COMPONENT_DEPENDS``: Optional list of component names that should be compiled before this compo…
201 - ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths to files which should tr…
203 The following variable only works for components that are part of esp-idf itself:
205 - ``COMPONENT_SUBMODULES``: Optional list of git submodule paths (relative to COMPONENT_PATH) used …
208 Optional Component-Specific Variables
213 - ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to the component directory, whi…
214 - ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when compiling the component's source …
215 - ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the component directory, which will b…
216 - ``COMPONENT_OBJS``: Object files to compile. Default value is a .o file for each source file that…
217 - ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build directory, of any files that ar…
218 - ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These targets allow you to fully ove…
219 - ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component produces no built outpu…
220 - ``CFLAGS``: Flags passed to the C compiler. A default set of ``CFLAGS`` is defined based on proje…
221 - ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp and .S files). A default set …
222 - ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of ``CXXFLAGS`` is defined based on…
223 - ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker script generation fu…
227 apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
232 -----------------------
238 …ponent KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf.
243 ------------------------
245 ESP-IDF build systems adds the following C preprocessor definitions on the command line:
247 - ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
248 - ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details.
251 -----------------------
256 - "make" is always run from the project directory and the project makefile, typically named Makefil…
257 - The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project vari…
258 - The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Ma…
259 - ``project.mk`` fills in default project-level make variables and includes make variables from the…
260 - ``project.mk`` builds a list of components to build, based on the default component directories o…
261 - Each component can set some `optional project-wide component variables`_. These are included via …
262 - `Makefile.projbuild` files from components are included into the make process, to add extra targe…
263 - By default, the project makefile also generates top-level build & clean targets for each componen…
264 - In order to compile each component, a recursive make is performed for the component makefile.
271 - Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper …
272 - This component wrapper includes all component ``Makefile.componentbuild`` files, making any recip…
273 - The ``component_wrapper.mk`` is called with the current directory set to the component build dire…
274 - ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `co…
275 - If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build a…
276 - The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is e…
278 …ugh the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf.
280 Running Make Non-Interactively
281 ------------------------------
283 When running ``make`` in a situation where you don't want interactive prompts (for example: inside …
287 - Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``.
288 - If the project configuration is missing new configuration items (from new components or esp-idf u…
289 - If the build system needs to invoke ``menuconfig``, an error is printed and the build fails.
291 .. _make-size:
294 ---------------------
296 - ``make app``, ``make bootloader``, ``make partition table`` can be used to build only the app, bo…
297 - ``make erase_flash`` and ``make erase_otadata`` will use esptool.py to erase the entire flash chi…
298 - ``make size`` prints some size information about the app. ``make size-components`` and ``make siz…
301 --------------------------
303 Some tips for debugging the esp-idf build system:
305 - Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause mak…
306 - Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same…
307 - Running ``make --trace`` (possibly in addition to one of the above arguments) will print out ever…
308 - Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile.
312 .. _warn-undefined-variables-legacy:
324 -------------------------------
329 For components that have build requirements that must be evaluated in the top-level project make pa…
333 ``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build featu…
335 …- such as adding include directories to the project, or LDFLAGS to the final linking step. These v…
337 Take care when setting variables or targets in this file. As the values are included into the top-l…
342 …nclude configuration options at the top-level of menuconfig, rather than inside the "Component Con…
351 Configuration-Only Components
359 ---------------------------
368 By default, sub-directories are ignored. If your project has sources in sub-directories
374 This will compile all source files in the src1/ and src2/ sub-directories instead.
381 …e compiled unconditionally. It is possible to circumvent that logic and hard-code the objects to b…
393 …iles depending on the options selected in ``make menuconfig``. For this, ESP-IDF has the compile_o…
433 $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
434 $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
439 …d: ESP-IDF uses the default Make policy of judging a variable which is empty or contains only whit…
455 bmp2h -i $^ -o $@
464 …the other component's ``COMPONENT_DEPENDS`` list to ensure that the components were built in-order.
469 …ome binary or text data that you'd like to make available to your component - but you don't want t…
475 …MPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string::
486 …xample :example_file:`protocols/http_server/file_serving/main/component.mk` - two files are loaded…
489 ------------------------
491 …-IDF has a feature called linker script generation that enables components to define where its cod…
496 ---------------------------------------
498 …another third-party component not originally intended to be compiled under this build system. In t…
502 …n using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to…
504 .. _esp-idf-template: https://github.com/espressif/esp-idf-template
508 .. _custom-sdkconfig-defaults-legacy:
511 -------------------------
513 …nfig configuration, but you do want to override some key values from the esp-idf defaults, it is p…
518 --------------------
522 …--flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 exa…
526 …ol.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset wri…
531 … all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list…