Add Libraries to the Project

There are four kinds of libraries:

  • The core libraries include all the basic functions required for development. Each platform provides its own set compatible with the Wiring and Arduino framework. One single #include statement in the main sketch and in the header files includes all of them.

  • The application libraries are optional libraries to provide additional features, like managing the specific I²C and SPI ports. They require to be explicitly mentioned with the #include statement on the main sketch and listed on the main Makefile after the APP_LIBS_LIST variable.

  • The user's libraries are developed by the user and stored under the Library sub-folder on the sketchbook folder. They require to be explicitly mentioned with the #include statement on the main sketch and listed on the main Makefile after the USER_LIBS_LIST variable.

  • The local libraries are part of the project and located on the same folder as the main sketch. They require to be explicitly mentioned by the #include statement on the main sketch. By default, all the local libraries are included.

embedXcode+ lists all the application and user’s libraries for the selected platform on the main Makefile. It also allows to create folders for local libraries and select them.

embedXcode+ introduces a variant for the local libraries, the pre-compiled libraries.

  • Instead of using the source code, the pre-compiled libraries are already built and ready to use. Just like the local libraries, they are part of the project and located on the same folder as the main sketch, they require to be explicitly mentioned by the #include statement on the main sketch and, they are all included by default.

Where to Find the Libraries in embedXcode and in the Finder

Each kind of library is located in a specific group or sub-group in embedXcode and in a specific folder in the finder.

There are slight different structures for embedXcode standard edition and embedXcode+ edition.

Identify the Different Structures

The embedXcode standard edition has a separate Sketchbook group for the users's libraries, while the Resources group lists all the other core and application libraries.

The Resources group of the embedXcode+ edition includes all the core, application and user's libraries.

embedXcode and embedXcode+

Locate the Core and Application Libraries

The core and application libraries are located under the Resources group in embedXcode and protected inside the IDE applications on the /Applications folder.

Core and application libraries in embedXcode and in the Finder

For the boards managed by the Arduino 1.6.5 and later, those libraries are also located under the ~/Library/Arduino15/packages folder.

Same logic applies for Energia 1.6.10E18 with libraries located under the ~/Library/Energi15/packages folder.

The exact path to the libraries includes a release number, listed in the About.mk file. For more information,

  • Please refer to the section Set the Boards Libraries Version.

Locate the User's Libraries

On embedXcode standard edition, the user's libraries are listed below the Sketchbook group in embedXcode, and stored on the Libraries or libraries sub-folder under the sketchbook folder.

User’s library in embedXcode and in the Finder

On embedXcode+ edition, the user's libraries are listed below the Sketchbook sub-group of the Resources group in embedXcode, and stored on the Libraries or libraries sub-folder under the sketchbook folder.

User’s library in embedXcode+ and in the Finder

Locate the Local Libraries

The local libraries are listed on the main group in embedXcode, embed1 in the example, and stored on the same folder where the main sketch in located, embed1/embed1 in the example.

Local libraries in embedXcode and in the Finder

embedXcode+ allows to have dedicated folders for the local libraries.

embedXcode+ allows to include and manage pre-compiled libraries. For more information on pre-compiled libraries,

  • Please refer to Locate the Pre-Compiled Libraries.

The local libraries are then listed on the dedicated LocalLibrary sub-group under the main embed1 group in embedXcode, and stored on the LocalLibrary sub-folder under the folder where the main sketch in located, embed1/embed1/LocalLibrary in the example.

Local libraries in embedXcode and in the Finder for embedXcode+

Using a library requires adding an #include statement on the main sketch or the header file and listing it on the main Makefile.

Locate the Pre-Compiled Libraries

This section requires embedXcode+.

embedXcode+ allows to include and manage pre-compiled libraries. To do so,

  • Place the the pre-compiled libraries with extension .a, their header files with extension .h, and additional file .board, into the main folder of the project or within a sub-folder of the project.

Pre-compiled local libraries in embedXcode and in the Finder for embedXcode+

In the example shown above, the LocalLibrary sub-folder contains: LocalLibrary.a is the pre-compiled library, LocalLibrary.h the corresponding header file and arduino_zero_native.board for the board the library has been compiled against.

  • Check no code file with extension .cpp or other is on the same location.

  • Ensure the pre-compiled library is consistent with the target. To do so, check the file .board. refers to the same board as the current target.

