Skip to content

Use the libraries

Just like any other IDE, using a library in a project requires specifying an #include statement on the main sketch.

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

By default, the main Makefile lists…

# Application libraries
#
APP_LIBS_LIST = 0

# User's libraries
#
USER_LIBS_LIST = 0

# Local libraries
#
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

Use the core libraries

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

To use the core library,

  • Add the #include "Arduino.h" statement on the main sketch or the header file.
// SDK
#include "Arduino.h"

Warning

This #include "Arduino.h" statement is compulsory for emCode.

The main Makefile does not need to mention the Arduino SDK as it is included by default.

Use the application libraries

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

To use an application library,

  • Add the corresponding #include statement with the name of the header file on the main sketch or the header file.
// Include application, user and local libraries
#include "Wire.h"
  • Mention the name of the folder of the library to the variable APP_LIBS_LIST in the main Makefile.
# Application libraries
# default = 0 = none
#
APP_LIBS_LIST = Wire
  • Set APP_LIBS_LIST to 0 to include no application library.

In case of multiple libraries,

  • Mention one include with the name of the header file per line.
// Include application, user and local libraries
#include "Wire.h"
#include "SPI.h"
  • Separate the names of the folders of the libraries with a space.
# Application libraries
#
APP_LIBS_LIST = Wire SPI

Use the user’s libraries

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

To use a user’s library,

  • Add the corresponding #include statement with the name of the header file on the main sketch or the header file.
// Include application, user and local libraries
#include "Ethernet.h"
  • Mention the name of the folder of the library to the variable USER_LIBS_LIST in the main Makefile.
# User's libraries
# default = empty = all
#
USER_LIBS_LIST = Ethernet

In case of multiple user’s libraries,

  • Mention one include with the name of the header file per line.
// Include application, user and local libraries
#include "Ethernet.h"
#include "JSON.h"
  • Separate the names of the folders of the libraries with a space.
# User's libraries
# default = empty = all
#
USER_LIBS_LIST = Ethernet JSON

Remember, only the specified libraries are compiled.

  • Set USER_LIBS_LIST to 0 to include no local library.

  • Keep USER_LIBS_LIST empty to include all the include no local libraries.

  • Use the same procedure for pre-compiled libraries.

emCode uses the pre-compiled archives for the local libraries first when they are available.

To force the compilation of the local libraries over the use of the pre-compiled archives,

  • Edit the main Makefile;

  • Set USE_ARCHIVES to false.

# For building, use available archives, false or true, default = true
USE_ARCHIVES = false

Use the local libraries

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

To use a local library,

  • Add the corresponding #include statement with the name of the header file on the main sketch or the header file.
// Include application, user and local libraries
#include "LocalLibrary.h"
  • Mention the name of the folder of the library to the variable LOCAL_LIBS_LIST in the main Makefile.
# Local libraries
# default = empty = all
#
LOCAL_LIBS_LIST = LocalLibrary

In case of multiple local libraries,

  • Mention one include with the name of the header file per line.
// Include application, user and local libraries
#include "LocalLibrary.h"
#include "AnotherLibrary.h"
  • Separate the names of the folders of the libraries with a space.
# Local libraries
# default = empty = all
#
LOCAL_LIBS_LIST = LocalLibrary AnotherLibrary

Remember, only the specified libraries are compiled.

  • Set LOCAL_LIBS_LIST to 0 to include no local library.

  • Keep LOCAL_LIBS_LIST empty to include all the include no local libraries.

  • Use the same procedure for pre-compiled libraries.

Warning

A pre-compiled library can’t be debugged, as the code source isn’t provided.

For more information on how to generate a pre-compiled library,