Skip to content

[skip changelog] Update library specification to reflect recently added features #789

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 6, 2020
Merged

[skip changelog] Update library specification to reflect recently added features #789

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3d00af8
[skip ci] Remove outdated statement re: Library Manager not handling …
per1234 Jul 5, 2020
20be188
[skip ci] Update documentation re: library "import" behavior
per1234 Jul 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/library-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ This is the specification for the 3rd party library format to be used with Ardui
* rev.2.1 will be implemented starting from version Arduino IDE 1.6.10
* rev.2.2 will be implemented starting from version Arduino IDE 1.8.10

This new library format is intended to be used in tandem with **Library Manager**, available since Arduino IDE 1.6.2. The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy to use graphic interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and [Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11) as well as [`arduino-cli lib`](https://arduino.github.io/arduino-cli/commands/arduino-cli_lib/). It doesn't yet take care of dependencies between libraries.
This new library format is intended to be used in tandem with **Library Manager**, available since Arduino IDE 1.6.2. The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy to use graphic interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and [Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11) as well as [`arduino-cli lib`](https://arduino.github.io/arduino-cli/commands/arduino-cli_lib/).

More information about how Library Manager works is available [here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).

Expand Down Expand Up @@ -83,7 +83,7 @@ For 1.5.x+-only libraries, the source code resides in the **src** folder. For ex
Servo/src/Servo.h
Servo/src/Servo.cpp

The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the Arduino IDE's "Sketch > Include Library" menu or the Arduino Web Editor's "Include" button), an `#include` statement will be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder.
The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the Arduino IDE's "Sketch > Include Library" menu or the Arduino Web Editor's "Include" button), the default behavior (configurable via the [library.properties `includes` field](#libraryproperties-file-format)) is for an `#include` statement to be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder.

For backward compatibility with Arduino IDE 1.0.x, the library author may opt to place source code into the root folder, instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched from the **library root folder** and the **utility** folder, for example:

Expand Down