Skip to content

Commit 841af8f

Browse files
per1234per1234
authored
Merge pull request #5 from arduino/faq
Integrate Library Manager FAQ into documentation
2 parents f0f7dd1 + 4b40e08 commit 841af8f

File tree

3 files changed

+249
-6
lines changed

3 files changed

+249
-6
lines changed

‎.github/workflows/check-toc.yml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Check ToC
2+
3+
# See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows
4+
on:
5+
push:
6+
paths:
7+
- ".github/workflows/check-toc.yml"
8+
- "README.md"
9+
- "FAQ.md"
10+
pull_request:
11+
paths:
12+
- ".github/workflows/check-toc.yml"
13+
- "README.md"
14+
- "FAQ.md"
15+
workflow_dispatch:
16+
repository_dispatch:
17+
18+
jobs:
19+
check:
20+
name: ${{ matrix.file.name }}
21+
runs-on: ubuntu-latest
22+
23+
strategy:
24+
fail-fast: false
25+
26+
matrix:
27+
file:
28+
- name: README.md
29+
# Max ToC depth, for use with the markdown-toc --maxdepth flag.
30+
maxdepth: 4
31+
- name: FAQ.md
32+
maxdepth: 3
33+
34+
steps:
35+
- name: Checkout repository
36+
uses: actions/checkout@v2
37+
38+
- name: Get week number for use in cache key
39+
id: get-date
40+
run: |
41+
echo "::set-output name=week-number::$(date --utc '+%V')"
42+
43+
- name: Load dependencies cache
44+
uses: actions/cache@v2
45+
with:
46+
path: ~/.npm
47+
key: ${{ runner.os }}-node-markdown-toc-${{ steps.get-date.outputs.week-number }}
48+
restore-keys: |
49+
${{ runner.os }}-node-markdown-toc-
50+
51+
- name: Install markdown-toc
52+
run: sudo npm install --global markdown-toc
53+
54+
- name: Rebuild ToC
55+
run: markdown-toc --bullets=- --maxdepth=${{ matrix.file.maxdepth }} -i "${{ github.workspace }}/${{ matrix.file.name }}"
56+
57+
- name: Check ToC
58+
run: git diff --color --exit-code

