Include header file from /include folder via build_flags


I am quite new to PlatformIO and a beginner/basic programmer and currently writing an Arduino - project.
Even after reaseaching i could not find a understandable or working solution for my problem.

I have a main.cpp file and want to include a header file into it. --> Therefore i placed it (header.h and header.cpp) into the /include folder of my project (since it is made to put header-files there) and tried to include it via #include “header.h” in the main.cpp file.
When building, I get the error “undefined reference to” my fuction in the header.h file.

After reaseaching i found out, that the include folder is not gobal and my main file cannot “see” the header but with the build-option “build_flags” in the platformio.ini file, i can include the folder.

But i simply cannot get it to work, since i don’t know what to type exactly.
The syntax should look something like this as far i found out.

[something here]
build_flags = -I include

What do i put in the brackets [] ?
Do i put in a path instead of include? Is this then computer specific?

Thanks for the help in advance.

1 Like

Don’t put neither main.cpp nor header.cpp into include, put them into src. Only headerfiles belong into include. Then you don’t need

build_flags = -I include

Please see also Use headers give me an error


Files in include/ will not be compiled. Only place header .h files there, not implementation (.cpp/.c) files there, but in source.

Having the declaration of a function but not the implementation (stemming from the .cpp file), will give you

so that’s right from the compiler’s side.

Files in src/ are also automatically in the include path so you can also just put all files into src/.

Or, if the code is fully self contained and indepentend from everything else, consider creating a library, aka creating a new folder in the lib/ folder of the project, say myLib and putting the source code files (.h, .cpp, …) in that folder.


Thank you very much.
I will simply store it in the /src than.

Have a nice day!

-Marked it as solution, that means topic closed for me.

Best wishes!

Just to clarify, what do you mean “files in include will not be compiled”? Header files are compiled indirectly through inclusion. If -I include is used, header files will be included and compiled, will they not?

.c/.cpp files are turned by the compiler into object files (.o). Compilation is done per-compilation unit, and a compilation unit is a .c/.cpp file, not a header file. Of course, the .c/.cpp file can use header files, aka a copy-paste help by the compiler, but the header files are themselves not the originating file for compilation, only used indirectly.

This topic talks about that in PlatformIO projects, the include/ folder is not compiled, files in src/ (and lib/ etc.) are. So if you have a project with

- include
  | - MyFunctions.h
  | - MyFunctions.cpp
- src
  | - main.cpp

where MyFunctions.h declares a function implemented by the MyFunctions.cpp file, that will fail at the linking stage. The compiler first turns main.cpp into main.o, and main.cpp file includes MyFunctions.h. This is no problem, the header is found and in the include path (-I<path>) automatically.

However, when the final ELF file is built / linked from all object files created in the project, it will give you an undefined referece to.. error in regards to the function you want to call in MyFunctions.h – since MyFunctions.cpp is in the include/ folder, it will not be compiled, so there is no MyFunctions.o where the implementation (instruction code) is stored for the function declared in the MyFunctions.h file. The solution is to move MyFunctions.cpp into src/.

This does not apply to header-only librares, since they put all the implementation directly in the header fiel and there is no accompanying .cpp file. Then it’s valid to only place the file into include/.

1 Like

Another post suggested /include is added by default. And it is. And, yes, I see the clarification. It hadn’t crossed my mind that c files would be put in /include. But them not being compiled surprises me a little. Scons? I must admit to having a hell of a time trying to make sense of the somewhat disjoint stm32 pio “bridge” in the day of stm32cubeide. Somewhat worryingly the latest stm32cubemx says exporting c h pairs will be discontinued. I’ll keep battling on.