Manage the Libraries for Compilation

This procedure allows to manage the libraries:

  • Select only the libraries to be taken into account to speed compilation, and

  • Exclude some libraries to avoid conflicts.

For more information on how to add libraries to your project,

For more information on how to install libraries,

The main Makefile is populated with the list of all the libraries during preparation.

Select the Libraries for Compilation

On the makefile, two variables are used:

  • APP_LIBS_LIST for the application libraries from the IDEs,

  • USER_LIBS_LIST for the user's libraries under the Library sub-folder on the sketchbook folder,

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

# List user's libraries here
#
USER_LIBS_LIST = 0

embedXcode+ provides a third variable, LOCAL_LIBS_LIST to manage the local libraries when they are placed in folders.

# List local libraries here
#
LOCAL_LIBS_LIST =

By default, LOCAL_LIBS_LIST is set to empty and includes all the local libraries.

Select the Application Libraries

By default, the variable APP_LIBS_LIST is set to 0: no library is considered and compiled.

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

This is the fastest option, as no library is compiled.

If you don't know which libraries are needed,

  • Just leave the line empty after the variable.
# List Arduino/chipKIT/Wiring/Energia/Maple libraries here
#
APP_LIBS_LIST =

This is the slowest option. Additionally, it may rise errors as some libraries are conflicting with others.

So the best and recommended solution consists on selecting the libraries.

If an application library is required, you need to specify the name of its folder. For example, if the Wire library is required in the project,

  • Specify the Wire folder after the APP_LIBS_LIST variable in the main Makefile:
# List Arduino/chipKIT/Wiring/Energia/Maple libraries here
#
APP_LIBS_LIST = Wire
  • Add the #include statement in the main sketch:
// Include application, user and local libraries
#include "Wire.h"

In case of multiple application libraries,

  • Separate the names of the folders of the libraries with a space.

Remember, only the specified libraries are compiled.

Select the User's Libraries

By default, the variable USER_LIBS_LIST is set to 0: no library is considered and compiled.

# List user's libraries here
#
USER_LIBS_LIST = 0

This is the fastest option, as no library is compiled.

If you don't know which libraries are needed,

  • Just leave the line empty after the variable.
# List users libraries here
#
USER_LIBS_LIST = 

This is the slowest option. Additionally, it may rise errors as some libraries are conflicting with others.

So the best and recommended solution consists on selecting the libraries.

If a user’s library is required, you need to specify the name of its folder.

For example, the project requires the myLibrary library, which is located under the Libraries sub-folder of the sketchbook folder and contains myLibrary.h and myLibrary.cpp.

  • Specify the myLibrary folder after the USER_LIBS_LIST variable in the main Makefile:
# List users libraries here
#
USER_LIBS_LIST = myLibrary
  • Add the #include statement in the main sketch:
// Include application, user and local libraries
#include "myLibrary.h"

In case of multiple user's libraries,

  • Separate the names of the folders of the libraries with a space.

Remember, only the specified libraries are compiled.

Select the Local Libraries

embedXcode+ provides a third variable, LOCAL_LIBS_LIST to manage the local libraries when they are placed in folders.

  • The LOCAL_LIBS_LIST option allows to select the local libraries when they are stored into sub-folders.
# List local libraries here
#
LOCAL_LIBS_LIST =

By default, LOCAL_LIBS_LIST is set to empty and includes all the local libraries.

  • The LOCAL_LIBS_LIST option is especially useful for selecting among different versions of the same library.

In such a case, keeping the variable LOCAL_LIBS_LIST empty takes all the versions and ends with a compilation error.

On the following example, the same library LocalLibrary has two versions, one stored in the Version1 sub-folder of the project and the other in the Version2 sub-folder.

Two versions of the same local library in different sub-folders

If you want to use the Version1,

  • Specify the name of the sub-folder Version1 after the variable LOCAL_LIBS_LIST on the main Makefile.

If you want to use the Version2,

  • Specify the name of the sub-folder Version2 after the variable LOCAL_LIBS_LIST on the main Makefile.

In case of multiple local libraries,

  • Separate the names of the folders of the libraries with a space.

The same variable also applies on pre-compiled libraries located under sub-folders. For more information on pre-compiled libraries,

Check and Update the Boards Reference List

The Arduino IDE starting release 1.6.5, and the Energia IDE release starting release 1.6.1E18, include a Boards Manager for downloading, installing and managing the boards.

For a set of boards, a dedicated sub-folder located under the ~/Library/Arduino15/packages or the ~/Library/Energia15/packages folder contains the board package, with the core libraries and the application libraries.

The content of the Arduino SAMD board package

Check the Boards Reference List

