How to use the proper #include statement /path?

[domify80]

I have a question with regards #include statements (and it's path) in a sketch.

Scenario:
I have the following directory structure:

In the sketch project-03/libtest.ino, I want to load to a header file (and the library source code) of a customized library (or even my own library) (just for test purposes).
My question is, how should the include statement look like to access the header file (and library source in directory: projects/custom-libraries/custom/header-01.h

With other works, how is the IDE handling during an include the path to another directory from the current project folder?

Should it be something like #include “../custom-libraries/custom-01/header-01.h”?

I tested already the menu option: Sketch → Add File. But this is adding the file(s) to the project folder. Therefore there is a duplication of code, which I do not want.

I want to maintain my customized library location and when needed, referring to it with the #include statement.

Is that even possible in the IDE?

Any suggestion is much appreciated.

Thanks all

And b.t.w., I’m talking about Linux, not Windows.

[ptillisch]

Hi @domify80.

@domify80

I want to load to a header file (and the library source code)

Typically an #include directive for a library header file in an Arduino sketch program has two effects:

• Adds the content of the specified file into the program.
• Causes the source files of the library that contains the specified file to be compiled.

You can specify any path you like in an #include directive. However, the latter of those two effects only occurs when no path is specified in the #include directive.

For example, if you have a library like this installed:

<sketchbook>/
├── libraries/
│   ├── custom-01/
│   │   ├── source-01.cpp
│   │   ├── header-01.h
│   │   ...
│   ...
...

and this in your sketch program:

#include "header-01.h"

Then source-01.cpp will be compiled.

However, if you instead did something like this:

#include "/home/myusername/Arduino/libraries/custom-01/header-01.h"

Then source-01.cpp will not be compiled.

@domify80

Should it be something like #include “../custom-libraries/custom-01/header-01.h”?

Relative paths outside the sketch folder won't work as expected in the code of the sketch files. The reason is the sketch is copied to a temporary folder before being compiled. The relative path that is correct for the real location of the sketch will not be correct for the location in the temporary build folder.

@domify80

I want to maintain my customized library location

You should put the customized library in the libraries subfolder of the sketchbook folder. I you do that, you can use the library in your sketches as usual.

If there is some reason why you don't want to place the library in the standard location, please provide a detailed explanation. That information will allow use to effectively advise you on how you can accomplish your goal.

[kenb4]

Considering that

• a sketch is a directory with a same-name .ino file
• when you compile a sketch, that .ino is converted to an .ino.cpp file (so it is a regular C++ source file)
• all the sources in the sketch directory are compiled
  • and in the sketch's src/ subdirectory, if any
    • and in the entire tree under that, if any
• the sources are copied to a temp directory first

You can then have a directory structure like

• custom-libraries/ (does not have to a sibling of sketchbook)
  • custom-pi/
    • custom-pi.cpp (can have any sources in here)
    • custom-pi.h (no requirement that the name matches its directory)
• <sketchbook>
  • libraries/
  • one/
    • one.ino
    • src/
      • custom-pi/
        • custom-pi.cpp
        • custom-pi.h
  • two_digit/
    • eleven/
      • eleven.ino
    • ten/
      • ten.ino
      • src/
        • custom-pi/
          • custom-pi.cpp
          • custom=pi.h

by adding a symlink to the custom library's directory from each sketch's src/ subdirectory; e.g.

two_digit/ten/src$ ln -s ~/custom-libraries/custom-pi

Note this requires that the sketch has been saved in the sketchbook; it won't work for a new/temp sketch. Then the include in the .ino (or any file in the sketch root) would be

#include "src/custom-pi/custom-pi.h"

which is a little long, but it works.

In the Preferences, enable Show files inside sketches to see the source tree in the Sketchbook.

[gilhad]

Arduino was made to make easy parts extra easy at the price of hard parts be extra hard.

When you are beginer, it is nice to scratch a sketch and be done and see it does something somehow.

I bought the larger kit many ears before and started by doing all the examples inside, so I get fast start and learned a lot fast without all the hurdles the wiring hide from me. It was really good.

I later start do larger and larger project and first I went out from IDE to get some better editor (VIM in my case) and some other tools I wanted (GIT - I cannot recomend it enought, it is really must have for any project), and some years later I started to use Arduino-CLI and another CLI based tools, my projects became .cpp (with #include “Arduino.h”) instead of .ino, then later I left even the #include “Arduino.h” after me and now I use make with Makefile and I use lot of assembler (some thing are really faster there and some are even easier - and some not)

I still sometime use Arduino IDE, mainly for fast test like blink, or some library for some HW or so, but it is just one of many tools, with its pluses and minuses.

[domify80]

First of all, thanks you for the detailed response.

@ptillisch

If there is some reason why you don't want to place the library in the standard location, please provide a detailed explanation. That information willPreference allow use to effectively advise you on how you can accomplish your goal.

Here is the reason why I want to use a location other than the default libraries directory:

I have already a ‘standard” library (ILI9488) in the default libraries directory.

Currently I’m using a modified version of this library for a few different projects (at the same time due to different mcu’s). I don’t want to interfere with the ‘standard’ version of the library (keep it unchanged).
If I would store the modified version in the library directory, I will have a name conflict.

In addition, I don’t want to change names of include files during the test phase of the modified library.

That’s why my first thought was to use a relative path in the #include statement. But as you’ve explained that doesn’t applies to the library code file (cpp).

(Why even copying everything to a temporary location during compilation?)

I think here also would help if the IDE would utilize an include-path environment var or at least a Preference property (like the sketch book folder).

Perhaps I’m on the absolute wrong path of thoughts on this matter, but that’s where I am right now.

Appreciate any suggestion or correction.

Thanks

[domify80]

That seems to be a smart solution.

I will take closer look and perhaps give it a try.

TY

[domify80]

@gilhad

now I use make with Makefile

That what I’m used to use during my active life as developer and I liked it.
Now I’m retired and want to have it easy. LOL

Cheers

[ptillisch]

Thanks for the clarification.

@domify80

I think here also would help if the IDE would utilize an include-path environment var

Arduino IDE is designed to be friendly to new users through a carefully curated user interface that only offers features that will be useful to a significant portion of the user base. Although you are completely reasonable to want this feature for your own use case, it would be of no interest to 99.9% of users.

We also offer an alternative development tool that is specifically targeted to meet the needs of advanced users: Arduino CLI. You can specify arbitrary additional libraries paths when compiling sketches using Arduino CLI:

https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_compile/#options

--libraries strings   Path to a collection of libraries. Can be used multiple times or entries can be comma separated.
--library strings     Path to a single library’s root folder. Can be used multiple times or entries can be comma separated.

This approach would allow you to use the standard approach with your #include directives, only specifying the header filename and allowing Arduino CLI to discover the library as usual.

But if you (understandably) prefer to use Arduino IDE, the solution offered by @kenb4 will be an excellent one.

[domify80]

I understand your point.

Perhaps I will look into the solution via CLI, in particular I'm using KATE as code editor very often and I could compile from inside the editor. That may also enable an utilization of the Make tool.

Overall, this thread is a nice piece of learning.

Thanks for that to all contributors of this thread.

[ptillisch]

@domify80

I'm using KATE as code editor very often and I could compile from inside the editor. That may also enable an utilization of the Make tool.

Exactly! Arduino CLI is perfectly suited for these use cases.

[domify80]

I implemented the logic with the symbolic-link to a custom-library-directory as suggested.

Initial test (compile) was successful.

Thanks for the ‘slick’ solution.