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.
Files changed (53) hide show
  1. {lib_installer-3.0.1 → lib_installer-4.0.0}/PKG-INFO +232 -7
  2. {lib_installer-3.0.1 → lib_installer-4.0.0}/README.md +231 -6
  3. {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/PKG-INFO +232 -7
  4. {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/SOURCES.txt +1 -0
  5. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/__init__.py +1 -1
  6. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/arduino.py +9 -1
  7. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/manifest.py +66 -2
  8. lib_installer-4.0.0/src/core/titles.py +260 -0
  9. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/yamlreader.py +64 -3
  10. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/esp32.py +181 -39
  11. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/project.py +34 -11
  12. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/ini.py +89 -28
  13. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/pio.py +164 -25
  14. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/stm32.py +4 -1
  15. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/zephyr/app.py +125 -24
  16. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/zephyr/module.py +116 -27
  17. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/zephyr/zephyr.py +379 -49
  18. {lib_installer-3.0.1 → lib_installer-4.0.0}/LICENSE +0 -0
  19. {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/dependency_links.txt +0 -0
  20. {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/entry_points.txt +0 -0
  21. {lib_installer-3.0.1 → lib_installer-4.0.0}/lib_installer.egg-info/top_level.txt +0 -0
  22. {lib_installer-3.0.1 → lib_installer-4.0.0}/pyproject.toml +0 -0
  23. {lib_installer-3.0.1 → lib_installer-4.0.0}/setup.cfg +0 -0
  24. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/__main__.py +0 -0
  25. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/__init__.py +0 -0
  26. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/properties.py +0 -0
  27. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/arduino/sketchbook.py +0 -0
  28. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/cli.py +0 -0
  29. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/__init__.py +0 -0
  30. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/blocks.py +0 -0
  31. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/cli.py +0 -0
  32. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/console.py +0 -0
  33. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/download.py +0 -0
  34. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/files.py +0 -0
  35. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/installer.py +0 -0
  36. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/steps.py +0 -0
  37. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/target.py +0 -0
  38. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/updates.py +0 -0
  39. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/core/usercode.py +0 -0
  40. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/__init__.py +0 -0
  41. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/esp32/component.py +0 -0
  42. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/__init__.py +0 -0
  43. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/pio/library_json.py +0 -0
  44. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/__init__.py +0 -0
  45. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/checks.py +0 -0
  46. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/__init__.py +0 -0
  47. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/base.py +0 -0
  48. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/cmake.py +0 -0
  49. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/cubeide.py +0 -0
  50. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/iar.py +0 -0
  51. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/keil.py +0 -0
  52. {lib_installer-3.0.1 → lib_installer-4.0.0}/src/stm32/ide/makefile.py +0 -0
  53. {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.0.1
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 3.1.0 or newer, and this one is 3.0.1. Nothing was changed.
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-3.0.1-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:
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-3.0.1-py3-none-any.whl
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 3.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).
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: 3.0.0 # the oldest lib-installer that reads this file
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 3.1.0 or newer, and this one is 3.0.1. Nothing was changed.
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-3.0.1-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:
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-3.0.1-py3-none-any.whl
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 3.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).
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: 3.0.0 # the oldest lib-installer that reads this file
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