From 2b3231d679de861bb596ae0651aa84ed8c076573 Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 13 Jul 2020 16:23:51 -0700 Subject: [PATCH] Document library.properties precompiled field's "full" option Previously, the precompiled field of library.properties only supported one value: "true". As it became apparent that there were two distinct use cases for this feature, it was necessary to add a new option so that both use cases could be fully supported. --- docs/library-specification.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/library-specification.md b/docs/library-specification.md index 3ab86d5d290..c2b0dd361b2 100644 --- a/docs/library-specification.md +++ b/docs/library-specification.md @@ -82,10 +82,20 @@ otherwise below, **all fields are required**. The available fields are: - **includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the sketch as `#include <...>` lines. This property is used with the "Include library" command in the Arduino IDE. If the `includes` property is missing, all the header files (.h) on the root source folder are included. -- **precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) set to `true` to allow the - use of .a (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where - `{build.mcu}` is the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. - The static library should be linked as an ldflag. +- **precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) enables support for .a + (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where `{build.mcu}` is + the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. The static library + should be linked as an ldflag. The **precompiled** field has two supported values, which control how any source files + in the library are handled: + - true - Source files are always compiled. This is useful for "mixed" libraries, such as those that contain both open + source code and the precompiled binary of a closed source component. Support for "mixed" libraries was inadvertently + lost in Arduino IDE 1.8.12/arduino-builder 1.5.2/Arduino CLI 0.8.0, and returned in Arduino IDE + 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0. + - full - **(available from Arduino IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0)** If the library provides a + precompiled library for the board being compiled for, the source files will not be compiled. If no precompiled + library was provided for the selected board, source files are compiled as a fallback. This is useful for + precompiling the library to reduce compilation time for specific target hardware, but also providing support for + arbitrary boards by compiling the library on demand. - **ldflags** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) the linker flags to be added. Ex: `ldflags=-lm`