VSCode/PlatformIO unable to locate library header in non-default locations

I am having issues when keeping libraries in a location that is not the default for VSCode/PlatformIO. I have built a minimal VS Code workspace in an attempt to better understand the problem and would appreciate any comments you may have.

As I understand it, VSCode/PlatformIO, given an #include<myfile.h> will search for that file based upon the locations in the current workspace’s “c_cpp_properties.json” file. The VSCode Intellisense also functions by using the locations of the “.h” files given in “c_cpp_properties.json”. Therefore, if the “.h” header files are all present in a folder that is represented in the “c_cpp_properties.json” file, they should be able to be found.

Given my minimal test project of:

#include <Arduino.h>
#include <Keypad.h> /An arbitrary library for testing/

void setup() {
// put your setup code here, to run once:

void loop() {
// put your main code here, to run repeatedly:

…and placing the Keypad library, which contains the required Keypad.h files, into unique location other than the default platformIO libraries location, and updating c_cpp_properties.json file appropriately, I would expect the compilation to succeed. It fails with

src\main.cpp:2:20: fatal error: Keypad.h: No such file or directory

Here is a section of the c_cpp_properties.json file, with the modifications I made for the addition of the Keypad library…

“includePath”: [
…several lines deleted for brevity…


“browse”: {
“limitSymbolsToIncludedHeaders”: true,
“path”: [
…several lines deleted for brevity…

Adding the absolute path “Z:/CodeArchive/ArduinoLibraries/Keypad/src” from the Keypad library folder to the list of includePath(s) in c_cpp_properties.json cures the “squiggle” over the #include<Keypad.h> line in the IDE, however the compilation still fails to find the file.

Adding the absolute path to the Browse section of c_cpp_Properties.json has no effect on the outcome.

However, If I use an absolute path in the #include<>, such as #include “Z:/CodeArchive/ArduinoLibraries/Keypad/src/Keypad.h” then the compilation will succeed without errors.

Am I missing another setting that must be configured to point to my libraries when they are placed in a non-default location?

There are two layers involved:

  1. PIO build system: If not properly configured, your software cannot be successfully built.
  2. Intellisense: If not properly configured, red squiggly lines are displayed (mainly on the first include directive of the file).

I don’t understand where you are having issues:

  • Are you unable to build the software? If so, what’s the error message in the Terminal view?
  • Or can you build the software but still get red squiggly line?

Can you also show the platformio.ini file. It’s the only relevant configuration file for everything.

Modifying c_cpp_properties.json isn’t a good idea. It will be overwritten by PlatformIO. That’s why it has a warning at the top.

Exactly. Have you used the lib_extra_dirs directive to include your external folder with Arduino libraries?

Also a verbose compilation log is needed (pio run -v or “Verbose Build”), as this will show what dependencies PIO knows of and where it thinks these are located.

I will summarize:

The minimal project fails to compile is my library is not in a default location. I wish it to be in a custom location.
Altering the contents of C_cpp_properties.json (in the project’s .vscode directory) allows intellisense to find the library, but the compile still fails. As you (manelbl) mentioned, this seems in keeping with your discriptions of the “two layers”–PIO Build system and Intellisense.

To answer your questions–yes, I am unable to build the software because I am unable to determine where to “tell” the vscode/PIO system where to “find” my libraries.

As requested, here is the contents of my project’s platformio.ini file:

[env:sparkfun_promicro16] platform = atmelavr board = sparkfun_promicro16 framework = arduino

It is as set up by the system at my project’s creation with no manual changes by myself.

It sounds like you (and maxerhardt) may be implying to me that the correct place to set the search for libraries is in the project’s platformio.ini file and not the project’s c_cpp_properties.json file as I was doing. This is an important distinction of which I was unaware. I am reviewing the library dependency docs now…

Should the platformio.ini file be modified by hand or, like c_cpp_properties.json will it by modified by something else?

Always only modify the platformio.ini. c_cpp_properties.json is auto-regenerated. If building works but Intellisense does not, rebuild the Intellisense with the appropriate task (docs)

Thanks you maxgerhardt. It also appears that path slashes must be in a forward manner, even under windowsOS, and quotes are problematic.

Keeping that in mind, while using the lib_extra_dirs specification in platformio.ini, what is the delimiter between multiple paths? I’ve seen examples that show each item on a different line, but it can’t be a space if paths with spaces are allowed…?

As seen in e.g. other parts of the documentation, either one-per-line or comma+space. For paths which contain both a comma and a space you must use the second option.