Skip to content

[skip changelog] Document "Library Name Priority" #1301

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 1 commit into from
May 28, 2021
Merged

[skip changelog] Document "Library Name Priority" #1301

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 19 additions & 1 deletion docs/sketch-build-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,10 @@ following rules, one by one in this order, until a rule determines a winner:

1. A library that is architecture compatible wins against a library that is not architecture compatible (see
[**Architecture Matching**](#architecture-matching))
1. A library that has better "folder name priority" wins (see [**Folder Name Priority**](#folder-name-priority))
1. A library with both [library name](#library-name-priority) and [folder name](#folder-name-priority) matching the
include wins
1. A library that has better "library name priority" or "folder name priority" wins (see
[**Library Name Priority**](#library-name-priority) and [**Folder Name Priority**](#folder-name-priority))
1. A library that is architecture optimized wins against a library that is not architecture optimized (see
[**Architecture Matching**](#architecture-matching))
1. A library that has a better "location priority" wins (see [**Location Priority**](#location-priority))
Expand Down Expand Up @@ -86,6 +89,21 @@ Examples:
| `architectures=avr,esp8266` | YES | YES |
| `architectures=samd` | NO | NO |

### Library Name Priority

A library's name is defined by the [library.properties](library-specification.md#libraryproperties-file-format) `name`
field. That value is sanitized by replacing spaces with `_` before comparing it to the file name of the include.

The "library name priority" is determined as follows (in order of highest to lowest priority):

| Rule | Example for `Arduino_Low_Power.h` |
| ------------------------------------------------------------------------- | --------------------------------- |
| The library name matches the include 100% | `Arduino Low Power` |
| The library name matches the include 100%, except with a `-master` suffix | `Arduino Low Power-master` |
| The library name has a matching prefix | `Arduino Low Power Whatever` |
| The library name has a matching suffix | `Awesome Arduino Low Power` |
| The library name contains the include | `The Arduino Low Power Lib` |

### Folder Name Priority

The "folder name priority" is determined as follows (in order of highest to lowest priority):
Expand Down