Skip to content

Check library.properties #21

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.

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

Closed
per1234 opened this issue Feb 24, 2018 · 1 comment
Closed

Check library.properties #21

per1234 opened this issue Feb 24, 2018 · 1 comment

Comments

@per1234
Copy link
Owner

per1234 commented Feb 24, 2018

  • 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).
        • The version value is reassembled and checked for semver compliance.
      • Value vs git tag mismatch
        • 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?
        • I found no problems with values true or asdf.
@per1234
Copy link
Owner Author

per1234 commented Sep 12, 2018

Resolved by 18d551c

@per1234 per1234 closed this as completed Sep 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant