Incorrect capitalization of library.properties filename
Causes library.properties to not be recognized on filename case sensitive OS (verified).
library.properties file format is UTF-8 BOM
Confirmed to cause the "Add .ZIP library" process to silently fail. I haven't checked if it causes other problems (likely will cause 1.5 format libraries that are manually installed to not be recognized).
Check if other file formats also cause the problem
verified working format is UTF-8
Missing required properties
Invalid property line
Every line of the file must either contain a = (even as the first character) or start with # (verified).
Otherwise every compilation (even if the code doesn't include the library) fails: Property line ... in file ... is invalid.
I've seen this in the wild where they were attempting to break the paragraph value into multiple lines by escaping the newline. That doesn't work. You can use <br> or <br/> instead.
Properties:
name (required)
The name value is used to determine the folder name for libraries installed via Library Manager. For this reason, the Library Manager indexer requires the name value to follow the same folder name restrictions as are imposed on sketch and library folder names, with the exception that spaces are allowed (they are replaced by _ in the folder name).
(A-Z or a-z) and numbers (0-9), spaces ( ), underscores (_), dots (.) and dashes (-). It cannot start or end with a space, and also it cannot start with a number.
The starting with a number prohibition has been lifted since Arduino IDE 1.8.4 but it's unknown whether the Library Manager indexer still prohibits it. Even if allowed, it is not backwards compatible with pre-1.8.4 IDE versions.
Library Manager strips leading and trailing whitespace from metadata values so it's unclear whether the prohibition against starting or ending with a space is real. The question is whether the indexer also strips spaces. I have not seen any case of a library failing to be added to the index due to this restriction so that makes me think it is not real.
The IDE does not prohibit any of these characters in the name value of libraries installed via "Add .ZIP Library..." or manually installed. So these restrictions are exclusively for Library Manager installations.
Relevant, but unclear: https://github.com/arduino/Arduino/issues/6753#issuecomment-333476054
version (required)
Invalid format
version value is split by - (semver pre-release syntax) or + (semver build syntax).
If first part is shorter than x.y.z then it's padded with zeros (e.g. x.y -> x.y.0).
This will really only be of concern for libraries in Library Manager. Any other library would probably not want to deal with it since it's already locked into history.
It's common to use the vX.Y.Z form for the tag name but the X.Y.Z form for the version value.
author (required)
maintainer (required unless there is an email field)
Since the email field is not in the specification this is not guaranteed to continue working.
sentence (required)
paragraph (required)
should not contain a repeat of sentence (since paragraph is appended to sentence in the Library Manager entry).
category (causes "Invalid category ''" warning if missing)
Invalid value
Category value other than the valid category list will cause a warning on every compilation.
Although not on the list, Uncategorized is also valid.
It is case-sensitive.
url (required)
missing scheme (http:// or https://) on the url value. This causes the More info link to not be clickable
Confirmed only with a .co URL so it should be checked on .com to make sure the issue persists
Visit URL to check if it's dead.
architectures (optional)
Check against a list of known-good values.
I think I can get this from arduino-libraries.info
Values are case-sensitive (generally lower case).
includes (optional)
Empty definition
Causes #include <> to be added to the sketch when you do Sketch > Include Library.
Set to a file name that doesn't exist in the repo or file that does exist but not in the stated path.
It might be for an external dependency but #include directives in sketches for dependencies of a library aren't necessary with any IDE version that supports the includes field so there is no point to doing that.
Filename case must be correct
This is even true on filename case insensitive OS like Windows
dot_a_linkage (optional)
What happens if it's set to something other than true?
I found no problems with values true or asdf.
precompiled (optional)
What happens if it's set to something other than true?
per1234
commented
6 years ago
=(even as the first character) or start with#(verified).Property line ... in file ... is invalid.paragraphvalue into multiple lines by escaping the newline. That doesn't work. You can use<br>or<br/>instead.name(required)namevalue is used to determine the folder name for libraries installed via Library Manager. For this reason, the Library Manager indexer requires thenamevalue to follow the same folder name restrictions as are imposed on sketch and library folder names, with the exception that spaces are allowed (they are replaced by_in the folder name).namevalue of libraries installed via "Add .ZIP Library..." or manually installed. So these restrictions are exclusively for Library Manager installations.https://github.com/arduino/Arduino/issues/6753#issuecomment-333476054version(required)versionvalue is split by-(semver pre-release syntax) or+(semver build syntax).versionvalue is reassembled and checked for semver compliance.versionvalue.author(required)maintainer(required unless there is anemailfield)emailfield is not in the specification this is not guaranteed to continue working.sentence(required)paragraph(required)category(causes "Invalid category ''" warning if missing)Uncategorizedis also valid.url(required)architectures(optional)includes(optional)#include <>to be added to the sketch when you do Sketch > Include Library.#includedirectives in sketches for dependencies of a library aren't necessary with any IDE version that supports theincludesfield so there is no point to doing that.dot_a_linkage(optional)true?trueorasdf.precompiled(optional)true?trueorasdf.