Go Down

Topic: Project File Structure / Project Libraries (Read 197 times) previous topic - next topic

awbMilne

Feb 17, 2020, 11:08 pm Last Edit: Feb 20, 2020, 05:54 pm by awbMilne
Hey everyone!

I've been working on writing and testing libraries for Arduino for the past couple weeks and everything has been going great.

One issue I ran into was how to deal with a bunch of library files inside a project directory.

I use VS-Code as my main IDE, so the Arduino plugin is a fantastic addition that allows me to do everything from VS-Code. Using the complex VS-Code file setups for workspaces, I was able to add the Arduino Libraries directory into the workspace so I could access my project code and the library code at the same time to change stuff as needed.
This worked great until I wanted to put the project into a Git repository and version control the code and the library. I looked through the forums to find a way to use libraries inside the project folder, but didnt find anything.
I eventually gave up on it.
But a couple weeks later, I tried again and managed to find some information to piece it all together (information in the references below). Here is what I found out.

(Written and effective as of Arduino IDE 1.8.11, theoretically effective as of 1.5.0)

I looked through the forums and found the 1.5+ library organization scheme which seems to work, but only under very specific circumstances.
───────────────────────────────────────────────────────────────────────
1.5+ Scheme
├── Project (Main Directory / Root)
    ├── Project.ino
    ├── src
          ├── LibraryA
               ├── src
                      ├── LibraryA.cpp
                      ├── LibraryA.h
               ├── library.properties
          ├── LibraryB
               ├── src
                      ├── LibraryB.cpp
                      ├── LibraryB.h
               ├── library.properties

In order to use this scheme, you are required to have library.properties file to document your library (doesnt need to have any data). If you are looking to develop libraries and keep them local to project or you want to use modified versions of libraries, I suggest you use this scheme. Using this scheme you need to include the libraries using the path from the the project directory as follows:

Code: [Select]
#include "src/LibaryA/src/LibraryA.h"
#include "src/LibaryB/src/LibraryB.h"

void setup(){
...
}
void loop(){
...
}


NOTE: Using quotation marks is different from using the <> characters. Quotation marks makes the Arduino compiler look for the file in the local directory before looking in the IDE's libraries directory. Using <> characters makes it search only in the IDE's libraries.

───────────────────────────
                  ALTERNATIVELY                       
───────────────────────────


You can use this folder structure.
1.5+ & Old Libraries Scheme
├── Project (Main Directory / Root)
    ├── Project.ino
    ├── src
          ├── LibraryA
               ├── LibraryA.cpp
               ├── LibraryA.h
          ├── LibraryB
               ├── LibraryB.cpp
               ├── LibraryB.h

This scheme does not require the library.properties file. Not having the file forces the arduino code builder to use the pre-1.5 library system without the src directory and .properties file. If you are just looking to abstract some code to organize your project and arent writting/testing/modifying libraries, I would suggest you use this scheme. Similair to the first scheme, you need to use the path in the #include statements:

Code: [Select]
#include "src/LibaryA/LibraryA.h"
#include "src/LibaryB/LibraryB.h"

void setup(){
...
}
void loop(){
...
}


───────────────────────────────────────────────────────────────────────
As stated above, the first scheme used the 1.5+ Libraries template and what I believe is the 1.5 project folder outline.
The second scheme uses the old Library template and the 1.5 project folder outline.
───────────────────────────────────────────────────────────────────────


Anyone with more knowledge than me is welcome to contribute and correct the technical aspects of this post, or to suggest better ways to get the same effect (ways that dont require long #include statements).


───────────────────────────────────────────────────────────────────────
Reference:
1.5 Library scheme: https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification
GitHub Issue #5186 relating to temporary removal in 1.6.10: https://github.com/arduino/Arduino/issues/5186

Other Similair Forum Posts:
https://forum.arduino.cc/index.php?topic=536771.0
https://forum.arduino.cc/index.php?topic=38124.0
https://forum.arduino.cc/index.php?topic=419818.0



───────────────────────────────────────────────────────────────────────

CORRECTION
As of 1.8.11, you do not need the library.properties file for the 1.5 file structure, it will compile without the need for it.

Go Up