arli 1.1.0 → 1.2.1

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: 818b4b5c9c83de430b9c59f4487731ee42cca089
4
- data.tar.gz: 8a2bce6807e0a4a84245d62bcc0780386bd46244
3
+ metadata.gz: 0abe9044357d7bff2eab6f8cd87b80b729aebc9a
4
+ data.tar.gz: ce3df76a7613eccd2d7ada2426400fd4084b7724
5
5
  SHA512:
6
- metadata.gz: a8eae4bcea44a72f7fe9411ac2efe3c8eec1de049b44f5829620a3d9255ee351738919c855134e4060f1931102a37b11c95abbcb0bc32b9a6fdbd878bd78ab4a
7
- data.tar.gz: 8f28ec1d5c3e7ad1736ac89e3be18fe9bd003f5ddc10f908e3547cf226a34437fd89f614fe375439b0052798668bc7876277088486be33297eba51e130a1257b
6
+ metadata.gz: b7f6aaed86211c89a35b9da9c0083c4daf9d01d4b3a1d3d6ff39cdcc577a9f1d091c25dd7ddb62ce681568879fe72b6755641fb1c7d3a067ecbfb2e8d4daec6a
7
+ data.tar.gz: 26ebf7fdfc17fcf40ac043e0b7e7c95960c8c84d1f7a3239e6b575a354c181b7b9cd688f3dda56b827cdb74c37d13d7da91fcc08f6bc75487e3bf089fae94f74
@@ -5,8 +5,9 @@ sudo: false
5
5
  language: ruby
6
6
  cache: bundler
7
7
  rvm:
8
- - 2.4.1
9
- - 2.3.5
8
+ - 2.5.1
9
+ - 2.4.3
10
+ - 2.3.7
10
11
  before_install: gem install bundler -v 1.15.4
11
12
  before_script:
12
13
  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64
data/README.md CHANGED
@@ -3,85 +3,172 @@
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
- Please visit Gitter to discuss this project.
6
+ Please visit Gitter to support and a discussion of this project.
7
7
 