embedXcode+ checks the consistency of the pre-compiled libraries with the current board based on the the file .board, and includes the pre-compiled libraries with extension .a during linking.

Please note that a pre-compiled library can't be debugged, as the code source isn't provided.

For more information on how to generate pre-compiled libraries,

Include Libraries to the Main Sketch and Header Files

Just like any other IDE, including a library to the project is done by specifying an #include statement on the main sketch.

Additionally, the library needs to be mentioned on the main Makefile to be compiled.

All the core libraries are included for compilation using one single #include statement on the main sketch. The same #include statement is also required on the header files.

For Arduino, the core library statement is

// Core library for code-sense - IDE-based
#include "Arduino.h"

The Application libraries require to be explicitly mentioned with the #include statement on the main sketch and listed on the main Makefile.

The include statement for the Wire or I²C library is

// Core library for code-sense - IDE-based
#include <Wire.h>

User's libraries require to be explicitly mentioned with the #include statement on the main sketch and listed on the main Makefile.

The include statement for a user's library is

// Include application, user and local libraries
#include "myLibrary.h"

Finally, local libraries require to be explicitly mentioned by the #include statement on the main sketch. By default, all the local libraries are included.

The include statement for a local library is

// Include application, user and local libraries
#include "LocalLibrary.h"

List the Libraries on the Main Makefile

By default, the main Makefile looks like...

# List Arduino/chipKIT/Digispark/Energia/Maple/Microduino/Teensy/Wiring libraries here
#
APP_LIBS_LIST = 0

# List user's libraries here
#
USER_LIBS_LIST = 0

# List local libraries here
#
LOCAL_LIBS_LIST =

...with the following options:

  • All the core libraries are included.

  • No application library is included.

  • No user's library is included.

  • All the local libraries are included.

If a library has been included in the main sketch or in a header file, it needs to be listed on the main Makefile to be compiled. This is a standard procedure

All the core libraries are included for compilation by default, so there no need to list them on the main Makefile.

The folders of the application libraries require to be listed on the main Makefile after the APP_LIBS_LIST variable.

The APP_LIBS_LIST variable lists the Wire or I²C library.

# List Arduino/chipKIT/Digispark/Energia/Maple/Microduino/Teensy/Wiring libraries here
#
APP_LIBS_LIST = Wire

In case of multiple libraries, separate the names of the folders of the libraries with a space.

The folders of the user's libraries require to be listed on the main Makefile after the USER_LIBS_LIST variable.

The USER_LIBS_LIST variable list a user's library, here myLibrary.

# List user's libraries here
#
USER_LIBS_LIST = myLibrary

In case of multiple libraries, separate the names of the folders of the libraries with a space.

With embedXcode+, the makefile comes populated with the list of the core, application and user’s libraries. This list is added during the preparation and for the selected platform of the project.

An example of the list of the application libraries for Arduino.

# List of Arduino/chipKIT/Digispark/Energia/Maple/Microduino/Teensy/Wiring libraries
#
# ARDUINO = Bridge EEPROM Esplora Ethernet
#   Firmata GSM LiquidCrystal SD Servo
#   SoftwareSerial SPI Stepper WiFi Wire
#
APP_LIBS_LIST = Wire

In case of multiple libraries, separate the names of the folders of the libraries with a space.

All the local libraries are included by default. Leave the line empty after the LOCAL_LIBS_LIST variable.

The empty LOCAL_LIBS_LIST variable takes all local libraries.

# List local libraries here
#
LOCAL_LIBS_LIST =

Create Folders for Local Libraries

embedXcode+ allows to create folders for local libraries and select them.

The LOCAL_LIBS_LIST variable lists the LocalLibrary library.

# List local libraries here
#
LOCAL_LIBS_LIST = LocalLibrary

In case of multiple libraries, separate the names of the folders of the libraries with a space.

In the following example, the application Wire library, the user's library myLibrary and all the local libraries are selected.

# List Arduino/chipKIT/Digispark/Energia/Maple/Microduino/Teensy/Wiring libraries here
#
APP_LIBS_LIST = Wire
# List user's libraries here
#
USER_LIBS_LIST = myLibrary
# List local libraries here
#
LOCAL_LIBS_LIST =

For more information about how the libraries are managed during compilation,