For example, the board package for the Arduino Zero boards is located under the ~/Library/Arduino15/packages/arduino/hardware/samd/1.6.14 folder.

The boards packages for Arduino

The exact path of the libraries contains the release number, here 1.6.14.

The About.mk file lists the references of the releases for each package.

The board ARDUINO_SAMD_RELEASE is set accordingly to 1.6.14 on the About.mk reference list.

ARDUINO_SAMD_RELEASE     = 1.6.14

Check Platforms and MCUs

The Check platforms and MCUs utility lists all the platforms and MCUs, checks the installed releases against the supported ones, and generates a report.

The Check Platforms and MCUs utility is located under the ~/Documents/embedXcode folder.

  • Double-click on the utility to generate the report.

Here is an example of the generated Platforms and MCUs Report.

Based on the Platforms and MCUs Report,

  • Upgrade the boards packages listed in red.

In this example, the Arduino SAMD package is installed with release 1.6.14, while embedXcode supports the newer release 1.6.15. Release 1.6.15 is the recommended release.

  • Downgrade the boards packages listed in yellow, as the newer releases haven't been tested yet.

In this example, the Arduino SAM package is installed with release 1.6.11, while embedXcode supports older release 1.6.10. Release 1.6.10 is the recommended release.

  • Nothing to be done for the boards packages listed in green.

In this example, the Arduino IDE and the Arduino AVR package are installed and correspond to the recommended releases.

  • Install the boards packages listed in blue.

In this example, the Arduino STM32F4 package isn't installed. Release 1.0.0 is the recommended release.

  • Beware of the boards listed in light colours.

In this example, the Intel Galileo and Intel Edison boards packages correspond to the expected releases but are no longer supported. They can be used and embedXcode still compiles against them.

For more information on how to download and install the boards packages,

Update the Boards Reference List

As an alternative when the installed boards package differs from the expected release supported by embedXcode, the boards reference list can be edited.

However, because this boards package hasn't been tested with embedXcode, no support can be provided.

In case a new release of the Arduino Zero board package has been downloaded and installed with the number 1.6.15, compilation may result in an error. The reference list needs to be updated.

  • Open the About.mk file in the project.

  • Find the corresponding entry, here ARDUINO_SAMD_RELEASE for the Arduino Zero board.

ARDUINO_SAMD_RELEASE     = 1.6.14
  • Edit and change the old version for the new one.
ARDUINO_SAMD_RELEASE     = 1.6.15

Additional changes may be required for the tool-chain and the utilities.

  • Edit the corresponding values, here for the Arduino Zero board.
ARDUINO_SAMD_RELEASE    = 1.6.15
ARM_GCC_RELEASE         = 4.8.3-2014q1
BOSSAC_RELEASE          = 1.6.1-arduino
CMSIS_RELEASE           = 4.0.0-atmel
OPENOCD_RELEASE         = 0.9.0-arduino
  • Launch a All or Build target.

The All and Build targets ensure consistency with the new release, as the Make or Fast targets reuse the libraries previously compiled with the old release.

For the embedXcode edition, this setting is valid for the project only.

For the embedXcode+ edition, this setting is valid for all the projects.

Exclude Libraries

Some libraries are specific to a platform but are included in a folder shared with other platforms, and some libraries may conflict with other ones.

For example, the WiFi library included among the core libraries is solely designed for the Arduino WiFi Shield.

With the Arduino 1.0 and 1.5 IDE, the WiFi is included by default in the compilation process, and raises error and warning messages even with the official IDE.

To exclude the WiFi library and avoid any unnecessary error,

  • Mention its name WiFi after the variable EXCLUDE_LIBS.
# List the libraries to be excluded
# For example, WiFi may crash on Arduino 1.0.2
#
EXCLUDE_LIBS = WiFi

In case of multiple libraries,

  • Separate the names of the libraries with a space.

Other cases include Esplora on Arduino 1.0.3, Firmata on Teensy 3.0, ArduinoRobot on Arduino 1.0.5.

The procedure is the same for a user's library.

For example, if a serial library conflicts with SoftwareSerial, use EXCLUDE_LIBS to prevent that.

  • Mention its name SoftwareSerial after the variable EXCLUDE_LIBS.
# List the libraries to be excluded
# For example, WiFi may crash on Arduino 1.0.2
#
EXCLUDE_LIBS = SoftwareSerial

If you need to use all the libraries,

  • Leave the line empty after the EXCLUDE_LIBS variable.
EXCLUDE_LIBS =

By default, the EXCLUDE_LIBS is empty and the line has a leading # to comment it.

# List the libraries to be excluded
#
#EXCLUDE_LIBS =

The parameter impacts all libraries, core, application, user and local.