lib-installer 3.0.1__tar.gz → 4.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {lib_installer-3.0.1 → lib_installer-4.0.0}/PKG-INFO +232 -7
- {lib_installer-3.0.1 → lib_installer-4.0.0}/README.md +231 -6
- {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/PKG-INFO +232 -7
- {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/SOURCES.txt +1 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/__init__.py +1 -1
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/arduino.py +9 -1
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/manifest.py +66 -2
- lib_installer-4.0.0/src/core/titles.py +260 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/yamlreader.py +64 -3
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/esp32.py +181 -39
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/project.py +34 -11
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/ini.py +89 -28
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/pio.py +164 -25
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/stm32.py +4 -1
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/zephyr/app.py +125 -24
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/zephyr/module.py +116 -27
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/zephyr/zephyr.py +379 -49
- {lib_installer-3.0.1 → lib_installer-4.0.0}/LICENSE +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/dependency_links.txt +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/entry_points.txt +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/top_level.txt +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/pyproject.toml +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/setup.cfg +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/__main__.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/__init__.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/properties.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/sketchbook.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/cli.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/__init__.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/blocks.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/cli.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/console.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/download.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/files.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/installer.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/steps.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/target.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/updates.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/usercode.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/__init__.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/component.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/__init__.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/library_json.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/__init__.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/checks.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/__init__.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/base.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/cmake.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/cubeide.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/iar.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/keil.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/makefile.py +0 -0
- {lib_installer-3.0.1 → lib_installer-4.0.0}/src/zephyr/__init__.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: lib-installer
|
|
3
|
-
Version:
|
|
3
|
+
Version: 4.0.0
|
|
4
4
|
Summary: Install embedded C libraries into STM32, Zephyr, ESP-IDF, Arduino and PlatformIO projects
|
|
5
5
|
Author-email: "Nima Askari (NimaLTD)" <nima.askari@gmail.com>
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -75,7 +75,7 @@ When a newer lib-installer is out, the last line of a run says so, with the comm
|
|
|
75
75
|
A library can need a newer installer than the one you have. It then says so and changes nothing:
|
|
76
76
|
|
|
77
77
|
```
|
|
78
|
-
Error: This library needs lib-installer
|
|
78
|
+
Error: This library needs lib-installer 4.1.0 or newer, and this one is 4.0.0. Nothing was changed.
|
|
79
79
|
Update it with:
|
|
80
80
|
pip install --upgrade lib-installer
|
|
81
81
|
```
|
|
@@ -144,6 +144,7 @@ Each command with `owner/example` standing for the library. An update is the ins
|
|
|
144
144
|
| Leave a step unrun, without the question | `lib-installer owner/example --no-run make-key` |
|
|
145
145
|
| Answer every question with the answer offered, and run every step, for a script | `lib-installer owner/example --yes` |
|
|
146
146
|
| Install from a private repository | `lib-installer owner/example --key github_pat_...` |
|
|
147
|
+
| Give the token once, for every run after | `GITHUB_TOKEN` set to it, see [A private repository](#a-private-repository) |
|
|
147
148
|
| Leave out the check for a newer installer | `lib-installer owner/example --no-update-check` |
|
|
148
149
|
| STM32: register with one IDE only, of `cmake`, `cubeide`, `keil`, `iar` and `makefile` | `lib-installer owner/example --ide cubeide` |
|
|
149
150
|
| Zephyr: choose the Kconfig file the libraries are switched on in | `lib-installer owner/example --conf boards/x.conf` |
|
|
@@ -155,6 +156,44 @@ Each command with `owner/example` standing for the library. An update is the ins
|
|
|
155
156
|
| Uninstall several, in any order | `lib-installer --uninstall osal example` |
|
|
156
157
|
| Run it when `lib-installer` is not found | `python -m lib_installer owner/example` |
|
|
157
158
|
|
|
159
|
+
### Every feature
|
|
160
|
+
|
|
161
|
+
What lib-installer does, and how. The version is the oldest a library's `installer.yml` has to ask for, under `requires.lib_installer`, to use it; with none given, every version does it. The keys of `installer.yml` are under [For someone writing a library](#for-someone-writing-a-library), and those of one platform on its page.
|
|
162
|
+
|
|
163
|
+
| Feature | How | Since |
|
|
164
|
+
|---|---|---|
|
|
165
|
+
| A library from GitHub, by owner and name, or one release, branch or commit of it | `lib-installer owner/example`, `owner/example@v2.0.0` or `--ref`, see [What to install](#what-to-install) | |
|
|
166
|
+
| A library from a downloaded zip or a folder, without internet | `lib-installer D:/Downloads/example-main.zip`, see [Without internet](#without-internet) | |
|
|
167
|
+
| Several libraries in one run | `lib-installer owner/example owner/other` | |
|
|
168
|
+
| A library in a private repository | `--key`, or `GITHUB_TOKEN`, see [A private repository](#a-private-repository) | |
|
|
169
|
+
| Through a proxy, every file tried again on a bad connection | `HTTPS_PROXY`, see [On a bad connection](#on-a-bad-connection) | |
|
|
170
|
+
| One `installer.yml` for every platform | `platform: [stm32, zephyr, esp32, arduino, pio]`, `--platform`, see [Which platform](#which-platform) | 3.0.0 |
|
|
171
|
+
| A library that does not fit refused before anything is written: another platform, a newer installer, an option of another platform | | |
|
|
172
|
+
| The libraries it needs, installed first, each at a version that will do | `requires.libraries`, with `>=`; with `@` a release of its own, and with `manifest` one for a repository with no `installer.yml`, see [A library that needs another](#a-library-that-needs-another) | `@` and `manifest`: 2.0.0 |
|
|
173
|
+
| Parts of a library the user chooses | `options`, `--with`, `--without`, see [Parts you choose](#parts-you-choose) | |
|
|
174
|
+
| An update that keeps the user's settings | `USER CODE BEGIN` and `END` in the library's files; anything else of the user's saved as a `.bak`, see [Updating a library](#updating-a-library) | |
|
|
175
|
+
| Files that become the project's own, made once and never written over | `once`, see [Files that become yours](#files-that-become-yours) | 2.0.0 |
|
|
176
|
+
| Steps run once the files are in, each asked about first | `run`, `--run`, `--no-run`, `--yes`, see [Steps a library runs](#steps-a-library-runs) | 2.0.0 |
|
|
177
|
+
| Every file at the path it has in the repository; wildcards; paths from the project's folder, `{library}` for the library's | `src/**/*.c`, `to`, `{library}` | 2.1.0 |
|
|
178
|
+
| The library's own files in the project's folder, such as its tools | `extras` with `root` | 2.1.0 |
|
|
179
|
+
| An uninstall that gives the project's files back to the byte | `--uninstall`, see [Uninstalling a library](#uninstalling-a-library) | |
|
|
180
|
+
| A record of what is installed, from where, down to the commit | `.lib-installer.json`, kept with the project | |
|
|
181
|
+
| A project of one of the five installers moved over | by itself, on the first run, see [Moving over](#moving-over-from-the-five-installers) | 3.0.0 |
|
|
182
|
+
| A key given twice in one place refused, where YAML would keep the last without a word | | 4.0.0 |
|
|
183
|
+
| A key a platform's section does not have, such as a misspelt one, refused, with the keys it holds; a manifest asking for less is told about it, and installs as it did | | 4.0.0 |
|
|
184
|
+
| The folders of the include path checked before any project file gets them: inside the library, and nothing an IDE's file would read as more than a path | `install.include_dirs` | |
|
|
185
|
+
| STM32: registered with CMake, STM32CubeIDE, Keil MDK, IAR or CubeMX's Makefile; HAL modules, peripherals and RTOS checked against the project | `--ide`, `requires.hal_modules`, `requires.peripherals`, `requires.rtos`, see [STM32](https://github.com/nimaltd/lib-installer/blob/main/docs/stm32.md) | |
|
|
186
|
+
| Zephyr: a module of the application, switched on in `prj.conf`, its settings in Kconfig and menuconfig | `zephyr.symbol`, `zephyr.settings`, `--conf`, see [Zephyr](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md) | |
|
|
187
|
+
| Zephyr: every line it writes under where it goes, the application's own files or its own folder | `zephyr.project`: `conf`, `sysbuild`, `cmake`; `zephyr.library`: `kconfig`, `conf`, `cmake` | 4.0.0 |
|
|
188
|
+
| Zephyr: lists in groups under their titles, a setting with a note, written into the files as comments | see [Titles and notes](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#titles-and-notes-from-400) | 4.0.0 |
|
|
189
|
+
| ESP-IDF: a component, its settings in menuconfig, its lines in `sdkconfig.defaults` and in CMake | `esp32.settings`, `esp32.project`, `esp32.library`, see [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md) | |
|
|
190
|
+
| ESP-IDF: every line it writes under where it goes, the project's own files or its component | `esp32.project`: `conf`, `cmake`; `esp32.library`: `requires`, `cmake`; before, `requires.kconfig`, `esp32.requires` and `esp32.cmake` | 4.0.0 |
|
|
191
|
+
| ESP-IDF: lists in groups under their titles, a symbol with a note, written into the files as comments | see [Titles and notes](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#titles-and-notes-from-400) | 4.0.0 |
|
|
192
|
+
| Arduino: into the libraries folder, for every sketch, or into one sketch, with its `library.properties` | `--into`, `--sketchbook`, `arduino`, see [Arduino](https://github.com/nimaltd/lib-installer/blob/main/docs/arduino.md) | |
|
|
193
|
+
| PlatformIO: into `lib/`, with its `library.json`, and its defines in `platformio.ini` | `pio.library`, `install.defines`, see [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md) | |
|
|
194
|
+
| PlatformIO: flags for every file of the build, in groups under their titles and with notes, as comments of `platformio.ini` | `pio.project.build_flags`, see [Build flags](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#build-flags) | 4.0.0 |
|
|
195
|
+
| PlatformIO: what goes into `library.json` under `library` | `pio.library`: `frameworks`, `platforms`, `dependencies`; before, right under `pio` | 4.0.0 |
|
|
196
|
+
|
|
158
197
|
### On a bad connection
|
|
159
198
|
|
|
160
199
|
A file that does not arrive is tried again, five times in all, 1, 2, 4 and 8 seconds apart. The tries take turns between `raw.githubusercontent.com` and `api.github.com`, two hosts on different addresses, so one that is filtered or failing does not stop the install. Every file of every library is fetched before anything is installed, so a run that fails part way leaves your project as it was: run it again.
|
|
@@ -183,10 +222,10 @@ On a machine that has internet, save the installer as a file:
|
|
|
183
222
|
pip download lib-installer
|
|
184
223
|
```
|
|
185
224
|
|
|
186
|
-
That saves one file, such as `lib_installer-
|
|
225
|
+
That saves one file, such as `lib_installer-4.0.0-py3-none-any.whl`, where the number is the installer's version. Download the library too, from the green **Code** button, **Download ZIP**. Copy both to the machine that has no internet, then from your project:
|
|
187
226
|
|
|
188
227
|
```bash
|
|
189
|
-
pip install lib_installer-
|
|
228
|
+
pip install lib_installer-4.0.0-py3-none-any.whl
|
|
190
229
|
lib-installer D:/Downloads/example-main.zip
|
|
191
230
|
```
|
|
192
231
|
|
|
@@ -482,7 +521,7 @@ Moved over from zephyr-installer to lib-installer: CMakeLists.txt, prj.conf, .li
|
|
|
482
521
|
|
|
483
522
|
Put an `installer.yml` at the root of the repository. Any library can have one, whoever wrote it, and the one file serves every platform: each reads its own section and leaves the others' alone. Releases before 1.9.0 called it `library.yml`, and the installer still reads that name when there is no `installer.yml`.
|
|
484
523
|
|
|
485
|
-
The keys every platform reads are below, as a manifest asking for
|
|
524
|
+
The keys every platform reads are below, as a manifest asking for 4.0.0 writes them. Only `name`, `platform` and its `headers` or `sources` are required; leave out what your library does not need. The keys of one platform, such as `zephyr:` or `requires.hal_modules`, are on that platform's page, with what it does with the rest: [STM32](https://github.com/nimaltd/lib-installer/blob/main/docs/stm32.md#for-someone-writing-a-library), [Zephyr](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#for-someone-writing-a-library), [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#for-someone-writing-a-library), [Arduino](https://github.com/nimaltd/lib-installer/blob/main/docs/arduino.md#for-someone-writing-a-library) and [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#for-someone-writing-a-library).
|
|
486
525
|
|
|
487
526
|
```yaml
|
|
488
527
|
name: example # the library's name, and its folder in the project
|
|
@@ -494,7 +533,7 @@ platform: [stm32, zephyr] # the platforms it works on: one name, or a l
|
|
|
494
533
|
version: 1.0.0 # only when the first header has no @version tag
|
|
495
534
|
|
|
496
535
|
requires:
|
|
497
|
-
lib_installer:
|
|
536
|
+
lib_installer: 4.0.0 # the oldest lib-installer that reads this file
|
|
498
537
|
libraries: # other libraries, installed first when missing
|
|
499
538
|
- osal >= 1.0.0 # no owner means nimaltd; >= the oldest that will do
|
|
500
539
|
- owner/lib@v1.2.0 # a tag, branch or commit, not its default branch
|
|
@@ -533,7 +572,7 @@ extras: # copied as they are, never compiled
|
|
|
533
572
|
|
|
534
573
|
`requires.lib_installer` is the oldest lib-installer that reads the file correctly. It is checked before anything else in the file is read, so when a manifest starts using something only a newer installer understands, raising this makes an older one stop with a message saying to update, rather than read the file wrongly without a word. Write it as three numbers, `3.0.0`: unquoted, YAML reads `1.10` as the decimal number `1.1`, and that is refused.
|
|
535
574
|
|
|
536
|
-
The keys of the five installers before 3.0.0, `requires.stm32_installer`, `requires.zephyr_installer`, `requires.esp32_installer`, `requires.arduino_installer`, `requires.pio_installer`, and `requires.installer` from before 2.0.0, are still read, so a manifest written for one of them installs as it did. The version a manifest asks for decides how it reads: what 2.0.0 brought, such as `once` files in the project's folder and `run`, needs 2.0.0 or newer, and what 2.1.0 brought, every path starting at the project's folder, needs 2.1.0 or newer. A manifest asking for 3.0.0 reads as one asking for 2.1.0 does, and names its `platform`.
|
|
575
|
+
The keys of the five installers before 3.0.0, `requires.stm32_installer`, `requires.zephyr_installer`, `requires.esp32_installer`, `requires.arduino_installer`, `requires.pio_installer`, and `requires.installer` from before 2.0.0, are still read, so a manifest written for one of them installs as it did. The version a manifest asks for decides how it reads: what 2.0.0 brought, such as `once` files in the project's folder and `run`, needs 2.0.0 or newer, and what 2.1.0 brought, every path starting at the project's folder, needs 2.1.0 or newer. A manifest asking for 3.0.0 reads as one asking for 2.1.0 does, and names its `platform`. 4.0.0 gives the `zephyr` section a place for everything a Zephyr library writes, by where it goes: the library's switch is `zephyr.symbol`, what it writes into the application's own files, `prj.conf`, `sysbuild.conf` and `CMakeLists.txt`, is under `zephyr.project`, and what it writes into its own folder, its Kconfig, a Kconfig fragment read after `prj.conf` and its `CMakeLists.txt`, under `zephyr.library`. Each list can be given in groups under their titles, and a setting with a note, which the files written carry as comments. The `esp32` and `pio` sections get the same two parts: `esp32.project` for the project's `sdkconfig.defaults` and `CMakeLists.txt`, `esp32.library` for its component, `pio.project` for `platformio.ini` and `pio.library` for `library.json`, and `requires.kconfig` gives way to each platform's own `project.conf`. Arduino and STM32 keep their sections as they are: what they write lands in files that hold no comments, or in different files for each IDE. A manifest asking for 4.0.0 has the new places, and one asking for less keeps the old keys, as the [Zephyr](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#titles-and-notes-from-400), [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#where-each-line-goes-from-400) and [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#where-everything-goes-from-400) pages say. A key given twice in one place is refused from 4.0.0, by every platform: YAML would keep only the last without a word.
|
|
537
576
|
|
|
538
577
|
Leave `version` out. The installer reads the version from the `@version` tag in the file comment of the first header listed, so it is written in the code and nowhere else:
|
|
539
578
|
|
|
@@ -548,6 +587,192 @@ A step a library runs sees where things are in its environment: `INSTALLER_PROJE
|
|
|
548
587
|
|
|
549
588
|
There is no installer script to copy into the repository: put the install line from the top of this page in your README, with your library's name in it.
|
|
550
589
|
|
|
590
|
+
### Examples
|
|
591
|
+
|
|
592
|
+
**The smallest one.** A library of one header and one source, for one platform, needs no more than this:
|
|
593
|
+
|
|
594
|
+
```yaml
|
|
595
|
+
name: example
|
|
596
|
+
platform: zephyr
|
|
597
|
+
requires:
|
|
598
|
+
lib_installer: 4.0.0
|
|
599
|
+
headers:
|
|
600
|
+
- src/example.h
|
|
601
|
+
sources:
|
|
602
|
+
- src/example.c
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
**A driver that needs another library**, with a part the user chooses, a file that becomes the project's, and a step run once the files are in, here for an STM32 project:
|
|
606
|
+
|
|
607
|
+
```yaml
|
|
608
|
+
name: example
|
|
609
|
+
description: Driver for the X chip
|
|
610
|
+
platform: stm32
|
|
611
|
+
requires:
|
|
612
|
+
lib_installer: 4.0.0
|
|
613
|
+
libraries:
|
|
614
|
+
- osal >= 1.0.0 # installed first, when the project has none that new
|
|
615
|
+
headers:
|
|
616
|
+
- src/example.h
|
|
617
|
+
- src/example_config.h # the user's settings, between USER CODE lines
|
|
618
|
+
sources:
|
|
619
|
+
- src/example.c
|
|
620
|
+
options:
|
|
621
|
+
littlefs: # lib-installer owner/example --with littlefs
|
|
622
|
+
description: LittleFS file system on the flash
|
|
623
|
+
libraries:
|
|
624
|
+
- littlefs >= 2.11.0
|
|
625
|
+
sources:
|
|
626
|
+
- src/example_lfs.c
|
|
627
|
+
once:
|
|
628
|
+
- from: templates/example_port.c # made once, then the project's
|
|
629
|
+
to: Core/Src/example_port.c
|
|
630
|
+
extras:
|
|
631
|
+
- root: tools # tools/make_key.py, in the project's folder
|
|
632
|
+
run:
|
|
633
|
+
- label: make-key # lib-installer owner/example --run make-key
|
|
634
|
+
description: Make the product's key, product.key
|
|
635
|
+
script: tools/make_key.py
|
|
636
|
+
unless: product.key # skipped once the key is there
|
|
637
|
+
```
|
|
638
|
+
|
|
639
|
+
**A Zephyr library that says where each line goes**, the application's files under `project`, its own folder under `library`, each list in groups under their titles, and a setting with a note:
|
|
640
|
+
|
|
641
|
+
```yaml
|
|
642
|
+
name: example
|
|
643
|
+
platform: zephyr
|
|
644
|
+
requires:
|
|
645
|
+
lib_installer: 4.0.0
|
|
646
|
+
headers:
|
|
647
|
+
- src/example.h
|
|
648
|
+
sources:
|
|
649
|
+
- src/example.c
|
|
650
|
+
zephyr:
|
|
651
|
+
symbol: # CONFIG_EXAMPLE=y, last in its block in prj.conf,
|
|
652
|
+
EXAMPLE: the driver, and its defaults while it is on # with its note
|
|
653
|
+
project:
|
|
654
|
+
conf: # prj.conf, beside the switch, the user's to change
|
|
655
|
+
What the release build leaves out:
|
|
656
|
+
- LOG=n: no messages, and nowhere to send them
|
|
657
|
+
- ASSERT=n
|
|
658
|
+
library:
|
|
659
|
+
kconfig: # defaults in its Kconfig, while CONFIG_EXAMPLE is on
|
|
660
|
+
Bluetooth, as a peripheral:
|
|
661
|
+
- BT
|
|
662
|
+
- BT_PERIPHERAL
|
|
663
|
+
conf: # its Kconfig fragment, read after prj.conf
|
|
664
|
+
Bluetooth as fast as it goes:
|
|
665
|
+
- BT_AUTO_PHY_PERIPHERAL_2M: the 2M PHY as soon as a phone connects
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
Its block in the application's `prj.conf` then reads:
|
|
669
|
+
|
|
670
|
+
```
|
|
671
|
+
# >>> lib-installer: example >>>
|
|
672
|
+
# Added by lib-installer, and written again on every install, so set
|
|
673
|
+
# example's settings below this block rather than in it.
|
|
674
|
+
|
|
675
|
+
# ******************************************************************************
|
|
676
|
+
# What the release build leaves out
|
|
677
|
+
# ******************************************************************************
|
|
678
|
+
# no messages, and nowhere to send them
|
|
679
|
+
CONFIG_LOG=n
|
|
680
|
+
CONFIG_ASSERT=n
|
|
681
|
+
|
|
682
|
+
# ******************************************************************************
|
|
683
|
+
# example
|
|
684
|
+
# ******************************************************************************
|
|
685
|
+
# the driver, and its defaults while it is on
|
|
686
|
+
CONFIG_EXAMPLE=y
|
|
687
|
+
# <<< lib-installer: example <<<
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
The [Zephyr page](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#for-someone-writing-a-library) has every key of its section, and what each writes where.
|
|
691
|
+
|
|
692
|
+
**An ESP-IDF library that says where each line goes**, the project's files under `project`, its component under `library`, a list in groups under their titles, and a symbol with a note:
|
|
693
|
+
|
|
694
|
+
```yaml
|
|
695
|
+
name: example
|
|
696
|
+
platform: esp32
|
|
697
|
+
requires:
|
|
698
|
+
lib_installer: 4.0.0
|
|
699
|
+
headers:
|
|
700
|
+
- src/example.h
|
|
701
|
+
sources:
|
|
702
|
+
- src/example.c
|
|
703
|
+
esp32:
|
|
704
|
+
project:
|
|
705
|
+
conf: # its block in the project's sdkconfig.defaults
|
|
706
|
+
A faster tick:
|
|
707
|
+
- FREERTOS_HZ=1000: one tick a millisecond
|
|
708
|
+
cmake: # the project's CMakeLists.txt, by place
|
|
709
|
+
after-project:
|
|
710
|
+
- idf_component_get_property(main_lib main COMPONENT_LIB)
|
|
711
|
+
- target_compile_definitions(${main_lib} PRIVATE EXAMPLE_IN_MAIN)
|
|
712
|
+
library:
|
|
713
|
+
requires: [esp_timer] # REQUIRES of its component
|
|
714
|
+
cmake: # its component's CMakeLists.txt
|
|
715
|
+
Math:
|
|
716
|
+
- target_link_libraries(${COMPONENT_LIB} PRIVATE m)
|
|
717
|
+
```
|
|
718
|
+
|
|
719
|
+
Its block in the project's `sdkconfig.defaults` then reads:
|
|
720
|
+
|
|
721
|
+
```
|
|
722
|
+
# >>> lib-installer: example >>>
|
|
723
|
+
# Added by lib-installer, and written again on every install, so set
|
|
724
|
+
# example's symbols below this block rather than in it.
|
|
725
|
+
|
|
726
|
+
# ******************************************************************************
|
|
727
|
+
# A faster tick
|
|
728
|
+
# ******************************************************************************
|
|
729
|
+
# one tick a millisecond
|
|
730
|
+
CONFIG_FREERTOS_HZ=1000
|
|
731
|
+
# <<< lib-installer: example <<<
|
|
732
|
+
```
|
|
733
|
+
|
|
734
|
+
**A PlatformIO library with a flag for the whole build**, in `platformio.ini` under `project`, and what goes into its `library.json` under `library`:
|
|
735
|
+
|
|
736
|
+
```yaml
|
|
737
|
+
name: example
|
|
738
|
+
platform: pio
|
|
739
|
+
requires:
|
|
740
|
+
lib_installer: 4.0.0
|
|
741
|
+
install:
|
|
742
|
+
defines:
|
|
743
|
+
- EXAMPLE_FAST
|
|
744
|
+
headers:
|
|
745
|
+
- src/example.h
|
|
746
|
+
sources:
|
|
747
|
+
- src/example.c
|
|
748
|
+
pio:
|
|
749
|
+
project:
|
|
750
|
+
build_flags: # platformio.ini, after its defines, for every file
|
|
751
|
+
Printing:
|
|
752
|
+
- -Wl,-u,_printf_float: printf("%f") prints nothing without it
|
|
753
|
+
library: # its library.json, which has no comments
|
|
754
|
+
frameworks: [arduino]
|
|
755
|
+
dependencies:
|
|
756
|
+
- bblanchon/ArduinoJson@^7
|
|
757
|
+
```
|
|
758
|
+
|
|
759
|
+
Its block in `build_flags` of `platformio.ini`, a title and a note as comments of the file's:
|
|
760
|
+
|
|
761
|
+
```ini
|
|
762
|
+
[env]
|
|
763
|
+
build_flags =
|
|
764
|
+
; >>> lib-installer: example >>>
|
|
765
|
+
-DEXAMPLE_FAST
|
|
766
|
+
; ******************************************************************************
|
|
767
|
+
; Printing
|
|
768
|
+
; ******************************************************************************
|
|
769
|
+
; printf("%f") prints nothing without it
|
|
770
|
+
-Wl,-u,_printf_float
|
|
771
|
+
; <<< lib-installer: example <<<
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
The [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#for-someone-writing-a-library) and [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#for-someone-writing-a-library) pages have every key of their sections.
|
|
775
|
+
|
|
551
776
|
---
|
|
552
777
|
|
|
553
778
|
## Running the tests
|
|
@@ -57,7 +57,7 @@ When a newer lib-installer is out, the last line of a run says so, with the comm
|
|
|
57
57
|
A library can need a newer installer than the one you have. It then says so and changes nothing:
|
|
58
58
|
|
|
59
59
|
```
|
|
60
|
-
Error: This library needs lib-installer
|
|
60
|
+
Error: This library needs lib-installer 4.1.0 or newer, and this one is 4.0.0. Nothing was changed.
|
|
61
61
|
Update it with:
|
|
62
62
|
pip install --upgrade lib-installer
|
|
63
63
|
```
|
|
@@ -126,6 +126,7 @@ Each command with `owner/example` standing for the library. An update is the ins
|
|
|
126
126
|
| Leave a step unrun, without the question | `lib-installer owner/example --no-run make-key` |
|
|
127
127
|
| Answer every question with the answer offered, and run every step, for a script | `lib-installer owner/example --yes` |
|
|
128
128
|
| Install from a private repository | `lib-installer owner/example --key github_pat_...` |
|
|
129
|
+
| Give the token once, for every run after | `GITHUB_TOKEN` set to it, see [A private repository](#a-private-repository) |
|
|
129
130
|
| Leave out the check for a newer installer | `lib-installer owner/example --no-update-check` |
|
|
130
131
|
| STM32: register with one IDE only, of `cmake`, `cubeide`, `keil`, `iar` and `makefile` | `lib-installer owner/example --ide cubeide` |
|
|
131
132
|
| Zephyr: choose the Kconfig file the libraries are switched on in | `lib-installer owner/example --conf boards/x.conf` |
|
|
@@ -137,6 +138,44 @@ Each command with `owner/example` standing for the library. An update is the ins
|
|
|
137
138
|
| Uninstall several, in any order | `lib-installer --uninstall osal example` |
|
|
138
139
|
| Run it when `lib-installer` is not found | `python -m lib_installer owner/example` |
|
|
139
140
|
|
|
141
|
+
### Every feature
|
|
142
|
+
|
|
143
|
+
What lib-installer does, and how. The version is the oldest a library's `installer.yml` has to ask for, under `requires.lib_installer`, to use it; with none given, every version does it. The keys of `installer.yml` are under [For someone writing a library](#for-someone-writing-a-library), and those of one platform on its page.
|
|
144
|
+
|
|
145
|
+
| Feature | How | Since |
|
|
146
|
+
|---|---|---|
|
|
147
|
+
| A library from GitHub, by owner and name, or one release, branch or commit of it | `lib-installer owner/example`, `owner/example@v2.0.0` or `--ref`, see [What to install](#what-to-install) | |
|
|
148
|
+
| A library from a downloaded zip or a folder, without internet | `lib-installer D:/Downloads/example-main.zip`, see [Without internet](#without-internet) | |
|
|
149
|
+
| Several libraries in one run | `lib-installer owner/example owner/other` | |
|
|
150
|
+
| A library in a private repository | `--key`, or `GITHUB_TOKEN`, see [A private repository](#a-private-repository) | |
|
|
151
|
+
| Through a proxy, every file tried again on a bad connection | `HTTPS_PROXY`, see [On a bad connection](#on-a-bad-connection) | |
|
|
152
|
+
| One `installer.yml` for every platform | `platform: [stm32, zephyr, esp32, arduino, pio]`, `--platform`, see [Which platform](#which-platform) | 3.0.0 |
|
|
153
|
+
| A library that does not fit refused before anything is written: another platform, a newer installer, an option of another platform | | |
|
|
154
|
+
| The libraries it needs, installed first, each at a version that will do | `requires.libraries`, with `>=`; with `@` a release of its own, and with `manifest` one for a repository with no `installer.yml`, see [A library that needs another](#a-library-that-needs-another) | `@` and `manifest`: 2.0.0 |
|
|
155
|
+
| Parts of a library the user chooses | `options`, `--with`, `--without`, see [Parts you choose](#parts-you-choose) | |
|
|
156
|
+
| An update that keeps the user's settings | `USER CODE BEGIN` and `END` in the library's files; anything else of the user's saved as a `.bak`, see [Updating a library](#updating-a-library) | |
|
|
157
|
+
| Files that become the project's own, made once and never written over | `once`, see [Files that become yours](#files-that-become-yours) | 2.0.0 |
|
|
158
|
+
| Steps run once the files are in, each asked about first | `run`, `--run`, `--no-run`, `--yes`, see [Steps a library runs](#steps-a-library-runs) | 2.0.0 |
|
|
159
|
+
| Every file at the path it has in the repository; wildcards; paths from the project's folder, `{library}` for the library's | `src/**/*.c`, `to`, `{library}` | 2.1.0 |
|
|
160
|
+
| The library's own files in the project's folder, such as its tools | `extras` with `root` | 2.1.0 |
|
|
161
|
+
| An uninstall that gives the project's files back to the byte | `--uninstall`, see [Uninstalling a library](#uninstalling-a-library) | |
|
|
162
|
+
| A record of what is installed, from where, down to the commit | `.lib-installer.json`, kept with the project | |
|
|
163
|
+
| A project of one of the five installers moved over | by itself, on the first run, see [Moving over](#moving-over-from-the-five-installers) | 3.0.0 |
|
|
164
|
+
| A key given twice in one place refused, where YAML would keep the last without a word | | 4.0.0 |
|
|
165
|
+
| A key a platform's section does not have, such as a misspelt one, refused, with the keys it holds; a manifest asking for less is told about it, and installs as it did | | 4.0.0 |
|
|
166
|
+
| The folders of the include path checked before any project file gets them: inside the library, and nothing an IDE's file would read as more than a path | `install.include_dirs` | |
|
|
167
|
+
| STM32: registered with CMake, STM32CubeIDE, Keil MDK, IAR or CubeMX's Makefile; HAL modules, peripherals and RTOS checked against the project | `--ide`, `requires.hal_modules`, `requires.peripherals`, `requires.rtos`, see [STM32](https://github.com/nimaltd/lib-installer/blob/main/docs/stm32.md) | |
|
|
168
|
+
| Zephyr: a module of the application, switched on in `prj.conf`, its settings in Kconfig and menuconfig | `zephyr.symbol`, `zephyr.settings`, `--conf`, see [Zephyr](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md) | |
|
|
169
|
+
| Zephyr: every line it writes under where it goes, the application's own files or its own folder | `zephyr.project`: `conf`, `sysbuild`, `cmake`; `zephyr.library`: `kconfig`, `conf`, `cmake` | 4.0.0 |
|
|
170
|
+
| Zephyr: lists in groups under their titles, a setting with a note, written into the files as comments | see [Titles and notes](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#titles-and-notes-from-400) | 4.0.0 |
|
|
171
|
+
| ESP-IDF: a component, its settings in menuconfig, its lines in `sdkconfig.defaults` and in CMake | `esp32.settings`, `esp32.project`, `esp32.library`, see [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md) | |
|
|
172
|
+
| ESP-IDF: every line it writes under where it goes, the project's own files or its component | `esp32.project`: `conf`, `cmake`; `esp32.library`: `requires`, `cmake`; before, `requires.kconfig`, `esp32.requires` and `esp32.cmake` | 4.0.0 |
|
|
173
|
+
| ESP-IDF: lists in groups under their titles, a symbol with a note, written into the files as comments | see [Titles and notes](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#titles-and-notes-from-400) | 4.0.0 |
|
|
174
|
+
| Arduino: into the libraries folder, for every sketch, or into one sketch, with its `library.properties` | `--into`, `--sketchbook`, `arduino`, see [Arduino](https://github.com/nimaltd/lib-installer/blob/main/docs/arduino.md) | |
|
|
175
|
+
| PlatformIO: into `lib/`, with its `library.json`, and its defines in `platformio.ini` | `pio.library`, `install.defines`, see [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md) | |
|
|
176
|
+
| PlatformIO: flags for every file of the build, in groups under their titles and with notes, as comments of `platformio.ini` | `pio.project.build_flags`, see [Build flags](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#build-flags) | 4.0.0 |
|
|
177
|
+
| PlatformIO: what goes into `library.json` under `library` | `pio.library`: `frameworks`, `platforms`, `dependencies`; before, right under `pio` | 4.0.0 |
|
|
178
|
+
|
|
140
179
|
### On a bad connection
|
|
141
180
|
|
|
142
181
|
A file that does not arrive is tried again, five times in all, 1, 2, 4 and 8 seconds apart. The tries take turns between `raw.githubusercontent.com` and `api.github.com`, two hosts on different addresses, so one that is filtered or failing does not stop the install. Every file of every library is fetched before anything is installed, so a run that fails part way leaves your project as it was: run it again.
|
|
@@ -165,10 +204,10 @@ On a machine that has internet, save the installer as a file:
|
|
|
165
204
|
pip download lib-installer
|
|
166
205
|
```
|
|
167
206
|
|
|
168
|
-
That saves one file, such as `lib_installer-
|
|
207
|
+
That saves one file, such as `lib_installer-4.0.0-py3-none-any.whl`, where the number is the installer's version. Download the library too, from the green **Code** button, **Download ZIP**. Copy both to the machine that has no internet, then from your project:
|
|
169
208
|
|
|
170
209
|
```bash
|
|
171
|
-
pip install lib_installer-
|
|
210
|
+
pip install lib_installer-4.0.0-py3-none-any.whl
|
|
172
211
|
lib-installer D:/Downloads/example-main.zip
|
|
173
212
|
```
|
|
174
213
|
|
|
@@ -464,7 +503,7 @@ Moved over from zephyr-installer to lib-installer: CMakeLists.txt, prj.conf, .li
|
|
|
464
503
|
|
|
465
504
|
Put an `installer.yml` at the root of the repository. Any library can have one, whoever wrote it, and the one file serves every platform: each reads its own section and leaves the others' alone. Releases before 1.9.0 called it `library.yml`, and the installer still reads that name when there is no `installer.yml`.
|
|
466
505
|
|
|
467
|
-
The keys every platform reads are below, as a manifest asking for
|
|
506
|
+
The keys every platform reads are below, as a manifest asking for 4.0.0 writes them. Only `name`, `platform` and its `headers` or `sources` are required; leave out what your library does not need. The keys of one platform, such as `zephyr:` or `requires.hal_modules`, are on that platform's page, with what it does with the rest: [STM32](https://github.com/nimaltd/lib-installer/blob/main/docs/stm32.md#for-someone-writing-a-library), [Zephyr](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#for-someone-writing-a-library), [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#for-someone-writing-a-library), [Arduino](https://github.com/nimaltd/lib-installer/blob/main/docs/arduino.md#for-someone-writing-a-library) and [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#for-someone-writing-a-library).
|
|
468
507
|
|
|
469
508
|
```yaml
|
|
470
509
|
name: example # the library's name, and its folder in the project
|
|
@@ -476,7 +515,7 @@ platform: [stm32, zephyr] # the platforms it works on: one name, or a l
|
|
|
476
515
|
version: 1.0.0 # only when the first header has no @version tag
|
|
477
516
|
|
|
478
517
|
requires:
|
|
479
|
-
lib_installer:
|
|
518
|
+
lib_installer: 4.0.0 # the oldest lib-installer that reads this file
|
|
480
519
|
libraries: # other libraries, installed first when missing
|
|
481
520
|
- osal >= 1.0.0 # no owner means nimaltd; >= the oldest that will do
|
|
482
521
|
- owner/lib@v1.2.0 # a tag, branch or commit, not its default branch
|
|
@@ -515,7 +554,7 @@ extras: # copied as they are, never compiled
|
|
|
515
554
|
|
|
516
555
|
`requires.lib_installer` is the oldest lib-installer that reads the file correctly. It is checked before anything else in the file is read, so when a manifest starts using something only a newer installer understands, raising this makes an older one stop with a message saying to update, rather than read the file wrongly without a word. Write it as three numbers, `3.0.0`: unquoted, YAML reads `1.10` as the decimal number `1.1`, and that is refused.
|
|
517
556
|
|
|
518
|
-
The keys of the five installers before 3.0.0, `requires.stm32_installer`, `requires.zephyr_installer`, `requires.esp32_installer`, `requires.arduino_installer`, `requires.pio_installer`, and `requires.installer` from before 2.0.0, are still read, so a manifest written for one of them installs as it did. The version a manifest asks for decides how it reads: what 2.0.0 brought, such as `once` files in the project's folder and `run`, needs 2.0.0 or newer, and what 2.1.0 brought, every path starting at the project's folder, needs 2.1.0 or newer. A manifest asking for 3.0.0 reads as one asking for 2.1.0 does, and names its `platform`.
|
|
557
|
+
The keys of the five installers before 3.0.0, `requires.stm32_installer`, `requires.zephyr_installer`, `requires.esp32_installer`, `requires.arduino_installer`, `requires.pio_installer`, and `requires.installer` from before 2.0.0, are still read, so a manifest written for one of them installs as it did. The version a manifest asks for decides how it reads: what 2.0.0 brought, such as `once` files in the project's folder and `run`, needs 2.0.0 or newer, and what 2.1.0 brought, every path starting at the project's folder, needs 2.1.0 or newer. A manifest asking for 3.0.0 reads as one asking for 2.1.0 does, and names its `platform`. 4.0.0 gives the `zephyr` section a place for everything a Zephyr library writes, by where it goes: the library's switch is `zephyr.symbol`, what it writes into the application's own files, `prj.conf`, `sysbuild.conf` and `CMakeLists.txt`, is under `zephyr.project`, and what it writes into its own folder, its Kconfig, a Kconfig fragment read after `prj.conf` and its `CMakeLists.txt`, under `zephyr.library`. Each list can be given in groups under their titles, and a setting with a note, which the files written carry as comments. The `esp32` and `pio` sections get the same two parts: `esp32.project` for the project's `sdkconfig.defaults` and `CMakeLists.txt`, `esp32.library` for its component, `pio.project` for `platformio.ini` and `pio.library` for `library.json`, and `requires.kconfig` gives way to each platform's own `project.conf`. Arduino and STM32 keep their sections as they are: what they write lands in files that hold no comments, or in different files for each IDE. A manifest asking for 4.0.0 has the new places, and one asking for less keeps the old keys, as the [Zephyr](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#titles-and-notes-from-400), [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#where-each-line-goes-from-400) and [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#where-everything-goes-from-400) pages say. A key given twice in one place is refused from 4.0.0, by every platform: YAML would keep only the last without a word.
|
|
519
558
|
|
|
520
559
|
Leave `version` out. The installer reads the version from the `@version` tag in the file comment of the first header listed, so it is written in the code and nowhere else:
|
|
521
560
|
|
|
@@ -530,6 +569,192 @@ A step a library runs sees where things are in its environment: `INSTALLER_PROJE
|
|
|
530
569
|
|
|
531
570
|
There is no installer script to copy into the repository: put the install line from the top of this page in your README, with your library's name in it.
|
|
532
571
|
|
|
572
|
+
### Examples
|
|
573
|
+
|
|
574
|
+
**The smallest one.** A library of one header and one source, for one platform, needs no more than this:
|
|
575
|
+
|
|
576
|
+
```yaml
|
|
577
|
+
name: example
|
|
578
|
+
platform: zephyr
|
|
579
|
+
requires:
|
|
580
|
+
lib_installer: 4.0.0
|
|
581
|
+
headers:
|
|
582
|
+
- src/example.h
|
|
583
|
+
sources:
|
|
584
|
+
- src/example.c
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
**A driver that needs another library**, with a part the user chooses, a file that becomes the project's, and a step run once the files are in, here for an STM32 project:
|
|
588
|
+
|
|
589
|
+
```yaml
|
|
590
|
+
name: example
|
|
591
|
+
description: Driver for the X chip
|
|
592
|
+
platform: stm32
|
|
593
|
+
requires:
|
|
594
|
+
lib_installer: 4.0.0
|
|
595
|
+
libraries:
|
|
596
|
+
- osal >= 1.0.0 # installed first, when the project has none that new
|
|
597
|
+
headers:
|
|
598
|
+
- src/example.h
|
|
599
|
+
- src/example_config.h # the user's settings, between USER CODE lines
|
|
600
|
+
sources:
|
|
601
|
+
- src/example.c
|
|
602
|
+
options:
|
|
603
|
+
littlefs: # lib-installer owner/example --with littlefs
|
|
604
|
+
description: LittleFS file system on the flash
|
|
605
|
+
libraries:
|
|
606
|
+
- littlefs >= 2.11.0
|
|
607
|
+
sources:
|
|
608
|
+
- src/example_lfs.c
|
|
609
|
+
once:
|
|
610
|
+
- from: templates/example_port.c # made once, then the project's
|
|
611
|
+
to: Core/Src/example_port.c
|
|
612
|
+
extras:
|
|
613
|
+
- root: tools # tools/make_key.py, in the project's folder
|
|
614
|
+
run:
|
|
615
|
+
- label: make-key # lib-installer owner/example --run make-key
|
|
616
|
+
description: Make the product's key, product.key
|
|
617
|
+
script: tools/make_key.py
|
|
618
|
+
unless: product.key # skipped once the key is there
|
|
619
|
+
```
|
|
620
|
+
|
|
621
|
+
**A Zephyr library that says where each line goes**, the application's files under `project`, its own folder under `library`, each list in groups under their titles, and a setting with a note:
|
|
622
|
+
|
|
623
|
+
```yaml
|
|
624
|
+
name: example
|
|
625
|
+
platform: zephyr
|
|
626
|
+
requires:
|
|
627
|
+
lib_installer: 4.0.0
|
|
628
|
+
headers:
|
|
629
|
+
- src/example.h
|
|
630
|
+
sources:
|
|
631
|
+
- src/example.c
|
|
632
|
+
zephyr:
|
|
633
|
+
symbol: # CONFIG_EXAMPLE=y, last in its block in prj.conf,
|
|
634
|
+
EXAMPLE: the driver, and its defaults while it is on # with its note
|
|
635
|
+
project:
|
|
636
|
+
conf: # prj.conf, beside the switch, the user's to change
|
|
637
|
+
What the release build leaves out:
|
|
638
|
+
- LOG=n: no messages, and nowhere to send them
|
|
639
|
+
- ASSERT=n
|
|
640
|
+
library:
|
|
641
|
+
kconfig: # defaults in its Kconfig, while CONFIG_EXAMPLE is on
|
|
642
|
+
Bluetooth, as a peripheral:
|
|
643
|
+
- BT
|
|
644
|
+
- BT_PERIPHERAL
|
|
645
|
+
conf: # its Kconfig fragment, read after prj.conf
|
|
646
|
+
Bluetooth as fast as it goes:
|
|
647
|
+
- BT_AUTO_PHY_PERIPHERAL_2M: the 2M PHY as soon as a phone connects
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
Its block in the application's `prj.conf` then reads:
|
|
651
|
+
|
|
652
|
+
```
|
|
653
|
+
# >>> lib-installer: example >>>
|
|
654
|
+
# Added by lib-installer, and written again on every install, so set
|
|
655
|
+
# example's settings below this block rather than in it.
|
|
656
|
+
|
|
657
|
+
# ******************************************************************************
|
|
658
|
+
# What the release build leaves out
|
|
659
|
+
# ******************************************************************************
|
|
660
|
+
# no messages, and nowhere to send them
|
|
661
|
+
CONFIG_LOG=n
|
|
662
|
+
CONFIG_ASSERT=n
|
|
663
|
+
|
|
664
|
+
# ******************************************************************************
|
|
665
|
+
# example
|
|
666
|
+
# ******************************************************************************
|
|
667
|
+
# the driver, and its defaults while it is on
|
|
668
|
+
CONFIG_EXAMPLE=y
|
|
669
|
+
# <<< lib-installer: example <<<
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
The [Zephyr page](https://github.com/nimaltd/lib-installer/blob/main/docs/zephyr.md#for-someone-writing-a-library) has every key of its section, and what each writes where.
|
|
673
|
+
|
|
674
|
+
**An ESP-IDF library that says where each line goes**, the project's files under `project`, its component under `library`, a list in groups under their titles, and a symbol with a note:
|
|
675
|
+
|
|
676
|
+
```yaml
|
|
677
|
+
name: example
|
|
678
|
+
platform: esp32
|
|
679
|
+
requires:
|
|
680
|
+
lib_installer: 4.0.0
|
|
681
|
+
headers:
|
|
682
|
+
- src/example.h
|
|
683
|
+
sources:
|
|
684
|
+
- src/example.c
|
|
685
|
+
esp32:
|
|
686
|
+
project:
|
|
687
|
+
conf: # its block in the project's sdkconfig.defaults
|
|
688
|
+
A faster tick:
|
|
689
|
+
- FREERTOS_HZ=1000: one tick a millisecond
|
|
690
|
+
cmake: # the project's CMakeLists.txt, by place
|
|
691
|
+
after-project:
|
|
692
|
+
- idf_component_get_property(main_lib main COMPONENT_LIB)
|
|
693
|
+
- target_compile_definitions(${main_lib} PRIVATE EXAMPLE_IN_MAIN)
|
|
694
|
+
library:
|
|
695
|
+
requires: [esp_timer] # REQUIRES of its component
|
|
696
|
+
cmake: # its component's CMakeLists.txt
|
|
697
|
+
Math:
|
|
698
|
+
- target_link_libraries(${COMPONENT_LIB} PRIVATE m)
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
Its block in the project's `sdkconfig.defaults` then reads:
|
|
702
|
+
|
|
703
|
+
```
|
|
704
|
+
# >>> lib-installer: example >>>
|
|
705
|
+
# Added by lib-installer, and written again on every install, so set
|
|
706
|
+
# example's symbols below this block rather than in it.
|
|
707
|
+
|
|
708
|
+
# ******************************************************************************
|
|
709
|
+
# A faster tick
|
|
710
|
+
# ******************************************************************************
|
|
711
|
+
# one tick a millisecond
|
|
712
|
+
CONFIG_FREERTOS_HZ=1000
|
|
713
|
+
# <<< lib-installer: example <<<
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
**A PlatformIO library with a flag for the whole build**, in `platformio.ini` under `project`, and what goes into its `library.json` under `library`:
|
|
717
|
+
|
|
718
|
+
```yaml
|
|
719
|
+
name: example
|
|
720
|
+
platform: pio
|
|
721
|
+
requires:
|
|
722
|
+
lib_installer: 4.0.0
|
|
723
|
+
install:
|
|
724
|
+
defines:
|
|
725
|
+
- EXAMPLE_FAST
|
|
726
|
+
headers:
|
|
727
|
+
- src/example.h
|
|
728
|
+
sources:
|
|
729
|
+
- src/example.c
|
|
730
|
+
pio:
|
|
731
|
+
project:
|
|
732
|
+
build_flags: # platformio.ini, after its defines, for every file
|
|
733
|
+
Printing:
|
|
734
|
+
- -Wl,-u,_printf_float: printf("%f") prints nothing without it
|
|
735
|
+
library: # its library.json, which has no comments
|
|
736
|
+
frameworks: [arduino]
|
|
737
|
+
dependencies:
|
|
738
|
+
- bblanchon/ArduinoJson@^7
|
|
739
|
+
```
|
|
740
|
+
|
|
741
|
+
Its block in `build_flags` of `platformio.ini`, a title and a note as comments of the file's:
|
|
742
|
+
|
|
743
|
+
```ini
|
|
744
|
+
[env]
|
|
745
|
+
build_flags =
|
|
746
|
+
; >>> lib-installer: example >>>
|
|
747
|
+
-DEXAMPLE_FAST
|
|
748
|
+
; ******************************************************************************
|
|
749
|
+
; Printing
|
|
750
|
+
; ******************************************************************************
|
|
751
|
+
; printf("%f") prints nothing without it
|
|
752
|
+
-Wl,-u,_printf_float
|
|
753
|
+
; <<< lib-installer: example <<<
|
|
754
|
+
```
|
|
755
|
+
|
|
756
|
+
The [ESP-IDF](https://github.com/nimaltd/lib-installer/blob/main/docs/esp32.md#for-someone-writing-a-library) and [PlatformIO](https://github.com/nimaltd/lib-installer/blob/main/docs/pio.md#for-someone-writing-a-library) pages have every key of their sections.
|
|
757
|
+
|
|
533
758
|
---
|
|
534
759
|
|
|
535
760
|
## Running the tests
|