I'm new to Arduino/C development (coming from a JavaScript/Ruby environment), but I was wondering if it was possible to include a library from a custom folder within a sketch?

So this is my situation;

project.ino
libs/
MyNewLib/
MyNewLib.h
MyNewLib.ccp


Now my question is: how can I include my custom library? I've tried several variations on this;

# project.ino

#include <libs/MyNewLib/MyNewLib.h>
#include "libs/MyNewLib/MyNewLib.h"
#include <./libs/MyNewLib/MyNewLib.h>
#include "./libs/MyNewLib/MyNewLib.h"


But none of them works. Can anyone tell me if this is possible? I've looked into this question around the web, but I can't find any satisfying answer. Hopefully you guys can help.

Cheers.

UPDATE

I'm aware you can put your libraries in your global libraries folder, but I want them in my local project folder. I want to share them through git with my team.

• Please read my question again @Tyson. I'm aware of the global libraries solution, but I want them inside my project. Feb 15 '15 at 14:27
• You have to first tell the IDE where to find the library (see prior link) then within your sketch you call the library.  #include <LibraryName.h> AFAIK you can not combine the two into a single include specifying the path/to/library/ which is what I guess you're asking. Feb 15 '15 at 14:52
• Okay, so I can't include files from subfolders.. That's a pity.. Feb 15 '15 at 15:12
• Windows Symlinks Feb 15 '15 at 15:16
• You are stumbling on the fact that the Arduino tools are fundamentally incompatible with real, mature or professional software practices. They'll probably also incessantly complain about that .git directory, though it won't actually break the build. Nov 5 '16 at 16:35

Okay, here is how it works, and I checked it to make sure.

Sure you can use hard paths, but every programmer hates using hard paths. They are not portable at all, and they lock your program in place. You use soft or hard links to the files in the project (look up the man pages on "ln"). But,... talk about ugly! So the question is how to do it "correctly"? The key is learning with what parameters and in what path the C/C++ compiler runs.

You will find the conclusion is NOT intuitive at all. Cutting to the chase: relative paths don't work correctly. Now, why?

But first, let me explain why anyone would want to place program files outside the project directory. Programmers like writing program classes, structs, methods, functions, macros, etc., once. As soon as the programmer solidifies the program fragment, he/she wants to put the files in a common tree and move on. Every program thereafter could use that private library. Also, by having the files in a central place, you won't have multiple copies and versions of each. One private library for many private programs.

As of 1.6.13 (Teensy does not yet support 1.8.*), relative includes start from the library, not your directory. It appears that the ano-to-C filter (remember that Arduino does a "conversion" to the target then calls the C/C++ compiler) starts where you installed your Arduino tree. In my case, I installed in "~/bin/arduino". Teensy's home is "./hardware/teensy". The entire home path for the libraries is "~/bin/arduino/hardware/teensy/avr/libraries" where you will find all the support program trees.

In a source file, the '#include "test.hpp"' statement correctly picks the file from your current directory. HOWEVER, if you use '#include "../test.hpp",' the include path does not start in your project directory. Instead it starts in "./libraries"! So the resulting path is:

#include "../test.hpp" ==> ./arduino/hardware/teensy/avr/libraries/test.hpp

In conclusion there is no clean way of making your own tree of tools in a nearby directory. The only course is to commit your work in the Arduino library and be aware of those rules as well.

I am just back to using the arduino after some time away and am somewhat bewildered by similar issues and confused by different info from different sites and for different versions of the ide.

What I have found is that if you have a sketch in a directory, then shut down the Ide you can drop .h, .cpp... files in the directory and the ide, when restarted, will open them with the sketch.

Include them by using simple quotes on the file names, no path, no angle brackets.

I am sure this is only part of the full answer, but it has gotten me started.

As far as I know, you can include your libraries from a custom location by using their absolute path.

Since absolute paths could be boring from a code-portability point of view, you could define some macros to get the absolute path from a given relative one. In this way, you would just have to fix the 'project root' path when passing from a device to another.

Define your project's root folder :

    #define PROJECT_ROOT C:\path\to\your\project\folder


Define a relative-to-absolute macro 'transformation' :

    #define TO_STRING(s) #s
#define ABSOLUTE_PATH(root, relative_path) TO_STRING(root\relative_path)
#define RELATIVE_PATH(library) ABSOLUTE_PATH(PROJECT_ROOT, library)


Include your files using the relative path :

    #include RELATIVE_PATH(some\file\relative\path.h)
#include RELATIVE_PATH(another\file\relative\path.h)


I hope it will be useful.

The Arduino plugin for Visual Studio supports local libraries you can find the plugin here

I recently tested this local library structure. It works with:

#include "libs/MyNewLib/MyNewLib.h"


The Arduino IDE 1.6.7 build pre-processing will even pick up the source code for the library.

Cheers!

• Must be new in 1.6.7 Feb 24 '16 at 2:25
• It seems that indeed the newer versions are more flexible and you can include libraries in relative paths. However I still ran into problems when the included files also include other files relative to their location. Dec 2 '16 at 11:07
• Hmm the include problems I just wrote about are not related to paths. It appears that the Arduino IDE does not handle *.ipp files well. See this arduino forum thread Dec 2 '16 at 12:51
• Doesn't work for me in 1.8.1 on Windows. Feb 23 '17 at 5:53

The simplest way I've found to do this is store the libraries in your local sketch directory and create a symbolic link in the [HOME]/Arduino/libraries directory. Then you can check them in to Git easily with your sketch/project and Arduino's still happy because the libraries are accessible in the global folder.

Maybe even create an install script that creates these links automatically and check that into Git too.

Another really bad fix - create a file called libraries.cpp, which contains:

// force the linker to build the libraries
#include "libraries/LIB1/src/FILE1.cpp"
#include "libraries/LIB1/src/FILE2.cpp"
#include "libraries/LIB2/src/FILE1.cpp"


Of course, this only works if the library does not itself contain any includes...