‎FAQ.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# Arduino Library Manager FAQ
2+
3+
## Table of Contents
4+
5+
<!-- toc -->
6+
7+
- [General](#general)
8+
- [What is the Arduino Library Manager?](#what-is-the-arduino-library-manager)
9+
- [How is the Library Manager index generated?](#how-is-the-library-manager-index-generated)
10+
- [Submission](#submission)
11+
- [How can I add my library to Library Manager?](#how-can-i-add-my-library-to-library-manager)
12+
- [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)
13+
- [Updates](#updates)
14+
- [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)
15+
- [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)
16+
- [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)
17+
- [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)
18+
- [How can I change my library's name?](#how-can-i-change-my-librarys-name)
19+
- [Limitations](#limitations)
20+
- [Is my Git repository OK?](#is-my-git-repository-ok)
21+
- [Are Git submodules supported?](#are-git-submodules-supported)
22+
- [Usage](#usage)
23+
- [Can I add my own URL with my own library index?](#can-i-add-my-own-url-with-my-own-library-index)
24+
- [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)
25+
- [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)
26+
- [How can I remove a library I installed via Library Manager?](#how-can-i-remove-a-library-i-installed-via-library-manager)
27+
28+
<!-- tocstop -->
29+
30+
## General
31+
32+
### What is the Arduino Library Manager?
33+
34+
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.
35+
36+
- In the Arduino IDE: **Sketch > Include Library > Manage Libraries...**
37+
- In Arduino CLI: `arduino-cli lib --help`
38+
- In Arduino Web Editor: all Library Manager libraries are pre-installed.
39+
40+
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.
41+
42+
More information:
43+
44+
- https://www.arduino.cc/en/Guide/Libraries#toc3
45+
- https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib/
46+
- https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a
47+
48+
### How is the Library Manager index generated?
49+
50+
[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/).
51+
52+
Every hour, the automated Library Manager indexer system:
53+
54+
1. checks every repository in the Library Manager list for new tags
55+
1. checks whether those tags meet [the requirements for addition to the index](#update-requirements)
56+
1. adds entries to the index for compliant tags
57+
1. pushes the updated index to Arduino's download server
58+
59+
## Submission
60+
61+
### How can I add my library to Library Manager?
62+
63+
Follow the instructions [here](README.md#adding-a-library-to-library-manager).
64+
65+
### What are the requirements for a library to be added to Library Manager?
66+
67+
<a id="submission-requirements"></a>
68+
69+
- [ ] The library must be fully compliant with the [Arduino Library Specification](https://arduino.github.io/arduino-cli/latest/library-specification).
70+
- [ ] 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.
71+
- [ ] The library.properties file must be located in the root of the repository.
72+
- [ ] The library must not have the same library.properties `name` value (regardless of case) as another library previously added to the Library Manager list.
73+
- [ ] For 3rd party libraries, the `name` field in library.properties must not start with `Arduino`.
74+
- [ ] The library repository must not contain any `.exe` files.
75+
- [ ] The library repository must not contain a [`.development` file](https://arduino.github.io/arduino-cli/latest/library-specification/#development-flag-file).
76+
- [ ] The library repository must not contain any [symlinks](https://en.wikipedia.org/wiki/Symbolic_link).
77+
- [ ] The library repository must not contain any files detected as infected by our antivirus scan.
78+
- [ ] 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.
79+
- [ ] 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).
80+
81+
Arduino has created a command line tool to check libraries for compliance with all the Library Manager requirements:
82+
83+
https://github.com/arduino/arduino-lint
84+
85+
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:
86+
87+
https://github.com/arduino/arduino-lint-action
88+
89+
## Updates
90+
91+
### How can I publish a new release once my library is in the list?
92+
93+
1. Make sure the library is compliant with [all requirements](#update-requirements).
94+
1. Update the `version` in your [`library.properties`](https://arduino.github.io/arduino-cli/latest/library-specification/#library-metadata)).
95+
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/)).
96+
97+
[Our indexer](#how-is-the-library-manager-index-generated) checks for new releases every hour and will eventually fetch and publish your new release.
98+
99+
### What are the requirements for publishing new releases of libraries already in the Library Manager list?
100+
101+
<a id="update-requirements"></a>
102+
103+
- [ ] The library must be compliant with all the same [requirements that apply to submissions](#submission-requirements).
104+
- [ ] 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).
105+
- [ ] The `version` property in library.properties must not be the same as it was in a tag previously added to the Library Manager index.
106+
107+
### Why aren't releases of my library being picked up by Library Manager?
108+
109+
The Library Manager indexer job will reject any releases which aren't compliant with all [the requirements](#update-requirements).
110+
111+
### I did something wrong! How can I change or unpublish an already published library?
112+
113+
In order to change contents of an already published library version, you can recreate its related tag.
114+
115+
In order to **un**publish a library version, delete its related tag/release.
116+
117+
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.
118+
119+
### How can I change my library's name?
120+
121+
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.
122+
123+
If you wish to change the name it will need to be done manually by request:
124+
125+
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`.
126+
1. Create a release or tag.
127+
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.
128+
129+
## Limitations
130+
131+
### Is my Git repository OK?
132+
133+
Your repo is OK if it meets all [the requirements listed here](#submission-requirements).
134+
135+
### Are Git submodules supported?
136+
137+
No. The library archive distributed by Library Manager will only contain an empty folder where the submodule should be.
138+
139+
## Usage
140+
141+
### Can I add my own URL with my own library index?
142+
143+
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.
144+
However, if you know your way through the code, you can change that URL with another one.
145+
146+
### When I install a library that I know depends on another library, will this other library be installed as well?
147+
148+
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.
149+
150+
For more information, see the [`library.properties` file format documentation](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format).
151+
152+
### Can I install multiple versions of one library and use the proper one in my sketches?
153+
154+
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.
155+
156+
### How can I remove a library I installed via Library Manager?
157+
158+
#### Arduino IDE 2.x
159+
160+
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.
161+
162+
#### Classic Arduino IDE
163+
164+
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.
165+
166+
#### Arduino CLI
167+
168+
Libraries can be uninstalled via [the `arduino-cli lib uninstall` command](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib_uninstall/).

‎README.md

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,25 @@
33
This repository contains the list of libraries in the
44
[Arduino Library Manager](https://www.arduino.cc/en/guide/libraries#toc3) index.
55

6+
## Table of Contents
7+
8+
<!-- toc -->
9+
10+
- [Frequently asked questions](#frequently-asked-questions)
11+
- [Adding a library to Library Manager](#adding-a-library-to-library-manager)
12+
- [Instructions](#instructions)
13+
- [If the problem is with the pull request:](#if-the-problem-is-with-the-pull-request)
14+
- [If the problem is with the library:](#if-the-problem-is-with-the-library)
15+
- [Changing the URL of a library already in Library Manager](#changing-the-url-of-a-library-already-in-library-manager)
16+
- [Removing the URL of a library already in Library Manager](#removing-the-url-of-a-library-already-in-library-manager)
17+
- [Report a problem with Library Manager](#report-a-problem-with-library-manager)
18+
19+
<!-- tocstop -->
20+
21+
## Frequently asked questions
22+
23+
For more information about Arduino Library Manager and how the index is maintained, please see [the FAQ](FAQ.md).
24+
625
## Adding a library to Library Manager
726

827
If you would like to have your library available for installation via Library Manager, just submit a
@@ -14,8 +33,8 @@ See the instructions below for detailed instructions on how to do this via the G
1433
### Instructions
1534

1635
1. You may want to first take a look at
17-
[the requirements for admission into the Arduino Library Manager index](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
18-
Each submission will be checked for compliance before being accepted.
36+
[the requirements for admission into the Arduino Library Manager index](FAQ.md#submission-requirements). Each submission will be checked for
37+
compliance before being accepted.
1938
1. Open this link to [fork](https://guides.github.com/activities/forking/) this repository and edit the list via the
2039
GitHub web interface: https://github.com/arduino/library-registry/edit/main/repositories.txt
2140
1. Add the library repository's URL to the list. This should be the URL of the repository home page. For example:
@@ -70,10 +89,8 @@ description, making it clear that the URL is intentionally being removed.
7089

7190
## Report a problem with Library Manager
7291

73-
Please first take a look at
74-
[the Arduino Library Manager FAQ](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ). If a library release is
75-
missing from Library Manager, it is usually because it was not compliant with all the requirements listed in that
76-
document.
92+
Please first take a look at [the FAQ](FAQ.md). If a library release is missing from Library Manager, it is usually
93+
because it was not compliant with all [the requirements](FAQ.md#update-requirements) listed in that document.
7794

7895
This repository is not an appropriate place to request support or report problems with a library. Check the library's
7996
own documentation for instructions or ask on the [Arduino Forum](https://forum.arduino.cc/).

0 commit comments

Comments
 (0)