arli 0.9.0 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: de043be09051d5efc23d015a0d25499a88213639
4
- data.tar.gz: 5847acb4a33cf1962045684aac21ba5662fa9536
3
+ metadata.gz: f95b4f39cee0b07fa49266ec9592091751d120aa
4
+ data.tar.gz: 73c36166b9d7944f5f5e19409f6cbcd48ce4cb74
5
5
  SHA512:
6
- metadata.gz: 8cdaf4315432f68158dfbd5a44b664947172fbcfeb2fb49808ac65647158f59176015c44748fdaff92e2e1fa20783eddb844ddd3614e084dbb320d108ce1a77d
7
- data.tar.gz: 9d4d5826901bca3cd3cf3bb3e077aa491464b42193b2acec91f53ee1b2ac49a0aefeec10a4f66d829f1d60c20905af015088fdcda91a820ccb71db180157002b
6
+ metadata.gz: 954895dde7df7aa1ba919885a42a2409ce959ab9d46a8707bbd4c577bdbe3675331cfd69900b34669aeaef6162d23102eca5dea692cc2be555e65f659b4119a6
7
+ data.tar.gz: b002cfcaff5452763cb76b28d11f741b8c143aea2bc506fac1a61de1670c877a22ccd46d68c7deb4788abdb4966940e24d90e74b27f2a6e42864a2e3ee8739d5
data/.gitignore CHANGED
@@ -1,4 +1,3 @@
1
- cmake/
2
1
  .idea/
3
2
  /.bundle/
4
3
  /.yardoc
