Skip to content

[skip changelog] Document floating point ABI configuration folders for precompiled libraries #833

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 23, 2020
Merged

[skip changelog] Document floating point ABI configuration folders for precompiled libraries #833

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bb365ae
Move precompiled library file location documentation to dedicated sec…
per1234 Jul 16, 2020
e3d792d
Document floating point ABI configuration folders for precompiled lib…
per1234 Jul 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 41 additions & 4 deletions docs/library-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,10 @@ otherwise below, **all fields are required**. The available fields are:
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) 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:
(archive) and .so (shared object) files. See the ["Precompiled binaries"](#precompiled-binaries) section for
documentation of the required location in the library for these files. 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
Expand Down Expand Up @@ -154,6 +154,43 @@ only needs to run on Arduino IDE 1.5.x+, we recommend placing all source code in
recursive compilation of nested source folders, its code must be in the src/ folder (since Arduino IDE 1.0.x doesn’t
support recursive compilation, backwards compatibility wouldn’t be possible anyway).

#### Precompiled binaries

The `precompiled` field of [library.properties](#libraryproperties-file-format) enables support for the use of
precompiled libraries. This requires providing .a (archive) or .so (shared object) files which are compiled for a
particular processor architecture. The target architecture of the files is indicated by folder names.

The binaries 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 filenames of the compiled binaries should start with `lib` (e.g., `libFoo.a`).

**(available from Arduino IDE 1.8.12/arduino-builder 1.5.2/Arduino CLI 0.8.0)** The floating point ABI configuration of
ARM core microcontrollers may be adjusted via compiler flags. An extra subfolder level can be used to provide files
compiled for a specific floating point configuration: `src/{build.mcu}/{build.fpu}-{build.float-abi}`, where
`{build.fpu}` is the value of the `-mfpu` compiler flag and `{build.float-abi}` is the value of the `-mfloat-abi`
compiler flag. **(available from Arduino IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0)** If floating point
configuration flags are used but no folder matching that configuration is found, `src/{build.mcu}` is used as a
fallback.

Below is an example library `src` folder structure that provides:

- Header file containing the declarations for the library API.
- Source file to use as a fallback for other architectures (`precompiled=full` mode).
- Archive file for the ARM Cortex M0+ architecture of the Arduino SAMD boards.
- Archive file for the ARM Cortex M4 architecture of the Arduino Nano 33 BLE, as a fallback for backwards compatibility
with Arduino development software before the floating point configuration support was added.
- Archive file for the ARM Cortex M4 architecture of the Arduino Nano 33 BLE, compiled for the
`-mfloat-abi=softfp -mfpu=fpv4-sp-d16` floating point ABI configuration.

```
Servo/src/Servo.h
Servo/src/Servo.cpp
Servo/src/cortex-m0plus/libServo.a
Servo/src/cortex-m4/libServo.a
Servo/src/cortex-m4/fpv4-sp-d16-softfp/libServo.a
```

#### Library Examples

Library examples must be placed in the **examples** folder. Note that the **examples** folder must be written exactly
Expand Down