Expiriment: Arduino Code Reuse

Motivation

I am an experienced C++ programmer and I believe in the DRY principle. I have some code I would like to package for reuse and share. The code is actually a C++ template, which I do not require an external implementation file (a .cpp file). According to the documentation found at LibraryTutorial on the Arduino site, this should be easy.

Procedure 1

Create a guarded header file containing the template

Execution of Procedure 1

Well, I’m at a loss already. The documentation does not state where to locate the library file at all. Taking a look at where my sketch is stored (~/Documents/Arduino), I noticed a library directory. This directory is empty. I'll call this ${ARDUINO_USER_HOME}, as it will most likely vary between OSX, *nix, and Windows.

I liked to be well organized in terms of code structure. I’m not sure what my library should be called, so for the sake of this experiment I’m labeling the library as ‘mee’. I created the file at ${ARDUINO_USER_HOME}/libraries/mee/shovel.h to encapsulate the code I would like to reuse. I attempted to compile the sketch referencing the file with an include to shovel.h. This failed with a compilation error. I then attempted to following combinations to import the file into the sketch which also failed:

Sketch > Add File menu item. This copied the file into my sketch workspace. To get remove the file I shutdown the Arduino IDE and deleted the file from the sketch directory.
Modified the include to #include <mee/shovel.h>. This failed with another compilation error.
Moving the file to ${ARDUINO_USER_HOME}/libraries/mee/mee/shovel.h. I kept the include directive the same. When this failed I change the include directive to <shovel.h> and tried again.

This caused me to wonder what would cause the Arduino IDE to recognize a new library was installed. When I removed the copied file resulting from the action on bullet 2, I found the Arduino recognized new libraries on start, or at least empty directories, as libraries. When you attempt to add the library however, it fails, inserting only a blank line. At this point I was wondering if there was additional meta-data which must be within the directory. So I ventured to the built-in library locations, under the OSX install I had, located at /Applications/Arduino.app/Contents/Resources/Java/libraries/Servo. The only special file I found was keywords.txt. So on to procedure #2!

Procedure 2

Create the directory ${ARDUINO_USER_HOME}/libraries/l
Create an empty keywords.txt file
Create the file l.h
Restart the Arduino IDE
Import the library
Attempt to ‘verify’ (IE: Compile)

So that worked, with the IDE placing an include at the top of the file, sending the correct directives to GCC and building the project. My keywords.txt file is blank. Reflecting on my experience versus the Arduino’s LibraryTutorial There is one other difference between the first attempt and the second: the name of the header file. So the next attempt I don’t create the keywords files.

Procedure 3

Create the directory ${ARDUINO_USER_HOME}/libraries/ltest
Create the file ltest.h
Restart the Arduino application
Import the library
Verify

This worked perfectly! The program compiled as I expected. Reflecting upon my achievementI realized the import menu action only added an include directive at the top. In the past when I desired to import a library I would manually add the #include to the top fo the file also. So I decided to see if I could circumvent the tool and manually include the file.

Procedure 4

Create the directory ${ARDUINO_USER_HOME}/libraries/ltest
Create the test file ltest.h within the new library directory
Restart the Arduino IDE application
Add the include directive to the stop of the Sketch you would like to import
Verify

Following this procedure the Sketch with dependent code correctly compiled. I’m not sure about library versioning, perhaps that is an experiment for the future.