Relative include files

[cupcup]

This is a possible solution to

Including files from other locations

Good day all, I am somewhat obsessive compulsive and like to impart some structure to my coding directories. One thing I find difficult in Arduino is including files from other locations. For instance, I am currently developing several screens for a capacitive touch TFT display. These screens will be used by other parts of my Arduino code for user input or displaying status data. I would like to have the screens organized in a sub-folder of my project something like this... TheProject | --> …

#include statement with relative path

Hi! I like to keep my project files in one directory so I would like to avoid putting classes/librarys inside the Arduino folder. I tried using this syntax (Windows machine): #include "..\AxisCtrl\AxisCtrl.h" The folder "AxisCtrl" is in the parent directory of my "prj0009_CNCCtrl_v04.ino" main file. I also tried: #include "../AxisCtrl/AxisCtrl.h" But I always get prj0009_CNCCtrl_v04.cpp:6:34: error: ..\AxisCtrl\AxisCtrl.h: No such file or directory Is it even possible to include "loc…

#include library from upper directory

I have got a project with this directory structure: Hand_main -- Hand --- Hand.ino -- Test --- Test.ino -- src --- Finger ---- Finger.h ---- Finger.cpp I would like to include the Finger library in the Hand and Test scripts, but I can't work out how. I have tried #include "../src/Finger/Finger.h but that didn't work. I don't want to put the Finger library in the Arduino libraries folder, because I store the project on Github and it is handier if all the code is in the same directory…

These questions have already been closed so I can't answer them. Say the files have the following structure

    +--include
    |   +-- xxx.h
    |   +-- yyy.h
    +-- project1
    |   +-- project1.ino
    +-- project2
    |   +-- project2.ino

I wish to include xxx.h in both projects. A simple way, from the command line (windows) is

cd project1
mklink /d include ..\include

in the code
#include "include/xxx.h"

If you only want one file, you could do something like this

cd project2
mklink xxx.h ..\include\xxx.h

in the code
#include "xxx.h"

On Linux, this can be done with ln -s.

[sterretje]

Include files can be anywhere and you can use absolute paths if so desired. The problem is when you have a library with a .cpp file and a .h file.

The IDE will only compile .cpp files that are in certain directories.

[cupcup]

I've never ever gotten absolute or relative paths to work. It always says no such file or directory. With symbolic links within the project directory, the code just builds.

[gilshultz]

You can generate a batch file that will copy all of the pertinent files to the sketch folder and then launch the IDE. I have tried many times to solve that problem with the IDE. It works fine with the .h files, but it will compile the first .cpp file it finds with the same name. The only reliable solution was to put both the .h and .cpp files in the sketch directory. This becomes very important if you modify a library file and make a second copy. The include order also affects the search order. The IDE does a lot of nice things, but it is not perfect.

[cupcup]

What I am suggesting is instead of copying, make a symbolic link. That way, all the changes will be saved in the original library so you do not need to waste time copying files to and fro.

[b707]

@cupcup

If you only want one file, you could do something like this

cd project2
mklink xxx.h ..\include\xxx.h

in the code
#include "xxx.h"

I don't think this will work with relative paths.
Arduino IDE doesn't compile your sketch in the folder where the .ino file is located. Before starting the build, IDE copies the entire folder to the temp directory, and all builds happen there, so when building, your path ..\include\xxx.h will point to a completely different location than the .h file.

[b707]

@cupcup

On Linux, this can be done with ln -s.

will not work during the compilation.

Just tested with ln -s on linux - surprisingly, it works.

[kenb4]

One important detail is that the sources are generated and copied into a temp directory, and the compile is done there. The .ino file is converted to an .ino.cpp. (If you have more than one .ino, they are glued together to generate a single .cpp) Then the "eligble" source files in the sketch directory tree are copied. This includes the main translation units -- .cpp, .c, .cc, .cxx, .S -- and supported headers like .h and .hpp. One hint might be whether the IDE allows creating such a file in a new tab, or complains "is not a valid extension".

Even though all the sources in the sketch's tree are copied, only those in the

• sketch directory
  • src/ subdirectory
    • entire tree under that

are compiled. For example, if you have lib2/ as a sibling of src/, those files would be copied, so #include "lib2/whatever.h" would work, but whatever.cpp there would not be compiled. If that was needed, the sketch would fail to link -- in the C compiler sense.

A file link (hard link, symlink) should work because that is effectively a file in the sketch, and its content will be copied over. But it won't work when

• the #include relatively navigates up back into the sketchbook, since the parent of the temp directory is another temp directory, and your files aren't there
• running Windows and the temp directory is on a different drive than the sketchbook and the absolute path does not include the drive letter

If you enable Show verbose output during compile, it shows the temp directory in the line right after "Compiling sketch". The command is essentially: "compile .ino.cpp -o .o" to compile the generated .ino.cpp into the named object file. If you scroll all the way to the end, the temp path is there for both. For example on Windows, with extra word wrap added

"C:\\Users\\kenb4\\AppData\\Local\\arduino\\sketches
   \\EC26961FCABBA78A5928D7411C66733B
   \\sketch\\relative_include.ino.cpp"
-o 
"C:\\Users\\kenb4\\AppData\\Local\\arduino\\sketches
   \\EC26961FCABBA78A5928D7411C66733B
   \\sketch\\relative_include.ino.cpp.o"

You can compare files put in the sketch directory by checking that temp directory (<random>/sketch) after a build to see what actually got copied over.

[cupcup]

Once you have done the mklink command, the file will appear as a normal file in the directory. For example

U:\arduino\project1>mklink xxx.h ..\include\xxx.h
symbolic link created for xxx.h <<===>> ..\include\xxx.h

U:\arduino\project1>dir
 Volume in drive U has no label.
 Volume Serial Number is CA18-63CF

 Directory of U:\arduino\project1

20/12/2025  09:52    <DIR>          .
20/12/2025  09:52    <DIR>          ..
20/12/2025  09:51                 4 project1.ino
20/12/2025  09:52    <SYMLINK>      xxx.h [..\include\xxx.h]
               2 File(s)              4 bytes
               2 Dir(s)  102,170,308,608 bytes free

U:\arduino\project1>

You can then compile your .ino file with #include "xxx.h". Like Linux, when you modify the .h file, the original in the include directory gets modified.

[b707]

@cupcup

the file will appear as a normal file in the directory.

This is an incorrect conclusion. Your example shown that it is not the case:

@cupcup

20/12/2025 09:52 <SYMLINK> xxx.h [..\include\xxx.h]

The symlink includes a relative path.

The reason this still works is apparently because IDE, when copying your sketch to a separate location for building, copies all nested files and directories, dereferencing symlinks.