Issues with the dependencies in library.json

Is it possible to specify a local folder or a symlink in the dependencies of library.json?

The documentation doesn’t mention it, but I’ve made a few tests and it seems it almost works:

Symlink Test 1

  "dependencies": {
    "lib1xxx": "symlink://../Core"

gets you this error:

Library Manager: Installing symlink://../Core
PackageException: Can not create a symbolic link for `../Core`, not a directory

EDIT : as discussed below, this error is due to the fact that //../Core is relative to the current project, not to the library folder. Thanks @sivar2311.

Symlink Test 2

  "dependencies": {
    "lib1xxx": "symlink:../Core"

seems to work:

Library Manager: Installing symlink:../Core

but in fact it doesn’t, as no symlink is actually created in libdeps (so the project doesn’t compile).

Local Folder

The same things happen when trying with a local folder instead of a symlink.

There’s something I’m probably missing here. I’ve tried adding an external repo and it doesn’t work either. Not sure if the two problems are related, but I prefer to post here in case there’s something wrong with my setup.

  "dependencies": {
    "SparkFun_BMI270": ""

In that case, the SparkFun_BMI270 folder is created in libdeps, but the compiler doesn’t find the library:

C:/Users/.../ImuBMI270.h:4:10: fatal error: SparkFun_BMI270_Arduino_Library.h: No such file or directory

However, if I add the dependency in platformio.ini, like this, it compiles without a glitch:

lib_deps =

I don’t know your usecase, but maybe this will help you:

Thanks @sivar2311.

A key element in your post is: “The use of relative paths is possible. However, these are relative to the current project!”

It explains why the above “Symlink Test 1” fails, as ../Core is relative to the library folder, not to the project folder.

Remaining questions:

  • Why does “Symlink Test 2” fail?
  • Why using an external repo fails?

Another remaining question (at least for me)

  • What’s the usecase for this?


Having a library dependent on other libraries is very useful. Right now, as far as I can tell, it’s only possible if those dependent libraries are either in the PlatformIO registry or accessed through a project-related path (which is very painful, as libraries are often used for several projects that can be anywhere on your hard drive). I’ve no tried with absolute paths, but it’s also painful.

You can also use http links like to a github repo.

It seems you can’t, see the second post of this thread.

Sure it works!

See example library lib_test/library.json at main · sivar2311/lib_test · GitHub

Create a project (ESP32)
Add to platformio.ini: lib_deps =

The library itself and all dependencies and sub-dependencies are installed automatically:

  • lib_test
  • ESPAsyncWebServer
  • AsyncTCP

Thanks a lot for this example, which has helped me find refine the issue:

  1. Create a sample project
  2. Add to platformio.ini: lib_deps =
  3. In the sample project, don’t include lib_test.h

You’ll get the following compile error:

In file included from .pio/libdeps/m5StickCPlus2_debugNoBle/lib_test/src/lib_test.cpp:1:
.pio/libdeps/m5StickCPlus2_debugNoBle/lib_test/src/lib_test.h:3:10: fatal error: ESPAsyncWebServer.h: No such file or directory

In your simple example, it feels strange not to include the header file. But it’s actually very common in real life: if a library has many header files, only one of them actually depending on an external library, you still want to be able to include the other ones.

Yeah, that’s a strange issue caused by the ESPAsyncWebServer library.
If it is in the lib_deps (directly, or indirectly as a dependency) the “ESPAsyncWebServer.h” must be included somewhere.

It should also only serve as an illustration. I have not created a complete test project.

It was just to illustrate that github repositories can be used as dependencies. Which seems to have worked for you.

Summary of the remaining two issues:

Issue when library.json contains a dependency to an external repo

If you put this in a library.json file:

  "dependencies": {
    "SparkFun_BMI270": ""

and file ImuBMI270.cpp of your library includes SparkFun_BMI270_Arduino_Library.h,

but your project never includes directly SparkFun_BMI270_Arduino_Library.h,

then you will get a compile error:

C:/Users/.../ImuBMI270.cpp:4:10: fatal error: SparkFun_BMI270_Arduino_Library.h: No such file or directory

The library is actually loaded and built, but the include path is not found.

I think this is a bug and I will file an issue with PlatformIO.

A workaround is to add this in your platformio.ini file:

lib_ldf_mode = deep

but if I understand the Library Dependency Finder manual correctly, it shouldn’t be required.

Silent failure when library.json contains a wrong dependency path

If you put this in a library.json file:

  "dependencies": {
    "nonexistent_lib_1": "symlink:../hfzehfzeiohize",
    "nonexistent_lib_2": "file:../hrfiohgeuibz"

PlatformIO will happily tell you:

Library Manager: Installing symlink:../hfzehfzeiohize
Library Manager: Installing file:../hrfiohgeuibz

even though none of those paths exist. This makes tracking path issues painful.

And remember

In library.json files, the use of relative paths is possible, but are relative to the current project, not to the library folder (thanks @sivar2311).

I would say that you have the wrong view of the first open issue.

The cause of the issue lies in the library!
But PlatformIO offers you the possibility to solve this issue with the LDF.

The library dependencies work perfectly.

In general, I do not yet understand what problem you are trying to solve. Do you want to use the library dependencies with local libraries? Please enlighten me.

For those landing here:

  • The first issue (bad include path with library dependency) has been fixed by the PlatformIO team. As of today, the fix is available in the dev branch only. You can install it by running pio upgrade --dev in a VSCode terminal (if you get an error message, follow the instructions).

  • The second issue (silent failure when wrong dependency) has been filed. Not sure when/if it will be fixed, as it is not too serious.