Add new libraries

Archive
1

I am trying to add several new libraries to the codebase. I however cannot figure out what I need to do to compile all the libraries I have added.

The libraries that I reference from within a .pde file (with #include <Library.h>) are being compiled. But when one of those libraries wants to include another library, it says it cannot find them.

To make it more clear, I have the following additional directories in Libraries:

  • AMW_Facade
    – AMW_Facade.h
    – AMW_Facade.cpp
  • AMW_Planner
    – Sequencer
    — AMW_Planner_Sequencer.h
    — AMW_Planner_Sequencer.cpp
    – Task_Planner
    — AMW_Task_Planner.h
    — AMW_Task_Planner.cpp

AMW_Facade.cpp contains the following includes:

#include "AMW_Facade.h" #include <AMW_Planner_Sequencer.h> #include <AMW_Task_Planner.h>

AMW_Facade.h is included in a .pde-file in ArduCopter.

When I compile, AMW_Facade.cpp is being compiled. It however gives the following error:
fatal error: AMW_Planner_Sequencer.h: No such file or directory

How do I add Libraries that are only used directly by other libraries, not by any of the .pde-files?

2

I eventually figured it out, though I do not know if I am correct on my assumptions. In case I am, I am posting my findings below for others to use as this was quite tricky to figure out and I did not find any other documentation on this.

This is actually a problem with 2 parts: including header-files and the locations of the source-files.

[size=150]Including Header-files[/size]

Include from other libraries

When including header files, you can only include header files in other libraries if the header file has the same name as the directory. (Note: file- and directory-names are case sensitive)
On top of that, it seems you must also include these header files in a sketch (.pde) file, even if you are only using them in libraries.

The notation does not matter. You can include files with “Header.h” or <Header.h>. However, the common theme in APM:Code seems to be to use <Header.h> if you are including a file from another library.

Example

includes.pde

#include <Library1.h>
#include <Library2.h>

Libraries
[ul]
[li]/libraries
[list][]/Library1
[list][][color=green]Library1.h[/color][/li][/ul][/:m]
[li]/Library2
[ul][][color=green]Library2.h[/color][/li]
[li][color=red]Library2b.h[/color][/li][/ul][/:m]
[li]/Library3
[ul][][color=red]Library3.h[/color][/li][/ul][/:m][/list:u][/:m][/list:u]
[color=green]File.h[/color]: Can be included in other Libraries
[color=red]File.h[/color]: Cannot be included in other Libraries

In this example, Library1.h can only include Library2.h. It cannot include Library2b.h because it has a different name from the directory it is in and it cannot include Library3.h because it is not included in a Sketch file.*
Library2.h can include Library1.h and Library2b.h (see next section) and Library2b.h can include Library1.h and Library2.h.
Library3.h can include Library1.h and Library2.h, but because it is not included itself, it won’t actually get used by the compiler.

If you need Library2b.h in Library1.h, include Library2b.h in Library2.h and then include Library2.h in Library1.h (see next section on including files in the same library).

*Note: It technically is possible to include both Library3.h and Library2b.h in Library1.h by using relative inclusion paths: (It again does not matter if you use <Header.h> or “Header.h”. However, with relative paths, the preferred way is to use “Header.h”.)

#include "../Library3/Library3.h" // Does not have to be included in a sketch-file #include "../Library2/Library2b.h" // Does not have to have the same name as directory
This is however not recommended as it makes your code much more dependent on the location of the header files of other libraries.

Note 2: While it is possible to include source files (.cpp) in the same fashion, including source files should be avoided at all times.

Include from same library
You can include any file within the same library. It is even possible to include files from sub/parent directories using relative paths (when using subdirectories, note that your source-file may not get compiled if it is also in the subdirectory, see next section).
These files do not have to be included in a sketch-file.

Again, notation does not matter. The preferred way is however to use “Header.h” to indicate relative paths.

Example
Libraries
[ul][li]/libraries
[list][]/Library1
[list][]/subDir
[list][]subLibrary.h[/li][/ul][/:m]
[li]Library1.h[/li]
[li]otherHeader.h[/li][/list:u][/:m][/list:u][/:m][/list:u]

Library1.h

#include "subDir/subLibrary.h" #include "otherHeader.h"

otherHeader.h

#include "subDir/subLibrary.h" #include "Library1.h"

subLibrary.h

#include "../Library1.h" #include "../otherHeader.h"

[size=150]Location of source-files[/size]
If you separate your headers and your source in separate files, you need to be careful to where you place your source files.
When making APM:Code, it automatically tries to list all the proper source files in libraries. It will compile any source files in the rootdirectory of libraries, but not in any subdirectories with the exception of the “utility” subdirectory.
The name of the sourcefile is not important. It does not need to have the same name as a headerfile or even implement a headerfile. It can even be in another Library altogether or even be implemented in a sketch-file.

Example
Libraries
[ul][li]/libraries
[list][]/Library1
[list][]/subDir1
[list][]sub.h[/li]
[li][color=red]sub.cpp[/color][/li]
[li]sub2Header.h[/li]
[li][color=red]sub3.cpp[/color][/li][/ul][/:m]
[li]/utility
[ul][]utility1.h[/li]
[li][color=green]utility1.cpp[/color][/li]
[li][color=green]otherUtility.cpp[/color][/li][/ul][/:m]
[li]Library1.h[/li]
[li][color=green]sourceFile.cpp[/color][/li]
[li][color=green]sub2Source.cpp[/color][/li]
[li]sub3.h[/li][/list:u][/:m]
[li]/otherDir
[ul][][color=green]Library1.cpp[/color][/li][/ul][/:m][/list:u][/:m][/list:u]
[color=green]File.cpp[/color]: Will be compiled
[color=red]File.cpp[/color]: Will not be compiled

In this example utility1.cpp, otherUtility.cpp, sourceFile.cpp, Library1.cpp and sub2Source.h will all be compiled.
However, sub.cpp and sub3.cpp will not be compiled as they are in a subdirectory other than utility.

For recap, the header file Library1.h can be included in other libraries (if it has been included in a sketch file) and sub.h, sub2Header.h, utility1.h, Library1.h and sub3.h can all be included in any file in Library1.