User Libraries

User libraries are ones that don't conform to the Arduino standard.
They should be architecture and OS agnostic, and hopefully restrain from any heap-oriented code (such as malloc). They should also provide sources instead of pre-built binaries.

A user library's sources could be located anywhere in the host system, without any constraints.
It is the user's responsibility to "find" them and pass their paths to the framework.

It's considered good practice to keep a user library's sources under the project's scope, especially if that library is created solely for the project at hand. It also makes it easy to "find" it.

As explained above, the library isn't found like an Arduino Library, thus no library target is magically created by some search process. Instead, the library should be created manually.
Creating a library target is really straightforward since it requires just the CMake library API!
To create a library, one would call the add_library function.

Since the library is manually created using CMake's API, it also requires the user to manually specify include directories, so that other targets linking the library will have access to its' headers.
This is done by calling the target_include_directories function, passing the name of the library target created earlier with add_library, a PUBLIC scope (So it will have effect during linkage) and the header directories themselves.
e.g target_include_directories(my_library_target PUBLIC include) where include is the directory containing all public headers.

At last, the library target should be linked to an existing target, just as you would do with an Arduino library.

The following is a list of common and recommended places where user libraries should be stored:

1. Inside the project's root directory, under a sub-directory named after the library.
   Example:

   |-Project Root
        |-Library
           |-include
               |-Library.h
           |-src
               |-Library.c
   

2. Inside the project's root directory, under a sub-directory named dependencies where all other user libraries are located.
   Note: This is recommended only for 3rd party user libraries, i.e. libraries that weren't created by the user itself.

The following example shows how a user library named Robotics is included in the project:

set(Robotics_lib_path ${CMAKE_SOURCE_DIR}/dependencies/Robotics-1.2)
add_library(Robotics_lib STATIC ${Robotics_lib_path}/src/Robotics.c)
target_include_directories(Robotics_lib PUBLIC ${Robotics_lib_path}/include)
link_arduino_library(my_target Robotics_lib ${board_id})

Where ${CMAKE_SOURCE_DIR} is the parent directory of the project's main CMakeLists.txt file.
The directory structure of the example is as follows:

|-Project Root
    |-dependencies
        |-include
            |-Robotics.h
        |-src
            |-Robotics.c
    |-src
    |-CMakeLists.txt

Note that the example above assumes the my_target target has already been created earlier.
Also, board's ID has been retrieved as well.