lib-installer help

Installing lib-installer

lib-installer is a Python program, on PyPI, and needs nothing but Python 3.8 or newer. Install it with pip, and see which version you have:

$ pip install lib-installer

$ lib-installer --version
lib-installer 4.0.1

pip install --upgrade lib-installer updates it, and pip uninstall lib-installer takes it away. On Linux or macOS, if pip refuses with externally-managed-environment, use pipx install lib-installer, and pipx upgrade lib-installer to update.

When a newer lib-installer is out, the last line of a run says so, with the command that updates it. It asks PyPI at most once a day; --no-update-check turns that off.

Installing a library

Open a terminal in your project's folder, and name the library: by its owner and name on GitHub, its address, a downloaded .zip, or a folder.

$ lib-installer nimaltd/spif

lib-installer reads the platform from the library's installer.yml, fetches the library and those it needs before anything is written, copies it into your project, and adds it to the build. It asks what is yours to choose: the folder it goes into, the library's options, such as littlefs for spif, and the steps it runs once it is in. Enter takes the answer offered, and --yes takes them all, for a script.

This is the Arduino example library going into a sketch, Blink, with its uptime option, run from the sketch's folder:

$ lib-installer nimaltd/lib-installer-example-arduino --into sketch --with uptime --yes
Fetching nimaltd/lib-installer-example-arduino ...

Options
  uptime     yes, as asked with --with uptime

example 1.4.0
A period that never blocks, made to try lib-installer on
utility / timing

Folder to install example into [src/example]: (--yes)

Files
  written src/example/src/example.h
  written src/example/src/example_config.h
  written src/example/src/example.cpp
  written src/example/src/example_uptime.h
  written src/example/src/example_uptime.cpp
  written src/example/LICENSE.md
  written src/example/NOTICE
  written src/example/README.md
  written src/example/tools/make_id.py

Project
  ok      Sketch  Arduino builds every file in the sketch's src folder, so there is nothing to register.

Run
  make-id      Make this board's own ID, example_id.h
               python src/example/tools/make_id.py example_id.h
Made example_id.h: device F8B9A0DB.
               done

Done. #include "src/example/src/example.h" and you are away.

• Options: the parts of the library you chose, here with --with uptime. Without it, you are asked.
• Files: each file written, in the folder you chose.
• Project: what was changed for the build. Arduino builds every file in a sketch's src folder, so here nothing needed to be.
• Run: the steps the library runs once it is in, each asked first. This one made the board's own ID.

What was chosen is kept in .lib-installer.json in your project, so the next run does not ask again. Keep it with your project, in version control.

Updating a library

Run the same command again. Every file of the library is replaced, and what you wrote between its USER CODE BEGIN and USER CODE END lines is kept, the way STM32CubeMX keeps your code when it generates again:

$ lib-installer nimaltd/lib-installer-example-arduino --into sketch --yes
Fetching nimaltd/lib-installer-example-arduino ...

Options
  uptime     yes, as before. Change it with --without uptime

example 1.4.0
A period that never blocks, made to try lib-installer on
utility / timing

Folder to install example into [src/example]: (--yes)

Files
  ...
  kept    src/example/src/example_config.h  your USER CODE EXAMPLE_CONFIGURATION

Project
  ok      Sketch  Arduino builds every file in the sketch's src folder, so there is nothing to register.

Run
  make-id      skipped, example_id.h is already there

Done. #include "src/example/src/example.h" and you are away.
This was an update. The library replaced, what was yours kept.

The option chosen before is taken again, and the step that made the ID is not run twice. A file of the library you changed outside its USER CODE lines is saved as a .bak beside it before it is replaced: take what you need from it, then delete it.

Your platform

A library that names no platform, or several, takes --platform: stm32, zephyr, esp32, arduino or pio.

Taking a library out

Name it after --uninstall. Its files come out, and its place in the build; what you wrote in it is saved beside it first, and its folder stays for that:

$ lib-installer --uninstall example

example 1.4.0
out of src/example

Files
  removed src/example/LICENSE.md
  removed src/example/NOTICE
  removed src/example/README.md
  removed src/example/src/example.cpp
  removed src/example/src/example.h
  removed src/example/src/example_config.h
  removed src/example/src/example_uptime.cpp
  removed src/example/src/example_uptime.h
  removed src/example/tools/make_id.py
  saved   src/example/src/example_config.h.20261031-103739.bak  it has something between its USER CODE lines, such as your settings

Done. example is out of the project.
src/example stays, for what was saved above. Delete it once you have taken what you need.

Several can go at once: lib-installer --uninstall osal example.

A private repository

With a GitHub token that can read it, given with --key:

$ lib-installer you/private-lib --key github_pat_...

or once in GITHUB_TOKEN, which keeps it out of your shell's history. The token is sent to GitHub and nowhere else. How to make one, with only the Contents: Read-only permission it needs, is in the README.

Without internet

On a computer with internet, save the installer as a file, and download the library from its GitHub page: Code, then Download ZIP.

$ pip download lib-installer

That saves one file, such as lib_installer-4.0.1-py3-none-any.whl. Copy both to the computer without internet, then from your project:

$ pip install lib_installer-4.0.1-py3-none-any.whl
$ lib-installer D:/Downloads/example-main.zip

Neither needs the internet: the installer needs nothing but itself, and reads the library from the zip without unpacking it.

Every command

When something goes wrong

• "names no platform": the library's installer.yml names none, or several, and nobody is there to pick one. Give --platform.
• "This library needs lib-installer … or newer": nothing was changed. Update it with pip install --upgrade lib-installer, and run the command again.
• A slow or broken connection. A file that does not come is tried again, and every file is fetched before anything is installed, so a run that fails part way leaves your project as it was: run it again. Behind a proxy, set HTTPS_PROXY on Linux and macOS; Windows uses the system's. For pip itself: pip install --retries 10 --timeout 60 lib-installer, or install from zips, as above.
• Anything else: ask, or report a bug on GitHub.

Everything else, and how to make your own library installable, is in lib-installer's README.