8
8
  [![Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/arduino-cmake-arli/)
9
9
 
10
- # Arli — The Missing Arduino Library Manager
10
+ # Arli
11
11
 
12
- **Arli** is a simple and very easy to use the command-line tool, which offers several vital features to aid in Arduino project development, especially for larger projects with many depenencies and external libraries.
12
+ **Arli is an Arduino library manager with the ability to search libraries, install a single library, or bundle any number of libraries with the project. Arli also is a new project generator based on the `arduino-cmake` build system.**
13
+
14
+ **Arli** is a rather simple and easy to use command-line tool which offers several indispensable features that help with Arduino project development, in particular for much larger projects with many dependencies and external libraries.
15
+
16
+ What's more, is that projects generated by Arli's `generate` command are highly portable from one system to another. Anyone can download your project build/upload with very little work.
17
+
18
+ ### Capabilities
13
19
 
14
20
  Arli can:
15
21
 
16
- * automatically **find, download and install** of any number of third-party Arduino library dependencies, while performing a [library folder name resolution](#folder-detection)
22
+ * **search for Arduino libraries** in the official public [database](http://downloads.arduino.cc/libraries/library_index.json.gz) maintained by Arduino using any of the standard [library attributes](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification) either by the exact match, or a case-insensitive regular expression, a substring, etc.
23
+
24
+ * automatically **find, download and install** of any number of third-party Arduino library dependencies, while performing a non-trivial but required [library folder name resolution](#folder-detection)
17
25
 
18
26
  * **maintain a consistent set of libraries** for a given project using a YAML-formatted `Arlifile`.
27
+
28
+ * support libraries **that depend on other libraries**. Arli ensures the correct build/linking order.
19
29
 
20
- * **generate a new project skeleton** that uses [`arduino-cmake`](https://github.com/arduino-cmake/arduino-cmake) as the build environment, which builds and uploads your firmware "out of the box".
21
-
22
- * **search for Arduino libraries** in the official public [database](http://downloads.arduino.cc/libraries/library_index.json.gz) maintained by Arduino using any library attribute by exact match, or regular expression, substring, and more.
30
+ * **generate a new project skeleton** based on [arli-cmake](https://github.com/kigster/arli-cmake) template, which in turn relies upon [`arduino-cmake`](https://github.com/arduino-cmake/arduino-cmake) as the build environment, which builds and uploads freshly generated projects to your firmware "out of the box".
23
31
 
24
32
  To get a sense of its feature, we invite you to watch the following screen cast:
25
33
 
26
- [![asciicast](https://asciinema.org/a/155261.png)](https://asciinema.org/a/155261)
34
+ [![asciicast](https://asciinema.org/a/155289.png)](https://asciinema.org/a/155289)
27
35
 
28
- ### Who is Arli For?
36
+ ### How is Arli Different?
29
37
 
30
- _Arli is ideally suited for C/C++ programmers who have some basic knowledge of CMake, and who want to build larger-than-trivial projects on Arduino platform. Arli promotes use and reuse of libraries, which help take advantage of the Object Oriented Design Patterns, decoupling your code into reusable libraries._
38
+ Arli is a fast, small, and pretty specialized command line tool (written in Ruby) that only does **four or five things very well**, and relies on other well-supported projects do their job in particular, it relies on Arduino SDK, and `arduino-cmake` when it generates new projects.
31
39
 
32
- Having said that, Arli is also helpful for projects that do NOT use CMake. It can be used purely as a library manager, or GitHub repo downloader.
40
+ For additional discussion, and comparison with Arduino IDE, or PlatformIO please [read the discussion section down below](#discussion)
33
41
 
34
- ### Why not the Arduino IDE?
35
42
 
36
- Arduino IDE is not meant for professional engineers — it's a fantastic educational tool for students. And while it lacks basic features of C/C++ development it succeeds in making Arduino programming accessible to young kids and students.
43
+ <a name="folder-detection"></a>
37
44
 
38
- ### Why not Platform.IO?
45
+ #### Automatic Folder Name Correction
39
46
 
40
- [PlatformIO](http://platformio.org/) is a great "eco-system" that includes not just Arduino, but many other boards, provides integrated library manager, and Atom as the primary IDE. It's a fantastic tool for beginner/intermediate developers, much better than Arduino IDE.
47
+ Arli understands that the folder where the library is installed must be named correctly: in other words, **folder name must match the header file inside of the folder** for the library to be found.
41
48
 
42
- But it's not without its downsides: to some PlatformIO feels *too heavy*. It comes with a gazillion additional features you'll never use and it tries to be too much all at once. Perhaps for some people it can be a feature. But for the author and other members of the Arduino dev community, PlatformIO design goes against the fundamental principals of [Unix Philosophy](https://en.wikipedia.org/wiki/Unix_philosophy), which promotes a minimalist, modular software development delegated to specialized commands that can be all interconnected (think `grep`, `awk`, `sort`, `uniq`).
49
+ When Arli downloads libraries in ZIP format, they are unpacked into a folder that would not resolve as an Arduino library folder without having to be renamed. Arli provides an algorithm that searches the contents of the folder for the source and header files. The name of the directory is then compared to the files found, and in most cases Arli will automatically **rename the library folder to match the main header file **
43
50
 
44
- ### How is Arli Different?
51
+ > 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.
45
52
 
46
- Arli is a fast, small, and pretty specialized command line tool (written in Ruby) that only does **four or five things very well**, and relies on other well-supported projects do their job — in particular, it relies on Arduino SDK, and `arduino-cmake` when it generates new projects.
47
53
 
48
- Arli shines when you need to build a complicated and multi-dependency project using an Arduino compatible board such as [Teensy](https://www.pjrc.com/teensy/), which has 16x more RAM than the Arduino UNO, and therefore allows you to take advantage of many more third-party Arduino libraries at once within a single project.
54
+ ## Installation
49
55
 
50
- > A few years ago the author built a complex project called [**Filx Capacitor**](https://github.com/kigster/flix-capacitor), which relied on **ten** external libraries. Managing these dependencies was very time-consuming. Asking someone else to build this project on their system was near impossible. Not just that, but even for the author himself, after taking some time off and returning to the project — it was still difficult to figure out why it was suddenly refusing to build. So many things could have gone wrong.
51
- >
52
- > This is the problem Arli (together with the very powerful `arduino-cmake` project) attempts to solve. Your project's dependencies can be cleanly defined in a YAML file called `Arlifile`, together with an optional board name and a CPU. Next, you add a bunch of C/C++ files to the folder, update `CMakeLists.txt` file and rebuild the project, upload the firmware, or connect to the serial port. See [arli-cmake](https://github.com/kigster/arli-cmake#manual-builds) for more information.
56
+ Arli is a ruby gem, so to install it run:
57
+
58
+ ```bash
59
+ gem install arli
60
+ ```
53
61
 
54
- ## Overview
62
+ You may need to use `sudo` before the command, if you are using a system-wide ruby installation.
55
63
 
56
- Arli offers several commands, explained below:
64
+ Once installed, run `arli` with no arguments to see it's help screen.
57
65
 
58
- * `arli search [ name | regex | ruby-expression]`
59
- [searches](#search-command) for a library by name or any attribute
66
+ ## Usage
60
67
 
61
- * `arli install [ name | regex | ruby-expression ]`
62
- search, and [install](#install-command) a single library if the search resulted in one and only one match.
68
+
69
+ Arli offers several key commands, explained below:
70
+
71
+ * `arli search [ name | regex ] [ options ]`
72
+ [searches](#search-command) for a library by name or any attribute in the default Arduino database.
73
+
74
+ * `arli install library-name [ options ]`
75
+ search, and [install](#install-command) a single library if the search for the name results in one and only one match (if multiple versions of the same library exist, the latest one is installed).
63
76
 
64
- * `arli bundle [ -f [ yaml | json | cmake | text ] ] `
65
- reads a YAML-formatted `Arlifile`, and [bundles](#bundle-command), i.e., searches, downloads, resolves the appropriate library folder name, and installs all libraries to either a global location, or a custom location specified by a `-l` flag, or in the `Arlifile` itself.
77
+ * `arli bundle [ options ]`
78
+ reads a YAML-formatted `Arlifile` that defines a list of libraries, as well as (optionally) a board name and CPU, and installs all specified libraries, or as we say [bundles the project](#bundle-command). This process includes a search, download, folder name resolution, and finally installation to either a global location, or a custom location specified by a `-l` flag, or in the `Arlifile` itself.
79
+
80
+ It also generates an output file in various formats, for example `json` format will generate `Arflifile.json` with full metadata about each library.
66
81
 
67
- In the CMake mode, generates `Arlifile.cmake` that is included in the main CMake of the project.
82
+ In the CMake mode, Arli generates `Arlifile.cmake`, which can be included in the main `CMakeLists.txt` file of the project to automatically build and link with the libraries.
68
83
 
69
- * `arli generate ProjectName [ -w ~/workspace ]`
70
- [generates](#generate-command) a clean brand new C/C++ project in a given folder, that consists of `Arlifile`, a C++ file, a `CMakeLists.txt` file, and the dependent CMake libraries all included.
84
+ * `arli generate ProjectName [ options ]`
85
+ [generates](#generate-command) a clean brand new C/C++/CMake project folder `ProjectName` in the current directory (or whatever is provided by `--workspace DIR`). The generated folder is a complete and nearly empty project, but one that builds, includes a sample `Arlifile`, a starting sketch file, and all of the `CMakeLists.txt` tooling you need to build and upload your project.
86
+
87
+
88
+ ### Arlifile Specification
89
+
90
+ `Arlifile` is the cornerstone of this library, and so we discuss this in detail. It's a central configuration file that defines library dependencies, and also some additional metadata, such as the board and CPU, as well as the hardware libraries.
91
+
92
+ ```yaml
93
+ version: 2.0.0
94
+ libraries_path: "./libraries"
95
+ lock_format: cmake
96
+ device:
97
+ board: uno
98
+ cpu: atmega328
99
+ libraries:
100
+ hardware:
101
+ - name: Wire
102
+ arduino:
103
+ - name: SD
104
+ dependencies:
105
+ - name: "Adafruit GFX Library"
106
+ - name: "Adafruit LED Backpack Library"
107
+ depends: "Adafruit GFX Library"
108
+ - name: "Adafruit Unified Sensor"
109
+ - name: "DHT sensor library"
110
+ - name: "DS1307RTC"
111
+ - name: "OneButton"
112
+ - name: "SimpleTimer"
113
+ url: https://github.com/jfturcot/SimpleTimer.git
114
+ - name: "Time"
115
+ ```
116
+
117
+ Let's review the contents:
118
+
119
+ * **libraries_path** defines an absolute or relative (to `Arlifile`) folder where libraries are to be installed.
120
+
121
+ * **lock_format** specifies the format of the output `Arlifile.<format>` after a successful `bundle` command. If you are using Arli with CMake, you will always want to have that be specified in Arlifile to save you typing :)
122
+
123
+ * **Device** section is optional, but can be used to specify the **Board Name** and the **Board CPU**, as well as the two types of libraries that come with Arduino SDK
124
+ 1. general **arduino** libraries, and
125
+ 2. **hardware-specific** libraries, found in a hardware-specific folder. For example, if your hardware is AVR — then they will be in the `${ARDUINO_SDK_PATH}/hardware/arduino/avr/libraries` folder.
126
+
127
+ * Finally, the **dependencies** key is an array of hashes, that list third-party libraries to be installed. Here you must specify libraries by one of the [supported fields](#arlifile-libraries). Name is the most common, but it must match library name provided in the database, not the header file name.
128
+
129
+ Note that you can specify `depends:` attribute, which is an array of other library names (that must also be present in the `Arlifile`). This setting only applies to CMake build.
130
+
131
+ > NOTE: One of Arli's design goals is to make `Arlifile` a sort of a reusable "configuration" file for the project that helps make your project easily portable.
132
+
133
+ <a name='arlifile-libraries'></a>
134
+
135
+ #### Adding Libraries to `Arlifile`
136
+
137
+ You can specify libraries by providing just the `name:` (and posibly `version`) — but **the name must match exactly a library in the Arduino standard database!** This is a critical part.
138
+
139
+ > **EXAMPLE:** If you want to add `Adafruit_GFX.h` header, you need to find the appropriate name for this library in the database. If you know the header name, the easiest way to do that is to do the following search:
140
+ >
141
+ > ```bash
142
+ > arli search 'archiveFileName: /adafruit_gfx/i'
143
+ > ```
144
+ >
145
+ > You will see in the output that only two libraries match:
146
+ >
147
+ > ```
148
+ > Adafruit GFX Library (1.2.2)
149
+ > WEMOS Matrix Compatible With Adafruit GFX (1.2.0)
150
+ > ```
151
+ >
152
+ > You want to copy the name "Adafruit GFX Library" and place it in the `Arlifile` against the `name:` attribute.
71
153
 
72
- ## Arlifile and the Bundle Command
154
+ You can provide the following fields in the `Arilfile` if you want the library to be found in the Arduino Library database automatically:
73
155
 
74
- This is the cornerstone of this library, and so we discuss this in detail.
156
+ * `name` should be the exact match as described above. Use double quotes if the name contains spaces.
157
+ * `version` can be used together with the `name` to specify a particular version. When `name` is provided without `version`, the latest version is used.
158
+ * `checksum` and `archiveFileName` can be also used as they both uniquely identify a library, however they are not very descriptive, and we suggest you simply search by these fields first, and add the library by name, which is a good convention.
159
+
160
+ #### Installing a Non-Standard Library
75
161
 
76
- Below is the image of a pretty comprehensive version of an [`Arlifile`](https://github.com/kigster/weather-pod/blob/master/src/Arlifile), which should be placed at the top of your project sources.
162
+ 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.
77
163
 
78
- ![](docs/arlifile.png)
164
+ **Arli will use the `url` field if it's available** without trying to search for the library elsewhere.
79
165
 
80
- The `dependencies` is the key that lists third-party libraries. But you can also define hardware dependencies such as `Wire`, and the BOARD name and the CPU if your project relies on a particular board.
81
166
 
82
- > One of Arli's design goals was for `Arlifile` to become a central "configuration" file for the project, and go beyond pure dependencies and also contain some additional metadata about the project that makes your code easily portable to another computer.
167
+ ## Commands
168
+
169
+ <a name="bundle-command"></a>
83
170
 
84
- #### Bundle Command Explained
171
+ ### Command `bundle`
85
172
 
86
173
  When you run `arli bundle` in the folder with an `Arlifile`, many things happen. Below is another screenshot of running bundle:
87
174
 
@@ -103,32 +190,57 @@ Let's break down what you see in the above screenshot:
103
190
 
104
191
  * the default action is to simply **overwrite the existing library folder**.
105
192
  * by using `-e [ abort | backup ]` you can optionally either abort the installation, or create a backup of the existing folder.
193
+
194
+ * Upon completion of the `bundle` command, a new file will be created next to `Arlifile`: `Arlifile.<format>` where format is one of: `yaml`, `json`, `text` or `cmake`. Format can be specified with `--format <format>` or `-f` for short. The file contains different contents depending on the format.
195
+
196
+ With `json` or `yaml` formats, the file will contain a complete metadata about each installed library, obtained from the database search.
197
+
198
+ With `text` format (which is the default), the result is a compact CSV file with just a couple of library attributes.
199
+
200
+ With the `cmake` format, the resulting `Arlifile.cmake` is meant to be included in the `CMakeLists.txt` file of the project build with `arduino-cmake` library.
106
201
 
107
- #### Arlifile "Lock" File
108
-
109
- 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.
110
-
111
- What's powerful is you can change the format of this file:
112
-
113
- ```
114
- $ arli bundle -f [ yaml | json | cmake ]
115
- ```
202
+ You can change the format of this file with `-f/--format` flag.
116
203
 
117
- Will create `Arlifile.yaml` or `Arlifile.cmake` with the set of resolved libraries.
204
+ #### CMake Integration
118
205
 
119
- <a name="folder-detection"></a>
206
+ The CMake format is now fully supported, in tandem with `arduino-cmake` project.
120
207
 
121
- ### Automatic Folder Name Correction
208
+ Below is the resulting `Arlifile.cmake` after running `arli bundle` on the above mentioned file.
122
209
 
123
- Arli understands that the folder where the library is installed must be named correctly: in other words, **folder name must match the header file inside of the folder** for the library to be found.
210
+ ```cmake
211
+ set(ARLI_CUSTOM_LIBS_PATH "${CMAKE_CURRENT_SOURCE_DIR}/libraries")
212
+ set(ARLI_CUSTOM_LIBS
213
+ Adafruit_GFX
214
+ Adafruit_LEDBackpack
215
+ Adafruit_Sensor
216
+ DHT
217
+ DS1307RTC
218
+ OneButton
219
+ SimpleTimer
220
+ Time)
221
+ set(ARLI_ARDUINO_HARDWARE_LIBS
222
+ Wire)
223
+ set(ARLI_ARDUINO_LIBS )
224
+ set(Adafruit_LEDBackpack_DEPENDS_ON Adafruit_GFX)
225
+ set(Adafruit_Sensor_ONLY_HEADER yes)
226
+
227
+ include(Arli)
228
+
229
+ arli_detect_serial_device("/dev/null")
230
+ arli_detect_board("uno" "atmega328")
231
+
232
+ message(STATUS "device: [${BOARD_DEVICE}], board: [${BOARD_NAME}], cpu: [${BOARD_CPU}] <<<")
233
+
234
+ arli_build_all_libraries()
235
+ ```
124
236
 
125
- When Arli downloads libraries in ZIP format, they are unpacked into a folder that would not resolve as an Arduino library folder without having to be renamed. Arli provides an algorithm that searches the contents of the folder for the source and header files. The name of the directory is then compared to the files found, and in most cases Arli will automatically **rename the library folder to match the main header file **
237
+ This file only works in tandem with [`arli-cmake`](https://github.com/kister/arli-cmake) project.
126
238
 
127
- > 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.
239
+ See the [`generate`](#command-generate) command, which creates a new project with CMake enabled.
128
240
 
129
241
  <a name="generate-command"></a>
130
242
 
131
- ## Command Generate
243
+ ### Command `generate`
132
244
 
133
245
  This command creates a new project using the template provided by the [`arli-cmake`](https://github.com/kigster/arli-cmake) project.
134
246
 
@@ -141,7 +253,6 @@ This command will create a brand new project under `~/arduino/sketches/MyClock`,
141
253
  ```bash
142
254
  cd ~/arduino/sketches/MyClock
143
255
  bin/setup
144
- cd src
145
256
  rm -rf build && mkdir build && cd build
146
257
  cmake ..
147
258
  make
@@ -154,76 +265,10 @@ There is an additional `example` folder that shows the complete example that use
154
265
 
155
266
  > **IMPORTANT**: Please do not forget to run `bin/setup` script. It downloads `arduino-cmake` dependency, without which the project will not build.
156
267
 
157
- <a name="bundle-command"></a>
158
-
159
- ## Command Bundle
160
-
161
- Use this command to install Arduino libraries defined in the `Arlifile` yaml file.
162
-
163
- 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`.
164
-
165
- Arlifile can also specify it's own installation path, lock file format (see below), and some additional device parameters.
166
-
167
- ![](docs/arlifile.png)
168
-
169
- There are two main categories of libraries you will be installing:
170
-
171
- 1. One of the officially registered in the [Arduino official library database](http://downloads.arduino.cc/libraries/library_index.json.gz), which is a giant gzipped JSON file. Arli will download and cache this file locally, and use it to find libraries.
172
-
173
- 2. Using the `:url` field that links to either a remote ZIP file, or a Github Repo.
174
-
175
- > When using the public database, which at the time of this writing contains 1220 unique libraries, spanning 4019 separate versions. when the remote file's size changes, will Arli automatically detects that by issuing a `HEAD` HTTP request, and after comparing the size to the locally cached version, it might decide to re-download it.
176
- >
177
- > 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.
178
-
179
- #### Installing from the Database
180
-
181
- You can specify libraries by providing just the `name:` (and posibly `version`) — the name must match exactly a library in the Arduino standard
182
-
183
- You can provide the following fields in the `Arilfile` if you want the library to be found in the Arduino Library database:
184
-
185
- * `name` should be the exact match. Use double quotes if the name contains spaces.
186
- * `version` can be used together with the `name` to specify a particular version. When `name` is provided without `version`, the latest version is used.
187
- * `checksum` and `archiveFileName` can be used as they both uniquely identify a library.
188
-
189
- #### Installing From a URL
190
-
191
- 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.
192
-
193
- #### Generated "lock" file — `Arlifile.<format>`
194
-
195
- Whenever `bundle` command succeeds, it will create a "lock" file in the same folder where the `Arlifile` file is located.
196
-
197
- The purpose of this file is to list in a machine-parseable way the *fully-resolved* installed library folders.
198
-
199
- There are four lock file formats that are supported, and they can be passed in with the `-f format` eg `--format text` flags to the `bundle` command:
200
-
201
- * `text`
202
- * `json`
203
- * `yaml`
204
- * `cmake`
205
-
206
- 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.
207
-
208
- #### CMake Integration
209
-
210
- The CMake format is now fully supported, in tandem with `arduino-cmake` project.
211
-
212
- Below is the resulting `Arlifile.cmake` after running `arli bundle` on the above mentioned file.
213
-
214
- ![](docs/arlifile-cmake.png)
215
-
216
- See the `generate` command, which creates a new project with CMake enabled.
217
-
218
- If you create `build` folder and run `cmake ..` here is what you'll see:
219
-
220
- ![](docs/arli-cmake-build.png)
221
-
222
- Just run `make` or `make upload` right after build and upload your firmware.
223
268
 
224
269
  <a name="install-command"></a>
225
270
 
226
- ## Command `install`
271
+ ### Command `install`
227
272
 
228
273
  Use this command to install a single library by either a name or URL:
229
274
 
@@ -236,7 +281,7 @@ Eg:
236
281
 
237
282
  <a name="search-command"></a>
238
283
 
239
- ## Command `search`
284
+ ### Command `search`
240
285
 
241
286
  To search Arduino library database, you can use the search command.
242
287
 
@@ -301,8 +346,27 @@ With `-m LIMIT` flag you can limit number of results. But in our case above we p
301
346
 
302
347
  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.
303
348
 
349
+ <a name="discussion"></a>
350
+
304
351
  ## Discussion
305
352
 
353
+ ### Who is Arli For?
354
+
355
+ _Arli is ideally suited for C/C++ programmers who have some basic knowledge of CMake, and who want to build larger-than-trivial projects on Arduino platform. Arli promotes use and reuse of libraries, which help take advantage of the Object Oriented Design Patterns, decoupling your code into reusable libraries._
356
+
357
+ Having said that, Arli is also helpful for projects that do NOT use CMake. It can be used purely as a library manager, or GitHub repo downloader.
358
+
359
+ ### Why not the Arduino IDE?
360
+
361
+ Arduino IDE is not meant for professional engineers — it's a fantastic educational tool for students. And while it lacks basic features of C/C++ development it succeeds in making Arduino programming accessible to young kids and students.
362
+
363
+ ### Why not Platform.IO?
364
+
365
+ [PlatformIO](http://platformio.org/) is a great "eco-system" that includes not just Arduino, but many other boards, provides integrated library manager, and Atom as the primary IDE. It's a fantastic tool for beginner/intermediate developers, much better than Arduino IDE.
366
+
367
+ But it's not without its downsides: to some — PlatformIO feels *too heavy*. It comes with a gazillion additional features you'll never use and it tries to be too much all at once. Perhaps for some people — it can be a feature. But for the author and other members of the Arduino dev community, PlatformIO design goes against the fundamental principals of [Unix Philosophy](https://en.wikipedia.org/wiki/Unix_philosophy), which promotes a minimalist, modular software development delegated to specialized commands that can be all interconnected (think `grep`, `awk`, `sort`, `uniq`).
368
+
369
+
306
370
  ### More Reasons Why Arli is Needed
307
371
 
308
372
  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?**
@@ -316,6 +380,15 @@ Arli is both an *Arduino Library Manager* and a project generator. If you are us
316
380
  * 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).
317
381
 
318
382
 
383
+ ### Working with Complex Projects
384
+
385
+ Arli shines when you need to build a complicated and multi-dependency project using an Arduino compatible board such as [Teensy](https://www.pjrc.com/teensy/), which has 16x more RAM than the Arduino UNO, and therefore allows you to take advantage of many more third-party Arduino libraries at once within a single project.
386
+
387
+ > A few years ago the author built a complex project called [**Filx Capacitor**](https://github.com/kigster/flix-capacitor), which relied on **ten** external libraries. Managing these dependencies was very time-consuming. Asking someone else to build this project on their system was near impossible. Not just that, but even for the author himself, after taking some time off and returning to the project — it was still difficult to figure out why it was suddenly refusing to build. So many things could have gone wrong.
388
+ >
389
+ > This is the problem Arli (together with the very powerful `arduino-cmake` project) attempts to solve. Your project's dependencies can be cleanly defined in a YAML file called `Arlifile`, together with an optional board name and a CPU. Next, you add a bunch of C/C++ files to the folder, update `CMakeLists.txt` file and rebuild the project, upload the firmware, or connect to the serial port. See [arli-cmake](https://github.com/kigster/arli-cmake#manual-builds) for more information.
390
+
391
+
319
392
  ## Development
320
393
 
321
394
  After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
data/Rakefile CHANGED
@@ -11,6 +11,10 @@ task :clean do
11
11
  shell('rm -rf pkg/ tmp/ coverage/ doc/ spec/fixtures/file5/libraries' )
12
12
  end
13
13
 
14
+ task :gem => [:build] do
15
+ shell('gem install pkg/*')
16
+ end
17
+
14
18
  task :permissions => [ :clean ] do
15
19
  shell("chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*")
16
20
  shell("find . -type d -exec chmod o+x,g+x {} \\;")
@@ -32,20 +32,23 @@ Gem::Specification.new do |spec|
32
32
  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
33
33
  spec.require_paths = ['lib']
34
34
 
35
- spec.add_dependency 'arduino-library', '~> 0.5.4'
35
+ spec.add_dependency 'arduino-library', '=0.5.5'
36
+
36
37
  spec.add_dependency 'awesome_print'
37
38
  spec.add_dependency 'colored2'
39
+
38
40
  spec.add_dependency 'dry-configurable'
39
- spec.add_dependency 'dry-struct'
40
41
  spec.add_dependency 'dry-types'
41
- spec.add_dependency 'hashie'
42
- spec.add_dependency 'require_dir'
42
+ spec.add_dependency 'dry-struct'
43
+
44
+ spec.add_dependency 'hashie', '~> 3.5'
45
+ spec.add_dependency 'require_dir', '~> 2'
43
46
  spec.add_dependency 'tty-cursor'
44
47
 
45
48
  spec.add_development_dependency 'aruba'
46
49
  spec.add_development_dependency 'bundler', '~> 1.15'
47
50
  spec.add_development_dependency 'rake', '~> 10.0'
48
- spec.add_development_dependency 'rspec', '~> 3.0'
51
+ spec.add_development_dependency 'rspec', '~> 3'
49
52
  spec.add_development_dependency 'rspec-its'
50
53
  spec.add_development_dependency 'simplecov'
51
54
  spec.add_development_dependency 'yard'
@@ -1,8 +1,7 @@
1
1
  require 'require_dir'
2
2
 
3
3
  module Arli
4
- extend RequireDir
5
- init __FILE__
4
+ RequireDir.enable_require_dir!(self, __FILE__)
6
5
  end
7
6
 
8
7
  require 'arduino/library'
@@ -55,6 +55,7 @@ module Arli
55
55
  ensure
56
56
  d = Arli.config.libraries.temp_dir
57
57
  FileUtils.rm_rf(d) if Dir.exist?(d) rescue nil
58
+ __pt
58
59
  end
59
60
 
60
61
  def parse_global_flags
@@ -18,6 +18,10 @@ module Arli
18
18
  self.lock_file = Arli::Lock::File.new(config: config, arlifile: arlifile)
19
19
  end
20
20
 
21
+ def additional_info
22
+ "\nArlifile Path: #{arlifile.arlifile_path.magenta}\nLock Format: #{config.arlifile.lock_format.to_s.yellow}\n"
23
+ end
24
+
21
25
  def params
22
26
  if arlifile&.libraries
23
27
  "libraries: \n • " + arlifile.libraries.map(&:name).join("\n • ")
@@ -21,7 +21,6 @@ module Arli
21
21
  include ::Arli::Library
22
22
 
23
23
  def setup
24
- super
25
24
  self.install_argument = runtime.argv.first
26
25
  raise InvalidInstallSyntaxError,
27
26
  'Missing installation argument: a name, a file or a URL.' unless install_argument
@@ -71,7 +70,7 @@ module Arli
71
70
  end
72
71
 
73
72
  def params
74
- " • #{library.to_s}"
73
+ nil
75
74
  end
76
75
 
77
76
  def post_install
@@ -143,20 +143,20 @@ module Arli
143
143
  end
144
144
 
145
145
  def header(command: nil)
146
- out = "\n#{hr}\n"
147
- out << "Arli (#{::Arli::VERSION.yellow})"
148
- out << ", Command: #{command.name.to_s.magenta.bold}" if command
146
+ out = "#{hr}\n"
147
+ out << 'Arli '.bold.red + "(#{::Arli::VERSION.yellow})"
148
+ out << ", executing command #{command.name.to_s.blue.bold}" if command
149
149
  if command && command.params && Arli.config.verbose
150
- out << "\n#{command.params.to_s.blue}\n"
150
+ out << "\n#{command.params.to_s.bold.magenta}\n"
151
151
  end
152
152
  out << command.additional_info if command.respond_to?(:additional_info)
153
- out << "Library Path: #{Arli.default_library_path.green}\n"
153
+ out << "Library Path: #{Arli.default_library_path.bold.green}\n"
154
154
  out << "#{hr}"
155
155
  info out
156
156
  end
157
157
 
158
158
  def hr
159
- ('—' * ((ENV['COLUMNS'] || 70).to_i - 1)).red.dark
159
+ ('—' * ((ENV['COLUMNS'] || 70).to_i - 1)).bold.black
160
160
  end
161
161
 
162
162
  # Some shortcuts
@@ -5,6 +5,8 @@ require 'arli/errors'
5
5
 
6
6
  module Arli
7
7
  module Library
8
+ ADDITIONAL_KEYS = %i(depends headers_only)
9
+
8
10
  def library_model(lib)
9
11
  return lib if lib.is_a?(::Arduino::Library::Model)
10
12
  ::Arduino::Library::Model.from(lib).tap do |model|
@@ -20,7 +22,19 @@ module Arli
20
22
  end
21
23
 
22
24
  def make_lib(lib)
23
- ::Arli::Library::SingleVersion.new(library_model(lib))
25
+ additional_keys = {}
26
+ ADDITIONAL_KEYS.each do |k|
27
+ if lib.is_a?(Hash) && lib[k]
28
+ additional_keys[k] = lib[k]
29
+ lib.delete(k)
30
+ end
31
+ end
32
+
33
+ ::Arli::Library::SingleVersion.new(library_model(lib)).tap do |svlib|
34
+ additional_keys.each_pair do |key, value|
35
+ svlib.send("#{key}=", value)
36
+ end
37
+ end
24
38
  end
25
39
  end
26
40
  end
@@ -34,7 +34,7 @@ module Arli
34
34
  run_action(action)
35
35
  end
36
36
  end
37
- ___ "\n\n"
37
+ ___ "\n"
38
38
  end
39
39
 
40
40
  def run_action(action_name)
@@ -12,14 +12,18 @@ module Arli
12
12
  attr_accessor :lib,
13
13
  :lib_dir,
14
14
  :canonical_dir,
15
- :config,
16
- :headers_only
15
+ :config
16
+
17
+ # Additional attributes that can be set via Arlifile
18
+ attr_accessor :headers_only,
19
+ :depends
17
20
 
18
21
  def initialize(lib, config: Arli.config)
19
22
  self.lib = lib
20
23
  self.config = config
21
24
  self.lib_dir = lib.name.gsub(/ /, '_')
22
25
  self.headers_only = false
26
+ self.depends = nil
23
27
  end
24
28
 
25
29
  def install
@@ -56,7 +60,7 @@ module Arli
56
60
 
57
61
  def inspect
58
62
  <<-EOF
59
- Library: #{lib.name} (#{lib.url}), only headers? #{headers_only ? 'YES': 'NO'}
63
+ Library: #{lib.name} (#{lib.url}), only headers? #{headers_only ? 'YES' : 'NO'}
60
64
  EOF
61
65
  end
62
66
 
@@ -10,8 +10,11 @@
10
10
  #
11
11
  # arli generate MyTestProject --workspace ~/workspace
12
12
  # cd ~/workspace/MyTestProject
13
- # bin/setup
14
- # bin/build src
13
+ # mkdir build; cd build
14
+ # cmake ..
15
+ # make <— builds your firmware
16
+ # make upload <— uploads your firmware to the device
17
+ # make MyTestProject-serial <— starts a screen session with serial connection
15
18
  #
16
19
  # And you should see a binary image built for the default board, or the
17
20
  # board you specified in the Arlifile.
@@ -32,18 +35,17 @@ set(ARLI_ARDUINO_HARDWARE_LIBS <% hardware_libraries.each do |library| %>
32
35
  set(ARLI_ARDUINO_LIBS <% arduino_libraries.each do |library| %>
33
36
  <%= library.name %><% end %>)
34
37
 
35
- <% device_libraries_headers_only.each do |library| %>
36
- set(<%= library.name %>_ONLY_HEADER yes)<% end %>
37
- <% custom_libraries_headers_only.each do |library| %>
38
- set(<%= library.canonical_dir %>_ONLY_HEADER yes)<% end %>
38
+ <% libraries.each do |library| %><% if library.depends %><%= cmake_dependencies(library) %><% end %><% end %>
39
+
40
+ <% device_libraries_headers_only.each do |library| %>set(<%= library.name %>_ONLY_HEADER yes)<% end %>
41
+ <% custom_libraries_headers_only.each do |library| %>set(<%= library.canonical_dir %>_ONLY_HEADER yes)<% end %>
39
42
 
40
43
  include(Arli)
41
44
 
42
45
  arli_detect_serial_device("/dev/null")
43
- arli_detect_board("<%= board %>" "<%= cpu %>")
44
-
45
- message(STATUS "device: [${BOARD_DEVICE}], board: [${BOARD_NAME}], cpu: [${BOARD_CPU}] <<<")
46
46
 
47
- arli_build_all_libraries()
47
+ <% if board && cpu %>arli_detect_board("<%= board %>" "<%= cpu %>")<% end %>
48
48
 
49
+ message(STATUS "HARDWARE:\n • BOARD_DEVICE=[${BOARD_DEVICE}]\n • BOARD_NAME=[${BOARD_NAME}]\n • BOARD_CPU=[${BOARD_CPU}]")
49
50
 
51
+ arli_build_all_libraries()
@@ -66,6 +66,24 @@ module Arli
66
66
  config.libraries.path
67
67
  end
68
68
 
69
+ def libraries_with_dependencies
70
+ libraries.select(&:depends)
71
+ end
72
+
73
+ def library_by_name(name)
74
+ libraries.find { |l| l.name.downcase == name.downcase }
75
+ end
76
+
77
+ def dependencies(lib)
78
+ return nil unless lib.depends
79
+ lib.depends.map { |name| library_by_name(name) }
80
+ end
81
+
82
+ def cmake_dependencies(lib)
83
+ return nil unless lib.depends
84
+ "set(#{lib.canonical_dir}_DEPENDS_ON_LIBS #{dependencies(lib).map(&:canonical_dir).join(' ')})"
85
+ end
86
+
69
87
  def arli_library_path
70
88
  if library_path.start_with?('/')
71
89
  "#{library_path}"
@@ -1,3 +1,3 @@
1
1
  module Arli
2
- VERSION = '1.1.0'.freeze
2
+ VERSION = '1.2.1'.freeze
3
3
  end
metadata CHANGED
@@ -1,29 +1,29 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: arli
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.1.0
4
+ version: 1.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Konstantin Gredeskoul
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2018-01-03 00:00:00.000000000 Z
11
+ date: 2018-07-04 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: arduino-library
15
15
  requirement: !ruby/object:Gem::Requirement
16
16
  requirements:
17
- - - "~>"
17
+ - - '='
18
18
  - !ruby/object:Gem::Version
19
- version: 0.5.4
19
+ version: 0.5.5
20
20
  type: :runtime
21
21
  prerelease: false
22
22
  version_requirements: !ruby/object:Gem::Requirement
23
23
  requirements:
24
- - - "~>"
24
+ - - '='
25
25
  - !ruby/object:Gem::Version
26
- version: 0.5.4
26
+ version: 0.5.5
27
27
  - !ruby/object:Gem::Dependency
28
28
  name: awesome_print
29
29
  requirement: !ruby/object:Gem::Requirement
@@ -67,7 +67,7 @@ dependencies:
67
67
  - !ruby/object:Gem::Version
68
68
  version: '0'
69
69
  - !ruby/object:Gem::Dependency
70
- name: dry-struct
70
+ name: dry-types
71
71
  requirement: !ruby/object:Gem::Requirement
72
72
  requirements:
73
73
  - - ">="
@@ -81,7 +81,7 @@ dependencies:
81
81
  - !ruby/object:Gem::Version
82
82
  version: '0'
83
83
  - !ruby/object:Gem::Dependency
84
- name: dry-types
84
+ name: dry-struct
85
85
  requirement: !ruby/object:Gem::Requirement
86
86
  requirements:
87
87
  - - ">="
@@ -98,30 +98,30 @@ dependencies:
98
98
  name: hashie
99
99
  requirement: !ruby/object:Gem::Requirement
100
100
  requirements:
101
- - - ">="
101
+ - - "~>"
102
102
  - !ruby/object:Gem::Version
103
- version: '0'
103
+ version: '3.5'
104
104
  type: :runtime
105
105
  prerelease: false
106
106
  version_requirements: !ruby/object:Gem::Requirement
107
107
  requirements:
108
- - - ">="
108
+ - - "~>"
109
109
  - !ruby/object:Gem::Version
110
- version: '0'
110
+ version: '3.5'
111
111
  - !ruby/object:Gem::Dependency
112
112
  name: require_dir
113
113
  requirement: !ruby/object:Gem::Requirement
114
114
  requirements:
115
- - - ">="
115
+ - - "~>"
116
116
  - !ruby/object:Gem::Version
117
- version: '0'
117
+ version: '2'
118
118
  type: :runtime
119
119
  prerelease: false
120
120
  version_requirements: !ruby/object:Gem::Requirement
121
121
  requirements:
122
- - - ">="
122
+ - - "~>"
123
123
  - !ruby/object:Gem::Version
124
- version: '0'
124
+ version: '2'
125
125
  - !ruby/object:Gem::Dependency
126
126
  name: tty-cursor
127
127
  requirement: !ruby/object:Gem::Requirement
@@ -184,14 +184,14 @@ dependencies:
184
184
  requirements:
185
185
  - - "~>"
186
186
  - !ruby/object:Gem::Version
187
- version: '3.0'
187
+ version: '3'
188
188
  type: :development
189
189
  prerelease: false
190
190
  version_requirements: !ruby/object:Gem::Requirement
191
191
  requirements:
192
192
  - - "~>"
193
193
  - !ruby/object:Gem::Version
194
- version: '3.0'
194
+ version: '3'
195
195
  - !ruby/object:Gem::Dependency
196
196
  name: rspec-its
197
197
  requirement: !ruby/object:Gem::Requirement
@@ -329,7 +329,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
329
329
  version: '0'
330
330
  requirements: []
331
331
  rubyforge_project:
332
- rubygems_version: 2.6.13
332
+ rubygems_version: 2.6.14
333
333
  signing_key:
334
334
  specification_version: 4
335
335
  summary: This is an Arduino helper toolkit that builds on top of the arduino-cmake