How Sloeber deals with libraries; the library manager; import into project and install

[jantje]

First off: Some vocubulary used in Sloeber

We use the word installing when Sloeber library manager downloads a file from the internet and installs it on your system to make the library available for compilations.
We use the word importing a library in a project when making a link in the projects libraries folder to the installed library.
Compile time is the action that is executed after you pressed the verify/build button.

Compile time

At compile time Sloeber uses the libraries that are linked in the libraries folder. You can add and remove libraries there via the menu "add a library to the selected project" or let Sloeber library library manager manage the content of the folder (default behaviour) or a mix of the 2 (adding manually the ones Sloeber library manager does not add automatically or delete the folder/library to let the library manager retry).
But what is important is that (in contrast with Arduino IDE) no libraries/platforms are searched at compile time. The libraries in the libraries folder are used as listed at the time the compile command is given.

What are the workspace configuration options in regards to libraries

You can allow Sloeber library manager to import libraries in your project in the workspace preferences.
You can allow Sloeber library manager to install libraries.
You can add library json files pointing to library locations on the internet in the "Third party index url's" page.

What triggers the library adding

Sloeber subscribes on indexer updates with CDT.
The indexer parses the code and provide all kinds of interesting information that is used to increase user experience.
The indexer is at the hart of why Sloeber is a good tool.
When CDT informs Sloeber of indexer updates Sloeber queries the CDT indexer for "unresolved includes".

How are libraries found

CDT reports unresolved includes as header files, let us assume one of the unresolved includes is "xx.h". Based on the CDT provided "xx.h" Sloeber will search for the library with the name"xx". Sloeber assumes the library name "xx" to be the folder name containing the library code. Therefore Sloeber will search for a folder named "xx" in any of the provided places containing libraries.
These places are

• core/libraries (provided by the platform with the boards)
• Private libraries folders
• Sloeber Library manager installed libraries
• Library json files provided in "Third party index url's" page.

notes:

1. The Arduino framework does not enforce the library xx to contain a xx.h file.
2. Sloeber contains additional code to mitigate the above described Arduino framework discrepancy a bit (but far from fully)

The Sloeber library way of selecting the library when importing libraries to a project.

1. If a Library is found in the libraries folder of the board core; this one is used
2. Else: If a Library in the private libraries is found this one is used (if multiple private libraries contain the library the order of the listing of private libraries folders will decide on the library used)
3. Else: if a library installed by the library manager is found this one is used
4. Else: if you have the option to "install missing libraries" on; the library manager will search for a matching library in the library jsons provided in the "third party index url's" and if a matching library is found the library manager will install it but not import it into the project (this is supposed to happen at the next search for unresolved includes).

Note that "the find the library" is different implementation then Arduino IDE.
Therefore a successful "install missing library" may not lead to a successfully "import the library" nor to resolving the unresolved include.

Manually importing libraries to a project

When Sloeber creates the list of libraries you can import to the project Sloeber first searches all possible libraries locations for libraries to be added to the list.
In case of naming conflicts (that is 2 libraries having the same (folder)name; the library that will be added to the list of libraries will be first one found in the list below

1. The library part of the product
2. The Library part of the private libraries(the search is in order of the listing of private libraries)
3. The library installed by the library manager