From 9e9cabee6945ce92adbfbbef1a76da2192fb58ed Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 01:41:39 -0700 Subject: [PATCH 01/11] Import Library Manager FAQ An FAQ hosted in the `arduino/Arduino` repository's wiki: https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ has long served as the canonical guide for the traditional process for submitting libraries to the Library Manager index. Now that the submission process and support for the process has been moved from `arduino/Arduino` to this dedicated repository, it makes sense to also host the FAQ content here. This commit imports the exact unmodified content of the FAQ from https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ/819425389e31540acee60eac9d1ade894659bf57 --- FAQ.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 14 ++++---- 2 files changed, 103 insertions(+), 6 deletions(-) create mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 00000000..a9ed9441 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,95 @@ +### Library Manager overview + +The Arduino Library Manager is a feature of the Arduino IDE (Sketch > Include Library > Manage Libraries...) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. More information: \ +https://www.arduino.cc/en/Guide/Libraries#toc3 + +### How is the library list generated? + +From a list of public Git repos, a job (a small program that runs regularly) fetches every tag, verifies library files and pushes the updated [list](http://downloads.arduino.cc/libraries/library_index.json) onto the Arduino download server. +Only valid libraries and their tags are published. A library is **not valid** when: +* it's not in [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification) and in particular it misses a [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata) file (1.5 format folder layout is not required) +* its `name` field in library.properties starts with `Arduino` +* its `url` field in library.properties is left blank +* its version number is not [semver compliant](http://semver.org/) +* it contains `.exe` files +* it contains a `.development` file +* it contains symlinks +* our antivirus finds infected files + +**The job runs every hour. If a new library has been released, you can expect it to be listed within the hour, but it might take longer**. + +Arduino has created a command line tool to check libraries for compliance with all the Library Manager requirements: + +https://github.com/arduino/arduino-lint + +Arduino Lint is also available as a GitHub Actions action that can be used in the CI systems of Arduino library repositories to ensure continued compliance: + +https://github.com/arduino/arduino-lint-action + +### How can I add my library to Library Manager? + +* Your library repository must be hosted on a major git-hosting website like GitHub, BitBucket or GitLab (other hosting site may be considered on request). +* Ensure your library is compliant with [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification/) (1.5 format folder layout is not required) +* Your library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index. +* [Tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it and push the tag (or create a release if you web hosting offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/)) +* Open an issue on [Arduino's GitHub](https://github.com/arduino/Arduino/issues), specifying the URL of the repository from where to download your library. If you have multiple libraries to submit you are welcome to do them all in a single issue. +* After some days, a member of the Arduino team will add your library to the Library Manager index and close the issue. Shortly after that your library will be available for installation via Library Manager. + +### How can I publish a new release once my library is in the list? + +Ensure you've changed version in your `library.properties`. Then tag your library once more and push the new tag (or create a release if your web hosting offers a way to do it, for example with GitHub "releases"). +Our indexer checks for new releases every hour and will eventually fetch and publish your new release. + +### Sorry, I did something wrong! How can I change or unpublish an already published library? + +In order to change contents of an already published library version, you can recreate its related tag. + +In order to **un**publish a library version, delete its related tag/release. + +Once you have done that, open an issue on [Arduino's GitHub](https://github.com/arduino/Arduino/issues), specifying the URL of the library repository and requesting that the library be updated. + +### Why aren't releases of my library being picked up by Library Manager? + +The Library Manager indexer job will not pick up releases which don't have a unique `version` value in library.properties. Remember to always update the `version` value in your library.properties *before* creating the tag or release. + +Make sure your library meets all the requirements listed [here](#how-is-the-library-list-generated). + +Changing the `name` value in your library.properties from the one it had at the time when the library was added to the Library Manager index will cause releases to be ignored. You need to request a name change, as explained [here](#how-can-i-change-my-librarys-name). + +### How can I change my library's name? + +For the sake of continuity, libraries in the Library Manager list are locked in to the name they had at the time they were added to the list. If you wish to change the name it will need to be done manually by request: +1. Change the `name` value in your [library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) and update the `version`. +1. Create a release or tag that matches the updated `version` value in library.properties. +1. Submit an [issue report](https://github.com/arduino/Arduino/issues/new) requesting the name be changed and the URL of your library's repository. + +### How can I delete a library? + +Open your sketchbook "libraries" folder with your OS file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing your library. + +##### Rationale + +No, we don't have a delete button. Libraries managed by the Library Manager are mixed with those you've manually installed, maybe libraries you've written: making a mistake and deleting the wrong library is too easy. That's why trash bins exist. Since the IDE has no knowledge of your trash bin, we didn't implement a "delete" button. + +## Limitations + +### Is my Git repo OK? + +Your repo is OK if its root folder contains the file `library.properties` and the rest of the library source code. If your library is stored in a subfolder, your repo is not OK and we can't include your library in the list. + +### Are Git submodules supported? + +No. The library archive distributed by Library Manager will only contain an empty folder where the submodule should be. + +### Can I add my own URL with my own library list? + +No. At the moment, the IDE handles one URL only, and that's written into the code (dev jargon: it's hardcoded), this is a known limitation. +However, if you know your way through the code, you can change that URL with another one. + +### When I install a library that I know depends on another library, will this other library be installed as well? + +You can specify the dependencies of your library in the `depends` field of library.properties. As of Arduino IDE 1.8.10, the user will be prompted to install those libraries when they install your library via Library Manager. For more information, see the [library.properties file format documentation](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format). + +### Can I install multiple versions of one library and use the proper one in my sketches? + +Library Manager installs libraries into your sketchbook "libraries" folder. Since you cannot create two folders with the same name, we can't install two versions of the same library. However, you can switch between library versions, by selecting the appropriate one from the version dropdown that pops up on Library Manager when more than one version is available. diff --git a/README.md b/README.md index f7096909..c709c859 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,10 @@ This repository contains the list of libraries in the [Arduino Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) index. +## Frequently asked questions + +For more information about Arduino Library Manager and how the index is maintained, please see [the FAQ](FAQ.md). + ## Adding a library to Library Manager If you would like to have your library available for installation via Library Manager, just submit a @@ -14,8 +18,8 @@ See the instructions below for detailed instructions on how to do this via the G ### Instructions 1. You may want to first take a look at - [the requirements for admission into the Arduino Library Manager index](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ). - Each submission will be checked for compliance before being accepted. + [the requirements for admission into the Arduino Library Manager index](FAQ.md). Each submission will be checked for + compliance before being accepted. 1. Open this link to [fork](https://guides.github.com/activities/forking/) this repository and edit the list via the GitHub web interface: https://github.com/arduino/library-registry/edit/main/repositories.txt 1. Add the library repository's URL to the list. This should be the URL of the repository home page. For example: @@ -70,10 +74,8 @@ description, making it clear that the URL is intentionally being removed. ## Report a problem with Library Manager -Please first take a look at -[the Arduino Library Manager FAQ](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ). If a library release is -missing from Library Manager, it is usually because it was not compliant with all the requirements listed in that -document. +Please first take a look at [the FAQ](FAQ.md). If a library release is missing from Library Manager, it is usually +because it was not compliant with all the requirements listed in that document. This repository is not an appropriate place to request support or report problems with a library. Check the library's own documentation for instructions or ask on the [Arduino Forum](https://forum.arduino.cc/). From d5ca56191f74982d2319105a1ff7fd15601401fd Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 02:21:25 -0700 Subject: [PATCH 02/11] Improve formatting of FAQ - Add page title - Bring into Prettier compliance - Minor manual formatting to improve readability --- FAQ.md | 46 ++++++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/FAQ.md b/FAQ.md index a9ed9441..a989f31e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,20 +1,25 @@ +# Arduino Library Manager FAQ + ### Library Manager overview -The Arduino Library Manager is a feature of the Arduino IDE (Sketch > Include Library > Manage Libraries...) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. More information: \ +The Arduino Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list, every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. More information:
https://www.arduino.cc/en/Guide/Libraries#toc3 ### How is the library list generated? From a list of public Git repos, a job (a small program that runs regularly) fetches every tag, verifies library files and pushes the updated [list](http://downloads.arduino.cc/libraries/library_index.json) onto the Arduino download server. -Only valid libraries and their tags are published. A library is **not valid** when: -* it's not in [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification) and in particular it misses a [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata) file (1.5 format folder layout is not required) -* its `name` field in library.properties starts with `Arduino` -* its `url` field in library.properties is left blank -* its version number is not [semver compliant](http://semver.org/) -* it contains `.exe` files -* it contains a `.development` file -* it contains symlinks -* our antivirus finds infected files +Only valid libraries and their tags are published. + +A library is **not valid** when: + +- it's not in [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification) and in particular it misses a [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata) file (1.5 format folder layout is not required) +- its `name` field in library.properties starts with `Arduino` +- its `url` field in library.properties is left blank +- its version number is not [semver compliant](http://semver.org/) +- it contains `.exe` files +- it contains a `.development` file +- it contains symlinks +- our antivirus finds infected files **The job runs every hour. If a new library has been released, you can expect it to be listed within the hour, but it might take longer**. @@ -28,12 +33,12 @@ https://github.com/arduino/arduino-lint-action ### How can I add my library to Library Manager? -* Your library repository must be hosted on a major git-hosting website like GitHub, BitBucket or GitLab (other hosting site may be considered on request). -* Ensure your library is compliant with [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification/) (1.5 format folder layout is not required) -* Your library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index. -* [Tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it and push the tag (or create a release if you web hosting offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/)) -* Open an issue on [Arduino's GitHub](https://github.com/arduino/Arduino/issues), specifying the URL of the repository from where to download your library. If you have multiple libraries to submit you are welcome to do them all in a single issue. -* After some days, a member of the Arduino team will add your library to the Library Manager index and close the issue. Shortly after that your library will be available for installation via Library Manager. +- Your library repository must be hosted on a major Git-hosting website like GitHub, BitBucket or GitLab (other hosting sites may be considered on request). +- Ensure your library is compliant with [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification/) (1.5 format folder layout is not required) +- Your library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index. +- [Tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it and push the tag (or create a release if you web hosting offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/)) +- Open an issue on [Arduino's GitHub](https://github.com/arduino/Arduino/issues), specifying the URL of the repository from where to download your library. If you have multiple libraries to submit you are welcome to do them all in a single issue. +- After some days, a member of the Arduino team will add your library to the Library Manager index and close the issue. Shortly after that your library will be available for installation via Library Manager. ### How can I publish a new release once my library is in the list? @@ -50,7 +55,7 @@ Once you have done that, open an issue on [Arduino's GitHub](https://github.com/ ### Why aren't releases of my library being picked up by Library Manager? -The Library Manager indexer job will not pick up releases which don't have a unique `version` value in library.properties. Remember to always update the `version` value in your library.properties *before* creating the tag or release. +The Library Manager indexer job will not pick up releases which don't have a unique `version` value in library.properties. Remember to always update the `version` value in your library.properties _before_ creating the tag or release. Make sure your library meets all the requirements listed [here](#how-is-the-library-list-generated). @@ -59,13 +64,14 @@ Changing the `name` value in your library.properties from the one it had at the ### How can I change my library's name? For the sake of continuity, libraries in the Library Manager list are locked in to the name they had at the time they were added to the list. If you wish to change the name it will need to be done manually by request: + 1. Change the `name` value in your [library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) and update the `version`. 1. Create a release or tag that matches the updated `version` value in library.properties. 1. Submit an [issue report](https://github.com/arduino/Arduino/issues/new) requesting the name be changed and the URL of your library's repository. ### How can I delete a library? -Open your sketchbook "libraries" folder with your OS file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing your library. +Open your sketchbook's `libraries` folder with your OS file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing your library. ##### Rationale @@ -88,8 +94,8 @@ However, if you know your way through the code, you can change that URL with ano ### When I install a library that I know depends on another library, will this other library be installed as well? -You can specify the dependencies of your library in the `depends` field of library.properties. As of Arduino IDE 1.8.10, the user will be prompted to install those libraries when they install your library via Library Manager. For more information, see the [library.properties file format documentation](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format). +You can specify the dependencies of your library in the `depends` field of library.properties. As of Arduino IDE 1.8.10, the user will be prompted to install those libraries when they install your library via Library Manager. For more information, see the [`library.properties` file format documentation](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format). ### Can I install multiple versions of one library and use the proper one in my sketches? -Library Manager installs libraries into your sketchbook "libraries" folder. Since you cannot create two folders with the same name, we can't install two versions of the same library. However, you can switch between library versions, by selecting the appropriate one from the version dropdown that pops up on Library Manager when more than one version is available. +Library Manager installs libraries into your sketchbook's `libraries` folder. Since you cannot create two folders with the same name, we can't install two versions of the same library. However, you can switch between library versions by selecting the appropriate one from the version dropdown that pops up on Library Manager when more than one version is available. From 616c3b51107629057280e690db8484148f94b05d Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 03:38:55 -0700 Subject: [PATCH 03/11] Update FAQ content to reflect new submission and support procedures --- FAQ.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/FAQ.md b/FAQ.md index a989f31e..c20d6134 100644 --- a/FAQ.md +++ b/FAQ.md @@ -37,8 +37,9 @@ https://github.com/arduino/arduino-lint-action - Ensure your library is compliant with [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification/) (1.5 format folder layout is not required) - Your library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index. - [Tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it and push the tag (or create a release if you web hosting offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/)) -- Open an issue on [Arduino's GitHub](https://github.com/arduino/Arduino/issues), specifying the URL of the repository from where to download your library. If you have multiple libraries to submit you are welcome to do them all in a single issue. -- After some days, a member of the Arduino team will add your library to the Library Manager index and close the issue. Shortly after that your library will be available for installation via Library Manager. +- Follow the submission instructions [here](README.md#adding-a-library-to-library-manager). + +Shortly after the pull request is merged by the automated system, your library will be available for installation via Library Manager. ### How can I publish a new release once my library is in the list? @@ -51,7 +52,7 @@ In order to change contents of an already published library version, you can rec In order to **un**publish a library version, delete its related tag/release. -Once you have done that, open an issue on [Arduino's GitHub](https://github.com/arduino/Arduino/issues), specifying the URL of the library repository and requesting that the library be updated. +Once you have done that, open an issue in [the issue tracker of this repository](https://github.com/arduino/library-registry/issues), specifying the URL of the library repository and requesting that the library be updated. ### Why aren't releases of my library being picked up by Library Manager? @@ -67,7 +68,7 @@ For the sake of continuity, libraries in the Library Manager list are locked in 1. Change the `name` value in your [library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) and update the `version`. 1. Create a release or tag that matches the updated `version` value in library.properties. -1. Submit an [issue report](https://github.com/arduino/Arduino/issues/new) requesting the name be changed and the URL of your library's repository. +1. Submit an [issue report](https://github.com/arduino/library-registry/issues) requesting the name be changed and the URL of your library's repository. ### How can I delete a library? From beb45f13df1ef5bea9f6c5c489e917a7737ab04d Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 04:35:40 -0700 Subject: [PATCH 04/11] Consolidate list of requirements in FAQ It is essential to clearly communicate the Library Manager requirements to the submitters. Previously, these requirements were scattered throughout the FAQ. Consolidating them into unified lists, then referencing that information from the other parts of the documentation makes it easier for the user to learn what are the requirements and easier for the documentation to be maintained. --- FAQ.md | 63 ++++++++++++++++++++++++++++++------------------------- README.md | 4 ++-- 2 files changed, 37 insertions(+), 30 deletions(-) diff --git a/FAQ.md b/FAQ.md index c20d6134..36bbf9de 100644 --- a/FAQ.md +++ b/FAQ.md @@ -5,23 +5,22 @@ The Arduino Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list, every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. More information:
https://www.arduino.cc/en/Guide/Libraries#toc3 -### How is the library list generated? -From a list of public Git repos, a job (a small program that runs regularly) fetches every tag, verifies library files and pushes the updated [list](http://downloads.arduino.cc/libraries/library_index.json) onto the Arduino download server. -Only valid libraries and their tags are published. +### What are the requirements for a library to be added to the Library Manager index? -A library is **not valid** when: + -- it's not in [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification) and in particular it misses a [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata) file (1.5 format folder layout is not required) -- its `name` field in library.properties starts with `Arduino` -- its `url` field in library.properties is left blank -- its version number is not [semver compliant](http://semver.org/) -- it contains `.exe` files -- it contains a `.development` file -- it contains symlinks -- our antivirus finds infected files - -**The job runs every hour. If a new library has been released, you can expect it to be listed within the hour, but it might take longer**. +- [ ] The library must be fully compliant with the [Arduino Library Specification](https://arduino.github.io/arduino-cli/latest/library-specification). +- [ ] The library must have [a library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata), in compliance with the Arduino Library 1.5 format. +- [ ] The library.properties file must be located in the root of the repository. +- [ ] The library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index. +- [ ] For 3rd party libraries, the `name` field in library.properties must not start with `Arduino`. +- [ ] The library repository must not contain any `.exe` files. +- [ ] The library repository must not contain a [`.development` file](https://arduino.github.io/arduino-cli/latest/library-specification/#development-flag-file). +- [ ] The library repository must not contain any [symlinks](https://en.wikipedia.org/wiki/Symbolic_link). +- [ ] The library repository must not contain any files detected as infected by our antivirus scan. +- [ ] The library repository must have a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) (or [release](https://help.github.com/articles/creating-releases/)) and must have been compliant with all the above requirements at the time of that tag. +- [ ] The library repository must be hosted on a major Git-hosting website like GitHub, BitBucket or GitLab (other hosting sites may be considered on request). Arduino has created a command line tool to check libraries for compliance with all the Library Manager requirements: @@ -31,21 +30,33 @@ Arduino Lint is also available as a GitHub Actions action that can be used in th https://github.com/arduino/arduino-lint-action +### How is the library list generated? + +From a list of public Git repos, a job (a small program that runs regularly) fetches every tag, checks compliance with [the requirements](#requirements), and pushes the updated [list](http://downloads.arduino.cc/libraries/library_index.json) onto the Arduino download server. +Only valid libraries and their tags are published. + +**The job runs every hour. If a new library has been released, you can expect it to be listed within the hour, but it might take longer**. + ### How can I add my library to Library Manager? -- Your library repository must be hosted on a major Git-hosting website like GitHub, BitBucket or GitLab (other hosting sites may be considered on request). -- Ensure your library is compliant with [1.5 format](https://arduino.github.io/arduino-cli/latest/library-specification/) (1.5 format folder layout is not required) -- Your library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index. -- [Tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it and push the tag (or create a release if you web hosting offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/)) -- Follow the submission instructions [here](README.md#adding-a-library-to-library-manager). - -Shortly after the pull request is merged by the automated system, your library will be available for installation via Library Manager. +Follow the submission instructions [here](README.md#adding-a-library-to-library-manager). ### How can I publish a new release once my library is in the list? -Ensure you've changed version in your `library.properties`. Then tag your library once more and push the new tag (or create a release if your web hosting offers a way to do it, for example with GitHub "releases"). +1. Make sure the library is compliant with [all requirements](#update-requirements). +1. Update the `version` in your `library.properties`. +1. Tag your library once more and push the new tag (or create a release if your web hosting offers a way to do it, for example with GitHub "releases"). + Our indexer checks for new releases every hour and will eventually fetch and publish your new release. +### What are the requirements for publishing new releases of libraries already in the Library Manager index? + + + +- [ ] The library must be compliant with all the same [requirements that apply to submissions](#submission-requirements). +- [ ] The `name` property in library.properties must not have changed from the value it had when the library was submitted. If you must change the library name, see [this](#how-can-i-change-my-librarys-name). +- [ ] The `version` property in library.properties must not be the same as it was in a tag previously added to the Library Manager index. + ### Sorry, I did something wrong! How can I change or unpublish an already published library? In order to change contents of an already published library version, you can recreate its related tag. @@ -56,11 +67,7 @@ Once you have done that, open an issue in [the issue tracker of this repository] ### Why aren't releases of my library being picked up by Library Manager? -The Library Manager indexer job will not pick up releases which don't have a unique `version` value in library.properties. Remember to always update the `version` value in your library.properties _before_ creating the tag or release. - -Make sure your library meets all the requirements listed [here](#how-is-the-library-list-generated). - -Changing the `name` value in your library.properties from the one it had at the time when the library was added to the Library Manager index will cause releases to be ignored. You need to request a name change, as explained [here](#how-can-i-change-my-librarys-name). +The Library Manager indexer job will reject any releases which aren't compliant with all [the requirements](#update-requirements). ### How can I change my library's name? @@ -82,7 +89,7 @@ No, we don't have a delete button. Libraries managed by the Library Manager are ### Is my Git repo OK? -Your repo is OK if its root folder contains the file `library.properties` and the rest of the library source code. If your library is stored in a subfolder, your repo is not OK and we can't include your library in the list. +Your repo is OK if it meets all [the requirements listed here](#submission-requirements). ### Are Git submodules supported? diff --git a/README.md b/README.md index c709c859..3d66f1dc 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ See the instructions below for detailed instructions on how to do this via the G ### Instructions 1. You may want to first take a look at - [the requirements for admission into the Arduino Library Manager index](FAQ.md). Each submission will be checked for + [the requirements for admission into the Arduino Library Manager index](FAQ.md#submission-requirements). Each submission will be checked for compliance before being accepted. 1. Open this link to [fork](https://guides.github.com/activities/forking/) this repository and edit the list via the GitHub web interface: https://github.com/arduino/library-registry/edit/main/repositories.txt @@ -75,7 +75,7 @@ description, making it clear that the URL is intentionally being removed. ## Report a problem with Library Manager Please first take a look at [the FAQ](FAQ.md). If a library release is missing from Library Manager, it is usually -because it was not compliant with all the requirements listed in that document. +because it was not compliant with all [the requirements](FAQ.md#update-requirements) listed in that document. This repository is not an appropriate place to request support or report problems with a library. Check the library's own documentation for instructions or ask on the [Arduino Forum](https://forum.arduino.cc/). From ddd8c7d47791f428b04b47f57e16193f64afc6a9 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 06:15:55 -0700 Subject: [PATCH 05/11] Disambiguate Library Manager list vs index terminology Previously, library submitters were not exposed to the internal workings of the Library Manager index generation system, so they only needed to be concern with the public index file. Now the submitters will be interacting directly with the Library Manager submission list. This might lead to some confusion between that list and the Library Manager index, so it's important to be clear in the terminology used in the documentation. --- FAQ.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/FAQ.md b/FAQ.md index 36bbf9de..0d755f69 100644 --- a/FAQ.md +++ b/FAQ.md @@ -5,15 +5,14 @@ The Arduino Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list, every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. More information:
https://www.arduino.cc/en/Guide/Libraries#toc3 - -### What are the requirements for a library to be added to the Library Manager index? +### What are the requirements for a library to be added to Library Manager? - [ ] The library must be fully compliant with the [Arduino Library Specification](https://arduino.github.io/arduino-cli/latest/library-specification). - [ ] The library must have [a library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata), in compliance with the Arduino Library 1.5 format. - [ ] The library.properties file must be located in the root of the repository. -- [ ] The library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager index. +- [ ] The library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager list. - [ ] For 3rd party libraries, the `name` field in library.properties must not start with `Arduino`. - [ ] The library repository must not contain any `.exe` files. - [ ] The library repository must not contain a [`.development` file](https://arduino.github.io/arduino-cli/latest/library-specification/#development-flag-file). @@ -30,12 +29,16 @@ Arduino Lint is also available as a GitHub Actions action that can be used in th https://github.com/arduino/arduino-lint-action -### How is the library list generated? +### How is the Library Manager index generated? -From a list of public Git repos, a job (a small program that runs regularly) fetches every tag, checks compliance with [the requirements](#requirements), and pushes the updated [list](http://downloads.arduino.cc/libraries/library_index.json) onto the Arduino download server. -Only valid libraries and their tags are published. +[The Library Manager index](http://downloads.arduino.cc/libraries/library_index.json) contains the data for every release of every one of the thousands of libraries that have been added to the Library Manager list. This index is used by Library Manager to provide installation and updates of the libraries as well as to generate automated documentation pages for the [Arduino Library Reference](https://www.arduino.cc/reference/en/libraries/). -**The job runs every hour. If a new library has been released, you can expect it to be listed within the hour, but it might take longer**. +Every hour, the automated Library Manager indexer system: + +1. checks every repository in the Library Manager list for new tags +1. checks whether those tags meet [the requirements for addition to the index](#update-requirements) +1. adds entries to the index for compliant tags +1. pushes the updated index to Arduino's download server ### How can I add my library to Library Manager? @@ -47,9 +50,9 @@ Follow the submission instructions [here](README.md#adding-a-library-to-library- 1. Update the `version` in your `library.properties`. 1. Tag your library once more and push the new tag (or create a release if your web hosting offers a way to do it, for example with GitHub "releases"). -Our indexer checks for new releases every hour and will eventually fetch and publish your new release. +[Our indexer](#how-is-the-library-manager-index-generated) checks for new releases every hour and will eventually fetch and publish your new release. -### What are the requirements for publishing new releases of libraries already in the Library Manager index? +### What are the requirements for publishing new releases of libraries already in the Library Manager list? @@ -95,7 +98,7 @@ Your repo is OK if it meets all [the requirements listed here](#submission-requi No. The library archive distributed by Library Manager will only contain an empty folder where the submodule should be. -### Can I add my own URL with my own library list? +### Can I add my own URL with my own library index? No. At the moment, the IDE handles one URL only, and that's written into the code (dev jargon: it's hardcoded), this is a known limitation. However, if you know your way through the code, you can change that URL with another one. From ca3a07811e727e83ac5c82528d65b3617b70afb5 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 06:34:25 -0700 Subject: [PATCH 06/11] Explain impacts of changing library name in FAQ --- FAQ.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/FAQ.md b/FAQ.md index 0d755f69..dce6fb1e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -74,7 +74,9 @@ The Library Manager indexer job will reject any releases which aren't compliant ### How can I change my library's name? -For the sake of continuity, libraries in the Library Manager list are locked in to the name they had at the time they were added to the list. If you wish to change the name it will need to be done manually by request: +For the sake of continuity, libraries in the Library Manager list are locked to the name they had at the time they were added to the list. Changing the library name can be disruptive to its users because this is the unique identifier for the library used by the Arduino development software [command line interfaces](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib/), sketch [metadata](https://arduino.github.io/arduino-cli/latest/sketch-specification/#metadata), library [dependencies](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format), and installation location. + +If you wish to change the name it will need to be done manually by request: 1. Change the `name` value in your [library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) and update the `version`. 1. Create a release or tag that matches the updated `version` value in library.properties. From d7d89ff94ad30e643e94305dc18b8d38e3046017 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 07:07:39 -0700 Subject: [PATCH 07/11] Reword title of LM overview in FAQ as a question This document is a collection of frequently asked questions, so it makes most sense for all entries to be phrased as questions. --- FAQ.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FAQ.md b/FAQ.md index dce6fb1e..3e118dcd 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,6 +1,6 @@ # Arduino Library Manager FAQ -### Library Manager overview +### What is the Arduino Library Manager? The Arduino Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list, every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. More information:
https://www.arduino.cc/en/Guide/Libraries#toc3 From f6fb08abd176ed7aa6e5857c378c56a67015f512 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 07:08:53 -0700 Subject: [PATCH 08/11] Reword FAQ text to improve readability A general pass of minor rewording. --- FAQ.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/FAQ.md b/FAQ.md index 3e118dcd..a65e14f7 100644 --- a/FAQ.md +++ b/FAQ.md @@ -2,7 +2,11 @@ ### What is the Arduino Library Manager? -The Arduino Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. When your library is added to the library list, every release/tag version of the library in your repository will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. More information:
+Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. + +When a library is [added to the library list](README.md#adding-a-library-to-library-manager), every release of the library will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. + +More information:
https://www.arduino.cc/en/Guide/Libraries#toc3 ### What are the requirements for a library to be added to Library Manager? @@ -42,13 +46,13 @@ Every hour, the automated Library Manager indexer system: ### How can I add my library to Library Manager? -Follow the submission instructions [here](README.md#adding-a-library-to-library-manager). +Follow the instructions [here](README.md#adding-a-library-to-library-manager). ### How can I publish a new release once my library is in the list? 1. Make sure the library is compliant with [all requirements](#update-requirements). -1. Update the `version` in your `library.properties`. -1. Tag your library once more and push the new tag (or create a release if your web hosting offers a way to do it, for example with GitHub "releases"). +1. Update the `version` in your [`library.properties`](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata)). +1. Tag your library once more and push the new tag (or create a release if your Git-hosting site offers a way to do it, for example with [GitHub "releases"](https://help.github.com/articles/creating-releases/)). [Our indexer](#how-is-the-library-manager-index-generated) checks for new releases every hour and will eventually fetch and publish your new release. @@ -60,7 +64,7 @@ Follow the submission instructions [here](README.md#adding-a-library-to-library- - [ ] The `name` property in library.properties must not have changed from the value it had when the library was submitted. If you must change the library name, see [this](#how-can-i-change-my-librarys-name). - [ ] The `version` property in library.properties must not be the same as it was in a tag previously added to the Library Manager index. -### Sorry, I did something wrong! How can I change or unpublish an already published library? +### I did something wrong! How can I change or unpublish an already published library? In order to change contents of an already published library version, you can recreate its related tag. @@ -79,20 +83,20 @@ For the sake of continuity, libraries in the Library Manager list are locked to If you wish to change the name it will need to be done manually by request: 1. Change the `name` value in your [library.properties file](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) and update the `version`. -1. Create a release or tag that matches the updated `version` value in library.properties. -1. Submit an [issue report](https://github.com/arduino/library-registry/issues) requesting the name be changed and the URL of your library's repository. +1. Create a release or tag. +1. Submit an [issue report](https://github.com/arduino/library-registry/issues) requesting the name be changed and stating the URL of your library's repository. -### How can I delete a library? +### How can I remove a library I installed via Library Manager? -Open your sketchbook's `libraries` folder with your OS file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing your library. +Open your sketchbook's `libraries` folder with your operating system's file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing the library. ##### Rationale -No, we don't have a delete button. Libraries managed by the Library Manager are mixed with those you've manually installed, maybe libraries you've written: making a mistake and deleting the wrong library is too easy. That's why trash bins exist. Since the IDE has no knowledge of your trash bin, we didn't implement a "delete" button. +No, we don't have a delete button. Libraries managed by the Library Manager are mixed with those you've manually installed, maybe libraries you've written: making a mistake and deleting the wrong library is too easy. That's why Trash bins exist. Since the IDE has no knowledge of your Trash bin, we didn't implement a "delete" button. ## Limitations -### Is my Git repo OK? +### Is my Git repository OK? Your repo is OK if it meets all [the requirements listed here](#submission-requirements). From cab7e9a446b1b2df71fcca7d3b878138f1f223dd Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 07:44:42 -0700 Subject: [PATCH 09/11] Make FAQ content applicable to all official Arduino development software At the time it was created, there was only one official Arduino development application: Arduino IDE. Since that time, Arduino Web Editor and Arduino CLI have been created, both of which implement Library Manager in their own manners. --- FAQ.md | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/FAQ.md b/FAQ.md index a65e14f7..f8c10f38 100644 --- a/FAQ.md +++ b/FAQ.md @@ -2,12 +2,19 @@ ### What is the Arduino Library Manager? -Library Manager is a feature of the Arduino IDE (**Sketch > Include Library > Manage Libraries...**) which makes it easy for users to find, install, and update both official and 3rd party libraries. +Library Manager is a feature of the Arduino development software which makes it easy for users to find, install, and update both official and 3rd party libraries. -When a library is [added to the library list](README.md#adding-a-library-to-library-manager), every release of the library will automatically be made available for installation via Library Manager. The users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. +- In the Arduino IDE: **Sketch > Include Library > Manage Libraries...** +- In Arduino CLI: `arduino-cli lib --help` +- In Arduino Web Editor: all Library Manager libraries are pre-installed. -More information:
-https://www.arduino.cc/en/Guide/Libraries#toc3 +When a library is [added to the library list](README.md#adding-a-library-to-library-manager), every release of the library will automatically be made available for installation via Library Manager. Users can set their preferences to display an update notification when a new version of any installed library on the list is available and easily update to the new version with just a couple clicks. + +More information: + +- https://www.arduino.cc/en/Guide/Libraries#toc3 +- https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib/ +- https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a ### What are the requirements for a library to be added to Library Manager? @@ -88,11 +95,17 @@ If you wish to change the name it will need to be done manually by request: ### How can I remove a library I installed via Library Manager? -Open your sketchbook's `libraries` folder with your operating system's file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing the library. +#### Arduino IDE 2.x -##### Rationale +Hover the mouse pointer over the "INSTALLED" label on the library listing in Library Manager. It will now change to "UNINSTALL", which you can click to uninstall that library. -No, we don't have a delete button. Libraries managed by the Library Manager are mixed with those you've manually installed, maybe libraries you've written: making a mistake and deleting the wrong library is too easy. That's why Trash bins exist. Since the IDE has no knowledge of your Trash bin, we didn't implement a "delete" button. +#### Classic Arduino IDE + +This version of the Arduino IDE does not have an integrated uninstall functionality, so you will need to remove the library manually. Open your sketchbook's `libraries` folder with your operating system's file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing the library. + +#### Arduino CLI + +Libraries can be uninstalled via [the `arduino-cli lib uninstall` command](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib_uninstall/). ## Limitations @@ -106,12 +119,14 @@ No. The library archive distributed by Library Manager will only contain an empt ### Can I add my own URL with my own library index? -No. At the moment, the IDE handles one URL only, and that's written into the code (dev jargon: it's hardcoded), this is a known limitation. +No. At the moment, the Arduino development software handles one URL only, and that's written into the code (dev jargon: it's hardcoded), this is a known limitation. However, if you know your way through the code, you can change that URL with another one. ### When I install a library that I know depends on another library, will this other library be installed as well? -You can specify the dependencies of your library in the `depends` field of library.properties. As of Arduino IDE 1.8.10, the user will be prompted to install those libraries when they install your library via Library Manager. For more information, see the [`library.properties` file format documentation](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format). +As of Arduino IDE 1.8.10 and Arduino CLI 0.7.0, you can specify the dependencies of your library in the `depends` field of library.properties. Those libraries can be installed automatically when someone installs your library via Library Manager. + +For more information, see the [`library.properties` file format documentation](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format). ### Can I install multiple versions of one library and use the proper one in my sketches? From 2d79e0e492d8a01725156f412fd73e7c723b9b64 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 07:51:20 -0700 Subject: [PATCH 10/11] Reorder the FAQs Organize the questions accordging to type and importance. --- FAQ.md | 72 ++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 40 insertions(+), 32 deletions(-) diff --git a/FAQ.md b/FAQ.md index f8c10f38..923712e0 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,7 @@ # Arduino Library Manager FAQ +## General + ### What is the Arduino Library Manager? Library Manager is a feature of the Arduino development software which makes it easy for users to find, install, and update both official and 3rd party libraries. @@ -16,6 +18,23 @@ More information: - https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib/ - https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a +### How is the Library Manager index generated? + +[The Library Manager index](http://downloads.arduino.cc/libraries/library_index.json) contains the data for every release of every one of the thousands of libraries that have been added to the Library Manager list. This index is used by Library Manager to provide installation and updates of the libraries as well as to generate automated documentation pages for the [Arduino Library Reference](https://www.arduino.cc/reference/en/libraries/). + +Every hour, the automated Library Manager indexer system: + +1. checks every repository in the Library Manager list for new tags +1. checks whether those tags meet [the requirements for addition to the index](#update-requirements) +1. adds entries to the index for compliant tags +1. pushes the updated index to Arduino's download server + +## Submission + +### How can I add my library to Library Manager? + +Follow the instructions [here](README.md#adding-a-library-to-library-manager). + ### What are the requirements for a library to be added to Library Manager? @@ -40,20 +59,7 @@ Arduino Lint is also available as a GitHub Actions action that can be used in th https://github.com/arduino/arduino-lint-action -### How is the Library Manager index generated? - -[The Library Manager index](http://downloads.arduino.cc/libraries/library_index.json) contains the data for every release of every one of the thousands of libraries that have been added to the Library Manager list. This index is used by Library Manager to provide installation and updates of the libraries as well as to generate automated documentation pages for the [Arduino Library Reference](https://www.arduino.cc/reference/en/libraries/). - -Every hour, the automated Library Manager indexer system: - -1. checks every repository in the Library Manager list for new tags -1. checks whether those tags meet [the requirements for addition to the index](#update-requirements) -1. adds entries to the index for compliant tags -1. pushes the updated index to Arduino's download server - -### How can I add my library to Library Manager? - -Follow the instructions [here](README.md#adding-a-library-to-library-manager). +## Updates ### How can I publish a new release once my library is in the list? @@ -71,6 +77,10 @@ Follow the instructions [here](README.md#adding-a-library-to-library-manager). - [ ] The `name` property in library.properties must not have changed from the value it had when the library was submitted. If you must change the library name, see [this](#how-can-i-change-my-librarys-name). - [ ] The `version` property in library.properties must not be the same as it was in a tag previously added to the Library Manager index. +### Why aren't releases of my library being picked up by Library Manager? + +The Library Manager indexer job will reject any releases which aren't compliant with all [the requirements](#update-requirements). + ### I did something wrong! How can I change or unpublish an already published library? In order to change contents of an already published library version, you can recreate its related tag. @@ -79,10 +89,6 @@ In order to **un**publish a library version, delete its related tag/release. Once you have done that, open an issue in [the issue tracker of this repository](https://github.com/arduino/library-registry/issues), specifying the URL of the library repository and requesting that the library be updated. -### Why aren't releases of my library being picked up by Library Manager? - -The Library Manager indexer job will reject any releases which aren't compliant with all [the requirements](#update-requirements). - ### How can I change my library's name? For the sake of continuity, libraries in the Library Manager list are locked to the name they had at the time they were added to the list. Changing the library name can be disruptive to its users because this is the unique identifier for the library used by the Arduino development software [command line interfaces](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib/), sketch [metadata](https://arduino.github.io/arduino-cli/latest/sketch-specification/#metadata), library [dependencies](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format), and installation location. @@ -93,20 +99,6 @@ If you wish to change the name it will need to be done manually by request: 1. Create a release or tag. 1. Submit an [issue report](https://github.com/arduino/library-registry/issues) requesting the name be changed and stating the URL of your library's repository. -### How can I remove a library I installed via Library Manager? - -#### Arduino IDE 2.x - -Hover the mouse pointer over the "INSTALLED" label on the library listing in Library Manager. It will now change to "UNINSTALL", which you can click to uninstall that library. - -#### Classic Arduino IDE - -This version of the Arduino IDE does not have an integrated uninstall functionality, so you will need to remove the library manually. Open your sketchbook's `libraries` folder with your operating system's file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing the library. - -#### Arduino CLI - -Libraries can be uninstalled via [the `arduino-cli lib uninstall` command](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib_uninstall/). - ## Limitations ### Is my Git repository OK? @@ -117,6 +109,8 @@ Your repo is OK if it meets all [the requirements listed here](#submission-requi No. The library archive distributed by Library Manager will only contain an empty folder where the submodule should be. +## Usage + ### Can I add my own URL with my own library index? No. At the moment, the Arduino development software handles one URL only, and that's written into the code (dev jargon: it's hardcoded), this is a known limitation. @@ -131,3 +125,17 @@ For more information, see the [`library.properties` file format documentation](h ### Can I install multiple versions of one library and use the proper one in my sketches? Library Manager installs libraries into your sketchbook's `libraries` folder. Since you cannot create two folders with the same name, we can't install two versions of the same library. However, you can switch between library versions by selecting the appropriate one from the version dropdown that pops up on Library Manager when more than one version is available. + +### How can I remove a library I installed via Library Manager? + +#### Arduino IDE 2.x + +Hover the mouse pointer over the "INSTALLED" label on the library listing in Library Manager. It will now change to "UNINSTALL", which you can click to uninstall that library. + +#### Classic Arduino IDE + +This version of the Arduino IDE does not have an integrated uninstall functionality, so you will need to remove the library manually. Open your sketchbook's `libraries` folder with your operating system's file explorer (Windows: Explorer, Mac: Finder, Linux: Nautilus, kfiles...) and delete the folder containing the library. + +#### Arduino CLI + +Libraries can be uninstalled via [the `arduino-cli lib uninstall` command](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib_uninstall/). From 4b40e083428b06b881fc5d5970a564ca55701ab1 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 9 Apr 2021 07:55:39 -0700 Subject: [PATCH 11/11] Add table of contents to documentation It will be helpful to the reader to be able to get an overview of the documentation content and quickly navigate to the section of interest. The table of contents are automatically generated using the markdown-toc tool. Because it can be easy to forget to update the table of contents when the documentation content is changed, I have added a CI workflow to check for missed updates to readme ToC. On every push or pull request that affects the repository's documentation, it will check whether the table of contents matches the content. --- .github/workflows/check-toc.yml | 58 +++++++++++++++++++++++++++++++++ FAQ.md | 27 +++++++++++++++ README.md | 15 +++++++++ 3 files changed, 100 insertions(+) create mode 100644 .github/workflows/check-toc.yml diff --git a/.github/workflows/check-toc.yml b/.github/workflows/check-toc.yml new file mode 100644 index 00000000..30d2765b --- /dev/null +++ b/.github/workflows/check-toc.yml @@ -0,0 +1,58 @@ +name: Check ToC + +# See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows +on: + push: + paths: + - ".github/workflows/check-toc.yml" + - "README.md" + - "FAQ.md" + pull_request: + paths: + - ".github/workflows/check-toc.yml" + - "README.md" + - "FAQ.md" + workflow_dispatch: + repository_dispatch: + +jobs: + check: + name: ${{ matrix.file.name }} + runs-on: ubuntu-latest + + strategy: + fail-fast: false + + matrix: + file: + - name: README.md + # Max ToC depth, for use with the markdown-toc --maxdepth flag. + maxdepth: 4 + - name: FAQ.md + maxdepth: 3 + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Get week number for use in cache key + id: get-date + run: | + echo "::set-output name=week-number::$(date --utc '+%V')" + + - name: Load dependencies cache + uses: actions/cache@v2 + with: + path: ~/.npm + key: ${{ runner.os }}-node-markdown-toc-${{ steps.get-date.outputs.week-number }} + restore-keys: | + ${{ runner.os }}-node-markdown-toc- + + - name: Install markdown-toc + run: sudo npm install --global markdown-toc + + - name: Rebuild ToC + run: markdown-toc --bullets=- --maxdepth=${{ matrix.file.maxdepth }} -i "${{ github.workspace }}/${{ matrix.file.name }}" + + - name: Check ToC + run: git diff --color --exit-code diff --git a/FAQ.md b/FAQ.md index 923712e0..b81c67c8 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,5 +1,32 @@ # Arduino Library Manager FAQ +## Table of Contents + + + +- [General](#general) + - [What is the Arduino Library Manager?](#what-is-the-arduino-library-manager) + - [How is the Library Manager index generated?](#how-is-the-library-manager-index-generated) +- [Submission](#submission) + - [How can I add my library to Library Manager?](#how-can-i-add-my-library-to-library-manager) + - [What are the requirements for a library to be added to Library Manager?](#what-are-the-requirements-for-a-library-to-be-added-to-library-manager) +- [Updates](#updates) + - [How can I publish a new release once my library is in the list?](#how-can-i-publish-a-new-release-once-my-library-is-in-the-list) + - [What are the requirements for publishing new releases of libraries already in the Library Manager list?](#what-are-the-requirements-for-publishing-new-releases-of-libraries-already-in-the-library-manager-list) + - [Why aren't releases of my library being picked up by Library Manager?](#why-arent-releases-of-my-library-being-picked-up-by-library-manager) + - [I did something wrong! How can I change or unpublish an already published library?](#i-did-something-wrong-how-can-i-change-or-unpublish-an-already-published-library) + - [How can I change my library's name?](#how-can-i-change-my-librarys-name) +- [Limitations](#limitations) + - [Is my Git repository OK?](#is-my-git-repository-ok) + - [Are Git submodules supported?](#are-git-submodules-supported) +- [Usage](#usage) + - [Can I add my own URL with my own library index?](#can-i-add-my-own-url-with-my-own-library-index) + - [When I install a library that I know depends on another library, will this other library be installed as well?](#when-i-install-a-library-that-i-know-depends-on-another-library-will-this-other-library-be-installed-as-well) + - [Can I install multiple versions of one library and use the proper one in my sketches?](#can-i-install-multiple-versions-of-one-library-and-use-the-proper-one-in-my-sketches) + - [How can I remove a library I installed via Library Manager?](#how-can-i-remove-a-library-i-installed-via-library-manager) + + + ## General ### What is the Arduino Library Manager? diff --git a/README.md b/README.md index 3d66f1dc..efbf66f9 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,21 @@ This repository contains the list of libraries in the [Arduino Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) index. +## Table of Contents + + + +- [Frequently asked questions](#frequently-asked-questions) +- [Adding a library to Library Manager](#adding-a-library-to-library-manager) + - [Instructions](#instructions) + - [If the problem is with the pull request:](#if-the-problem-is-with-the-pull-request) + - [If the problem is with the library:](#if-the-problem-is-with-the-library) +- [Changing the URL of a library already in Library Manager](#changing-the-url-of-a-library-already-in-library-manager) +- [Removing the URL of a library already in Library Manager](#removing-the-url-of-a-library-already-in-library-manager) +- [Report a problem with Library Manager](#report-a-problem-with-library-manager) + + + ## Frequently asked questions For more information about Arduino Library Manager and how the index is maintained, please see [the FAQ](FAQ.md).