data/README.md CHANGED
@@ -3,64 +3,76 @@
3
3
  [![Maintainability](https://api.codeclimate.com/v1/badges/0812671b4bec27ba89b9/maintainability)](https://codeclimate.com/github/kigster/arli/maintainability)
4
4
  [![Test Coverage](https://api.codeclimate.com/v1/badges/0812671b4bec27ba89b9/test_coverage)](https://codeclimate.com/github/kigster/arli/test_coverage)
5
5
 
6
- ### Discussion
7
-
8
- Please head over to Gitter to discuss this project.
6
+ Please visit Gitter to discuss this project.
9
7
 
10
8
  [![Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/arduino-cmake-arli/)
11
9
 
12
- ___
13
10
 
14
- > Arli should work in any Unix environment. If you are on Windows, and need support — please [let us know](https://gitter.im/arduino-cmake-arli/).
15
- >
16
- > See also "sister project" [Arli-CMake](https://github.com/kigster/arli-cmake).
11
+ # Arli The Missing Arduino Library Manager
17
12
 
18
- ___
13
+ **Arli** is a simple and very easy to use command-line tool, that provides several key functions to aid in Arduino project development.
19
14
 
20
- # Arli
15
+ ### Why not Arduino IDE? Why not Platform.IO?
21
16
 
22
- **Arli** is an *awesomely simple and very easy to use Arduino Library Manager*. If you are using Arduino IDE you may be wondering **why is this needed?**
17
+ Arduino IDE is not meant for professional engineers — it's an educational tool for students. But if you want to build a sophisticated project in Arduino, you could leverage most of the Object Oriented practices thanks to the C++ support, as well as decoupling your code into modules and/or libraries.
23
18
 
24
- * Well, for one, Arli can "bundle" libraries not just from the official Arduino database, but also from individual Github URLs. There are thousands of libraries of high quality, that for one reason or another did not make it into the official database.
19
+ Unfortunately, this is not very easy to do with neither Arduino IDE, nor Platform.IO AFAIK.
25
20
 
26
- * Arduino still haven't come up with a way to automatically document project's dependencies on a set of libraries. I believe the best you've got is having to list libraries in comments, and then install each manually. With Arli you can automate this entire process.
27
- * [Not everyone likes using Arduino IDE](https://kig.re/2014/08/02/arduino-ide-alternatives.html). So this tool is, perhaps, aimed more at the professional programmers, wanting to build applications that tend to be on a complex side, and rely on multiple third party libraries. Boards like Teensy have a lot more RAM than Arduino UNO and clones, and so it can support much larger projects with dozens of libraries linked in with the firmware.
28
- * One of Arli's design goals is to provide a bridge between the [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake) project, which provides an alternative build system, and is compatible with numerous IDEs such as [Atom](https://atom.io), [JetBrains CLion](https://www.jetbrains.com/clion/), [Visual Studio Code](https://code.visualstudio.com/), or even [Eclipse](https://eclipse.org).
21
+ ### So, How does Arli Do It?
22
+
23
+ Arli integrates natively with the [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake) project, and provides an automatic generator for new projects, that should compile and upload out of the box.
24
+
25
+ You can easily declare new library depenencies, and Arli will happily find and install them for you, while the [arli-cmake](https://github.com/kigster/arli-cmake) project (that's a bridge between the two) knows how to compile each external library into a static .a object, and link it with your firmware in the end.
29
26
 
30
27
  ## Overview
31
28
 
32
- Arli allows your Arduino projects to be portable by including a YAML file called `Arlifile` at the top of your project, that defines your project's Arduino library dependencies.
29
+ Arli offers several commands, explained below:
33
30
 
34
- You can use the command `arli bundle` in the project's root directory to search, download and install all dependent libraries defined in the `Arlifile`. You can specify libraries by name and version, or you can omit the version to install the latest one. You can install libraries to a nested project folder, or a shared custom location where you keep all of your Arduino Libraries, and do it all consistently and reliably over and over again.
31
+ * `arli search [ terms ]` — search for a library by name or any attribute
35
32
 
36
- Below is an example of an actual `Arlifile` for a [Wall Clock](https://github.com/kigster/arduino-wallclock) project, which is a gorgeous wall clock equipped with a large and bright 7-Segment LED Display that dims automatically when it's dark in the room. In addition, the clock is equipped with multple sensors, a potentiometer, and a rotatary knob for changing time and brightness. This is not a simple project and it has nine library dependencies:
33
+ * `arli install 'library-name'` search, and install a single library
34
+ * `arli bundle` — uses a YAML-formatted `Arlifile` to install a bunch of dependencies. Can optionally generate a CMake include file for this project.
35
+ * `arli generate ProjectName --workspace ~/coding` — generates a clean brand new project in a given folder, that's equipped with `Arlifile`, and builds out of the box.
36
+
37
+ ### Arlifile and Bundle Command
38
+
39
+ `Arlifile` should be placed at the top of your project sources. Here is an example of a simple Arlifile with a bunch of dependencies:
37
40
 
38
41
  ![](docs/arlifile.png)
39
42
 
40
- Next, below is a screenshot of running `arli bundle` inside of that with the above `Arlifile`. We install into the default libraries folder `~/Documents/Arduino/Libraries`:
43
+ Next, below is a screenshot of running `arli bundle` inside of that folder. In this particular case, libraries are installed into the default folder `~/Documents/Arduino/Libraries`:
41
44
 
42
45
  ![](docs/arli-in-action.png)
43
46
 
47
+ #### Bundle Command Explained
48
+
44
49
  Let's break down what you see on the above screenshot:
45
50
 
46
51
  * First Arli prints the header, containing Arli version, the command, as well as the destination library path that the libraries are going to get installed to.
52
+
47
53
  * Next, Arli is looping, and for each library without the `url` field, it performs a search by the library `name` (and optionally its `version`), and then it prints the resulting library's name in blue.
48
54
  * The `version` that either was specified in the `Arlifile`, or is the latest for this library is printed next, in green.
49
- * Then Arli downloads the library sources either using the URL provided, or the URL attribute of the search result. Note, that **Arli always downloads libraries into a temporary folder first, always!**. It then scans the files inside, and determines the *canonical directory name* for the given library based on the most appropriate C/C++ header file. The library is first moved to this new name within the temporary folder, and the resulting directory is finally moved into the library path, while also handling the use-case where the library's canonical folder may already exist in the destination. There are three possible actions in this case that can be taken:
55
+ * Then Arli downloads the library sources either using the URL provided, or the URL attribute of the search result. Note, that **Arli always downloads libraries into a temporary folder first.**.
56
+ * Arli then scans the files inside each folder, and cleverly determines the *canonical directory name* for each library based on the most appropriate C/C++ header file.
57
+ * Next, the library is moved to the new canonical name within the temporary folder, and then the canonical folder is moved into the destination library path.
58
+ * If the destination folder already exist, there are three possible actions that can be specified via `-e` flag that will happen:
50
59
 
51
- * the silent default action is to simply **overwrite the existing library folder**.
52
- * by using `-e [ abort | backup ]` you can optionally do the following:
53
- * With the `abort` option, the first time an existing library is encountered, the entire command is halted, and an exception is thrown.
54
- * With the `backup` option, the old library folder is moved by adding an extension `.arli-backup-<TIMESTAMP>`.
55
-
60
+ * the silent default action is to simply **overwrite the existing library folder**.
61
+ * by using `-e [ abort | backup ]` you can optionally either abort the installation, or create a backup of each existing folder.
56
62
 
57
- Note that `-f yaml` specifies the format of the 'lock' file (`Arlifile.<format>`). So in this case our `Arlifile.yaml` will contain all library details obtained from the central database in YAML format.
63
+ #### Arlifile "Lock" File
58
64
 
59
- ### How Does It Work?
65
+ Whenever `bundle` command runs using an `Arlifile`, upon completion another file will be found in the same folder: typically `Arlifile.txt`, which contains metadata about libraries installed.
66
+
67
+ What's powerful is you can change the format of this file:
68
+
69
+ ```
70
+ $ arli bundle -f [ yaml | json | cmake ]
71
+ ```
72
+
73
+ Will create `Arlifile.yaml` or `Arlifile.cmake` with the set of resolved libraries.
60
74
 
61
- In a nutshell, Arli relies on the publicly available database of the vast majority of public Ardiuino libraries. This database is maintained by Arduino themselves, and is a [giant gzipped JSON file](http://downloads.arduino.cc/libraries/library_index.json.gz). Arli automatically downloads and caches the index on a local file system, and then lets you search and install libraries using either a simple name search, or more sophisticated ruby-like syntax that supports searching for ANY attribute as an equal match, or a regular expressions, or even a [Proc](http://ruby-doc.org/core-2.4.2/Proc.html).
62
75
 
63
- Sometimes, however, an Arduino library you use may not part of the main database. No problem! Just add the `url:` attribute together with the library name to `Arlifile`. The URL can either be a Github URL, or a URL to a downloadable ZIP file. Arli will figure out the rest.
64
76
 
65
77
  <a name="folder-detection"></a>
66
78
 
@@ -72,50 +84,45 @@ When Arli downloads libraries in ZIP format, they are unpacked into folder that
72
84
 
73
85
  > For example, 'Adafruit GFX Library' is the proper name of a corresponding library, and it's ZIP archive will unpack into a folder named `Adafruit_GFX_Library-1.4.3`. Arli will then detect that the header file inside the folder is `Adafruit_GFX.h`. In this case Arli will rename the top-level folder to `Adafruit_GFX`, and make the library valid, and its folder easily found.
74
86
 
75
- ### Other Commands
87
+ <a name="command-generate"></a>
76
88
 
77
- Arli provides several additional commands, described in details down below.
89
+ ## Command Generate
78
90
 
79
- * You can [search](#search-command) the offical library using any attribute of the library tested against a string, or a regular expression, or even a Ruby Proc if you know how to write them.
80
-
81
- * You can also install a single library with [install](#install-command), in which case there is no `Arlifile` or a lock file.
91
+ This command creates a new project using the template provided by the [`arli-cmake`](https://github.com/kigster/arli-cmake) project.
82
92
 
83
- ## Usage
93
+ ```bash
94
+ $ arli generate MyClock --workspace ~/arduino/sketches
95
+ ```
84
96
 
85
- Run `arli --help` for more information:
97
+ This command will create a brand new project under `~/arduino/sketches/MyClock`, and you should be able to build it right away:
86
98
 
87
99
  ```bash
88
- Usage:
89
- arli options
90
- arli command [ options ]
91
-
92
- -A, --print-attrs prints full list of available library
93
- attributes that can be used in search strings.
100
+ cd ~/arduino/sketches/MyClock
101
+ bin/setup
102
+ cd src
103
+ rm -rf build && mkdir build && cd build
104
+ cmake ..
105
+ make
106
+ make upload
107
+ ```
94
108
 
95
- -C, --no-color Disable any color output.
96
- -D, --debug Print debugging info.
97
- -t, --trace Print exception stack traces.
98
- -v, --verbose Print more information.
99
- -q, --quiet Print less information.
100
- -V, --version Print current version and exit
101
- -h, --help prints this help
109
+ The above steps can also be done via `bin/build src` bash script.
102
110
 
103
- Available Commands:
104
- search — Search standard Arduino Library Database with over 4K entries
105
- bundle — Installs all libraries specified in Arlifile
106
- install — Installs a single library either by searching, or url or local ZIP
111
+ There is an additional `example` folder that shows the complete example that uses external libraries, and builds and compiles using CMake and Arli.
107
112
 
108
- See arli command --help for more information on a specific command.
113
+ > **IMPORTANT**: Please do not forget to run `bin/setup` script. It downloads `arduino-cmake` dependency, without which the project will not build.
109
114
 
110
- arli (0.9.0) © 2017 Konstantin Gredeskoul, MIT License.
111
- ```
112
115
 
113
116
  <a name="command-bundle"></a>
114
117
 
115
- ### Command `bundle`
118
+ ## Command Bundle
116
119
 
117
120
  Use this command to install Arduino libraries defined in the `Arlifile` yaml file.
118
121
 
122
+ Below is a pretty comprehensive version, which not only defines external dependencies to be installed (in the `:depenencies` key), but also specifies built-in Arduino libraries, including Hardware libraries such as `Wire`.
123
+
124
+ Arlifile can also specify it's own installation path, lock file format (see below), and some additional device parameters.
125
+
119
126
  ![](docs/arlifile.png)
120
127
 
121
128
  There are two main categories of libraries you will be installing:
@@ -128,7 +135,6 @@ There are two main categories of libraries you will be installing:
128
135
  >
129
136
  > Note that this functionality is provided by the "sister" Ruby gem called [`arduino-library`](https://github.com/kigster/arduino-library), which essentially provides most of the underlying library-specific functionality.
130
137
 
131
-
132
138
  #### Installing from the Database
133
139
 
134
140
  You can specify libraries by providing just the `name:` (and posibly `version`) — the name must match exactly a library in the Arduino standard
@@ -143,7 +149,7 @@ You can provide the following fields in the `Arilfile` if you want the library t
143
149
 
144
150
  If a library you are using is not in the public database just provide its `name` and the `url` fields. The URL can either be a git URL, or a downloadable ZIP file. Arli will use the `url` field if it's available without trying to search for the library elsewhere.
145
151
 
146
- ### Generated "lock" file — `Arlifile.<format>`
152
+ #### Generated "lock" file — `Arlifile.<format>`
147
153
 
148
154
  Whenever `bundle` command succeeds, it will create a "lock" file in the same folder where the `Arlifile` file is located.
149
155
 
@@ -158,94 +164,16 @@ There are four lock file formats that are supported, and they can be passed in w
158
164
 
159
165
  Each format produces a file `Arlifile.<format>`: YAML and JSON will simply include the complete library info received from the database, while text format includes a *resolved* library folder names, versions, and the download URL — all comma separated, one per line.
160
166
 
161
- #### Experimental CMake Integration
162
-
163
- The CMake format is currently [**work in progress**](https://github.com/kigster/arli-cmake).
164
-
165
- The main goal is to create a CMake "include" file that can automatically build arli-installed libraries, add their locations to the `include_directories` so that the header files can be found.
166
-
167
- > **Help Wanted!** Do you know CMake well? Help us design the CMake and arduino-cmake integration.
168
-
169
- The CMake lock file is meant to be consumed by projects relying on the [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake). We are still working on the complete integration, which would hopefully allow the following features:
170
-
171
- * auto-generate a new Arduino project with the library dependencies using [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake) as the underlying build tool.
167
+ #### CMake Integration
172
168
 
173
- * Optionally, provide a CMake plugin that runs `arli bundle -f cmake`, and reads the `Arlifile.cmake`. That file will contain CMake code to build each dependent library separately as a static library, and then link it to the firmware in the end.
169
+ The CMake format is now fully supported, in tandem with `arduino-cmake` project.
174
170
 
175
- **CMake Coming Soon!**
171
+ See the `generate` command, which creates a new project with CMake enabled.
176
172
 
177
- #### An Example
178
-
179
- Here is the `arli bundle` command inside CMake-based project to build a [Wall Clock using Arduino](https://github.com/kigster/wallclock-arduino). This project has the following `Arlifile`:
180
-
181
- ```yaml
182
- # vi:syntax=yaml
183
- ---
184
- libraries_path: ./libs
185
- lock_format: cmake
186
- dependencies:
187
- - name: "Adafruit GFX Library"
188
- version: '1.2.0'
189
- - name: "DS1307RTC"
190
- - name: "Adafruit LED Backpack Library"
191
- - name: "Adafruit Unified Sensor"
192
- - name: "DHT sensor library"
193
- - name: "OneButton"
194
- - name: SimpleTimer
195
- url: https://github.com/jfturcot/SimpleTimer.git
196
- - name: Time
197
- ```
198
-
199
- You can see that most libraries are specified by name, except one (SimpleTimer) is specified together with the URL, which will be used to `git clone` the library.
200
-
201
- So let's specify where our libraries live, and run `arli bundle` inside that project. Below is a screenshot of running `arli` inside of the Wall Clock Arduino project:
202
-
203
- Below is the complete help for the `bundle` command for reference:
204
-
205
- ```
206
- ❯ arli bundle -h
207
- Description:
208
- Installs all libraries specified in Arlifile
209
-
210
- This command reads Arlifile (from the current
211
- folder, by default), and then it installs all dependent libraries
212
- specified there, checking if each already exists, and if not —
213
- downloading them, and installing them into your Arduino Library
214
- folder. Both the folder with the Arlifile, as well as the destination
215
- library path folder can be changed with the command line flags.
216
-
217
- Usage:
218
- arli bundle [options]
219
-
220
- Options
221
- -l, --lib-path PATH Destination: typically your Arduino libraries folder
222
- Defaults to ~/Documents/Arduino/Libraries
223
-
224
- -a, --arli-path PATH An alternate folder with the Arlifile file.
225
- Defaults to the current directory.
226
-
227
- -f, --format FMT Arli writes an Arlifile.lock with resolved info.
228
- The default format is text. Use -f to set it
229
- to one of: cmake, text, json, yaml
230
-
231
- -e, --if-exists ACTION If a library folder already exists, by default
232
- it will be overwritten or updated if possible.
233
- Alternatively you can either abort or backup
234
-
235
- -C, --no-color Disable any color output.
236
- -D, --debug Print debugging info.
237
- -t, --trace Print exception stack traces.
238
- -v, --verbose Print more information.
239
- -q, --quiet Print less information.
240
- -V, --version Print current version and exit
241
- -h, --help prints this help
242
-
243
- arli (0.9.0) © 2017 Konstantin Gredeskoul, MIT License.
244
- ```
245
173
 
246
174
  <a name="command-install"></a>
247
175
 
248
- ### Command `install`
176
+ ## Command `install`
249
177
 
250
178
  Use this command to install a single library by either a name or URL:
251
179
 
@@ -256,49 +184,9 @@ Eg:
256
184
  ❯ arli install 'https://github.com/jfturcot/SimpleTimer'
257
185
  ```
258
186
 
259
- Complete help is:
260
-
261
- ```bash
262
- ❯ arli install -h
263
- Description:
264
- Installs a single library either by searching, or url or local ZIP
265
-
266
- This command installs a single library into your library path (which
267
- can be set with --lib-path flag). Arli interpretes the
268
- third argument to arli install as either an exact
269
- library name, or a remote URL (either ZIP or Git Repo). You can use
270
- search command to first find the right library
271
- name, and then pass it to the install command.
272
-
273
- Usage:
274
- arli install [ "Exact Library Name" | url ] [options]
275
-
276
- Options
277
- -l, --lib-path PATH Destination: typically your Arduino libraries folder
278
- Defaults to ~/Documents/Arduino/Libraries
279
-
280
- -e, --if-exists ACTION If a library folder already exists, by default
281
- it will be overwritten or updated if possible.
282
- Alternatively you can either abort or backup
283
-
284
- -C, --no-color Disable any color output.
285
- -D, --debug Print debugging info.
286
- -t, --trace Print exception stack traces.
287
- -v, --verbose Print more information.
288
- -q, --quiet Print less information.
289
- -V, --version Print current version and exit
290
- -h, --help prints this help
291
-
292
- Examples:
293
- # Install the latest version of this library locally
294
- arli install "Adafruit GFX Library" -l ./libraries
295
-
296
- # Install the library from a Github URL
297
- arli install https://github.com/jfturcot/SimpleTimer```
298
-
299
187
  <a name="command-search"></a>
300
188
 
301
- ### Command `search`
189
+ ## Command `search`
302
190
 
303
191
  To search Arduino library database, you can use the search command.
304
192
 
@@ -309,7 +197,7 @@ You can search in two ways:
309
197
 
310
198
  `arli search AudioZero` does a simple search by name, and would match any library with 'AudioZero' in the name, such as `AudioZeroUpdated`. This search returns three results sorted by the version number:
311
199
 
312
- ```
200
+ ```bash
313
201
  ❯ arli search AudioZero
314
202
 
315
203
  --------------------------------------------------------------------------------
@@ -343,20 +231,17 @@ Adafruit AHRS (1.1.3) ( 5 total versions )
343
231
  Adafruit AM2315 (1.0.1) ( 2 total versions )
344
232
  Adafruit AMG88xx Library (1.0.0) ( 1 total versions )
345
233
  ......
346
- dafruit WS2801 Library (1.0.0) ( 1 total versions )
234
+ Adafruit WS2801 Library (1.0.0) ( 1 total versions )
347
235
  Adafruit microbit Library (1.0.0) ( 1 total versions )
348
236
  Adafruit nRF8001 (1.1.1) ( 2 total versions )
349
- Adafruit seesaw Library (1.0.1) ( 2 total versions )
350
- Adafruit_VL53L0X (1.0.2) ( 2 total versions )
351
- Adafruit_VL6180X (1.0.2) ( 2 total versions )
352
- Adafruit_mp3 (1.0.1) ( 2 total versions )
353
- WEMOS Matrix Compatible With Adafruit GFX (1.2.0) ( 3 total versions )
354
237
  ———————————————————————
355
238
  Total Versions : 355
356
239
  Unique Libraries : 116
357
240
  ———————————————————————
358
241
  ```
359
242
 
243
+ #### Search Output Format
244
+
360
245
  Finally, you can change the output format of the search, by passing `-f <format>`, where `format` can be `short` (the default), `long`, `json`, or `yaml`.
361
246
 
362
247
  For example, here is a how long format looks like:
@@ -364,10 +249,8 @@ For example, here is a how long format looks like:
364
249
  ```
365
250
  ❯ arli search 'name: /adafruit/i' -f long
366
251
 
367
- --------------------------------------------------------------------------------
368
252
  Arli (0.8.4), Command: search
369
253
  Library Path: ~/Documents/Arduino/Libraries
370
- --------------------------------------------------------------------------------
371
254
  _______________________________________________________________
372
255
  Name: Adafruit ADS1X15
373
256
  Versions: 1.0.0,
@@ -381,81 +264,26 @@ Versions: 1.0.0,
381
264
  Author(s): Adafruit
382
265
  Website: https://github.com/adafruit/Adafruit_ADXL345
383
266
  Sentence: Unified driver for the ADXL345 Accelerometer
384
- _______________________________________________________________
385
- Name: Adafruit AHRS
386
- Versions: 1.1.3, 1.1.2, 1.1.0, 1.0.2, 1.0.0
387
- Author(s): Adafruit
388
- Website: https://github.com/adafruit/Adafruit_AHRS
389
- Sentence: AHRS (Altitude and Heading Reference System) for Adafruit's
390
- 9DOF and 10DOF breakouts
391
- _______________________________________________________________
267
+ .....
268
+
392
269
  ```
393
270
 
271
+ With `-m LIMIT` flag you can limit number of results. But in our case above we printed all libraries that had the word "adafruit" (case insensitively) in their official name. We could have used `version:`, or `author`, or `website`, or even `url` and `archiveFileName` fields. For complete description of available library attributes, please see the official definition of the [`library.properties`](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#library-metadata) file.
394
272
 
395
- With `-m LIMIT` flag you can limit number of results. But in our cas above we printed all libraries that had the word "adafruit" (case insensitively) in their official name. We could have used `version:`, or `author`, or `website`, or even `url` and `archiveFileName` fields. For complete description of available library attributes, please see the official definition of the [`library.properties`](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#library-metadata) file.
273
+ A detailed description of the complete search functionality is documented in the library that provides it [arduino-library](https://github.com/kigster/arduino-library#using-search). Arli uses the `arduino-library` gem behind the scenes to search, and lookup libraries.
396
274
 
397
- A detailed description of the complete search functionality is documented in the library that provides it — [arduino-library](https://github.com/kigster/arduino-library#using-search). Arli uses `arduino-library` gem behind the scenes to search, and lookup libraries.
275
+ ## Discussion
398
276
 
399
- Below is the help screen for the search command:
277
+ ### More Reasons Why Arli is Needed
278
+
279
+ Arli is both an *Arduino Library Manager* and a project generator. If you are using Arduino IDE you may be wondering **why is this needed?**
280
+
281
+ * Well, for one, Arli can "bundle" libraries not just from the official Arduino database, but also from individual Github URLs. There are thousands of libraries of high quality, that for one reason or another did not make it into the official database.
282
+
283
+ * Arduino still haven't come up with a way to automatically document project's dependencies on a set of libraries. I believe the best you've got is having to list libraries in comments, and then install each manually. With Arli you can automate this entire process.
284
+ * [Not everyone likes using Arduino IDE](https://kig.re/2014/08/02/arduino-ide-alternatives.html). So this tool is, perhaps, aimed more at the professional programmers, wanting to build applications that tend to be on a complex side, and rely on multiple third party libraries. Boards like Teensy have a lot more RAM than Arduino UNO and clones, and so it can support much larger projects with dozens of libraries linked in with the firmware.
285
+ * One of Arli's design goals is to provide a bridge between the [arduino-cmake](https://github.com/arduino-cmake/arduino-cmake) project, which provides an alternative build system, and is compatible with numerous IDEs such as [Atom](https://atom.io), [JetBrains CLion](https://www.jetbrains.com/clion/), [Visual Studio Code](https://code.visualstudio.com/), or even [Eclipse](https://eclipse.org).
400
286
 
401
- ```
402
- ❯ arli search -h
403
- Description:
404
- Search standard Arduino Library Database with over 4K entries
405
-
406
- This command provides both the simple name-based search interface, and
407
- the most sophisticated attribute-specific search using a downloaded,
408
- and locally cached Public Arduino Database JSON file, maintained by
409
- the Arduino Community. If you know of another database, that's what
410
- the --database flag is for. Note that you can print the
411
- list of available attributes by running arli with
412
- --print-attrs flag.
413
-
414
- Usage:
415
- arli search [ -A | search-expression ] [options]
416
-
417
- Options
418
- -d, --database URL a JSON(.gz) file path or a URL of the library database.
419
- Defaults to the Arduino-maintained database.
420
-
421
- -m, --max NUMBER if provided, limits the result set using the
422
- total number of the unique library name matches.
423
- Default is 0, which means no limit.
424
-
425
- -f, --format FMT Optional format of the search results.
426
- The default is short. Available
427
- formats: with_versions, long, short, json, yaml
428
-
429
- -A, --print-attrs prints full list of available library
430
- attributes that can be used in search strings.
431
-
432
- -C, --no-color Disable any color output.
433
- -D, --debug Print debugging info.
434
- -t, --trace Print exception stack traces.
435
- -v, --verbose Print more information.
436
- -q, --quiet Print less information.
437
- -V, --version Print current version and exit
438
- -h, --help prints this help
439
-
440
- Examples:
441
- # Finds any library with name matching a given string, case insensitively
442
- arli search audiozero
443
-
444
- # If the first character is "/", then the argument is assumed to be regex
445
- arli search /AudioZero$/
446
-
447
- # If the first character is "=", then the rest is assumed to be exact name
448
- arli search =Time
449
-
450
- # Lets get a particular version of the library using another attribute
451
- arli search 'name: "AudioZero", version: "1.0.2"'
452
-
453
- # Search using case insensitive search for the author
454
- arli search 'author: /adafruit/i'
455
-
456
- # Finally, search for regex match for "WiFi" in a sentence or a paragraph
457
- arli search 'sentence: /wifi/i, paragraph: /wifi/i'
458
- ```
459
287
 
460
288
 
461
289
  ## Development