Library Dependency Finder is a core part of PlatformIO Build System that operates with the C/C++ source files and looks for #include ...
directives to know what header directories to include for the compiler.
In spite of the fact that Library Dependency Finder is written in pure Python, it evaluates ldf_c_cond_syntax
(#ifdef
, if
, defined
, else
, and elif
) without calling gcc -E
. This approach allows to significantly reduce the total compilation time. See ldf_mode
for more details.
Library Dependency Finder can be configured from projectconf
:
../projectconf/sections/env/options/library/index
There are different storages where Library Dependency Finder looks for libraries. These storages (folders) have priority and LDF operates in the next order:
projectconf_pio_lib_dir
- own/private library storage per projectprojectconf_pio_libdeps_dir
- project dependency storage used bylibrarymanager
- "
projectconf_pio_core_dir
/lib" - global storage per all projects. - Library storages built into frameworks, SDKs.
Library Dependency Finder starts work from analyzing source files of the project (projectconf_pio_src_dir
) and can work in the next modes:
off
"Manual mode", does not process source files of a project and dependencies. Builds only the libraries that are specified in manifests (
library_json
,module.json
) or usingprojectconf_lib_deps
option.chain
[DEFAULT] Parses ALL C/C++ source files of the project and follows only by nested includes (
#include ...
, chain...) from the libraries. It also parses C, CC, CPP files from libraries which have the same name as included header file. Does not evaluateldf_c_cond_syntax
.deep
Parses ALL C/C++ source files of the project and parses ALL C/C++ source files of the each found dependency (recursively). Does not evaluate
ldf_c_cond_syntax
.chain+
The same behavior as for the
chain
but evaluatesldf_c_cond_syntax
.deep+
The same behavior as for the
deep
but evaluatesldf_c_cond_syntax
.
The mode can be changed using projectconf_lib_ldf_mode
option in projectconf
. Default value is set to chain
.
Note
Once a library is picked by the LDF for the build process, all source files according to its manifest file will be built.
Note
Usually, when the LDF appears to fail to identify a dependency of a library, it is because the dependency is only referenced from a library source file, and not a library header file (see example below). In this case, it is necessary to either explicitly reference the dependency from the project source or projectconf
(projectconf_lib_deps
option), or change the LDF mode to "deep" (not generally recommended).
A difference between chain/chain+
and deep/deep+
modes. For example, there are 2 libraries:
- Library
Foo
with files:Foo/foo.h
Foo/foo.cpp
Foo/extra.cpp
- Library
Bar
with files:Bar/bar.h
Bar/bar.cpp
- Case 1
lib_ldf_mode = chain
Foo/foo.h
depends on theBar
library (contains#include <bar.h>
)#include <foo.h>
is located in one of the project source filesHere the nested includes (
project file > foo.h > bar.h
) and LDF will find both librariesFoo
andBar
.
- Case 2
lib_ldf_mode = chain
Foo/extra.cpp
depends on theBar
library (contains#include <bar.h>
)#include <foo.h>
is located in one of the project source filesIn this case, LDF will not find the
Bar
library because it doesn't know about the CPP file (Foo/extra.cpp
).
- Case 3
lib_ldf_mode = deep
Foo/extra.cpp
depends onBar
library (contains#include <bar.h>
)#include <foo.h>
is located in one of the project source filesFirstly, LDF finds the
Foo
library, then it parses all sources from theFoo
library and findsFoo/extra.cpp
that depends on#include <bar.h>
. Secondly, it will parse all sources from theBar
library. This operation continues until all dependencies will not be parsed.
Compatibility mode allows one to control strictness of Library Dependency Finder. If library contains one of manifest file (library_json
, library.properties
, module.json
), then LDF check compatibility of this library with real build environment. Available compatibility modes:
off
Does not check for compatibility (is not recommended)
soft
[DEFAULT] Checks for the compatibility with
projectconf_env_framework
from build environmentstrict
Checks for the compatibility with
projectconf_env_framework
andprojectconf_env_platform
from build environment.
This mode can be changed using projectconf_lib_compat_mode
option in projectconf
. Default value is set to soft
.
In spite of the fact that Library Dependency Finder is written in pure Python, it evaluates C/C++ Preprocessor conditional syntax (#ifdef
, if
, defined
, else
, and elif
) without calling gcc -E
. For example,
platformio.ini
[env:myenv]
lib_ldf_mode = chain+
build_flags = -D MY_PROJECT_VERSION=13
mylib.h
#ifdef MY_PROJECT_VERSION
// include common file for the project
#include "my_common.h"
#endif
#if MY_PROJECT_VERSION < 10
// this include will be ignored because does not satisfy condition above
#include "my_old.h"
#endif