From 78a63bda03ce3a45a9607e39dcf1479544468133 Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 20 Sep 2021 03:34:38 -0700 Subject: [PATCH] [skip changelog] Fully document library layouts in specification Arduino library authors may chose from multiple structures, each of which have different implications for the compilation of the library source files. The specification explains this in a somewhat simplistic manner as "1.5 format" and "1.0 format". That is sufficient for most, but does not provide a complete picture. Feedback indicated that more advanced users were left wanting complete documentation, which is provided here. The subject is not well suited for description via prose, so a chart and table are employed instead. The chart is defined in the DOT graph description language. --- docs/img/library-layout.dot | 39 ++++++++++++ docs/img/library-layout.svg | 117 ++++++++++++++++++++++++++++++++++ docs/library-specification.md | 9 +++ 3 files changed, 165 insertions(+) create mode 100644 docs/img/library-layout.dot create mode 100644 docs/img/library-layout.svg diff --git a/docs/img/library-layout.dot b/docs/img/library-layout.dot new file mode 100644 index 00000000000..9afa87b93c5 --- /dev/null +++ b/docs/img/library-layout.dot @@ -0,0 +1,39 @@ +// See: https://www.graphviz.org/documentation/ +digraph { + // This generates library-layout.png using the following command: + // dot -Tsvg -olibrary-layout.svg library-layout.dot + graph [ + splines=line + ] + node [ + shape=box + ] + + subgraph { + // This subgraph provides the labels on left margin + node [ + margin="0.0,0.0" + shape=none + width=0.0 + ] + "Metadata:" -> "Format:" -> "Structure:" -> "Layout:" [style=invis] + } + + subgraph cluster1 { + peripheries=0 + "library.properties" [height=1.0 margin="0.0,0.0" shape=diamond width=0.0] + "library.properties" -> "1.5" [label="yes"] + "library.properties" -> "1.0" [label="no"] + subgraph cluster2 { + peripheries=0 + rank=same + "1.5" + "1.0" + } + "1.5" -> "src/" + "src/" [shape=diamond] + "src/" -> "recursive" [label=" yes"] + "src/" -> "flat" [label="no"] + "1.0" -> "flat" + } +} diff --git a/docs/img/library-layout.svg b/docs/img/library-layout.svg new file mode 100644 index 00000000000..dc1f7bf72a7 --- /dev/null +++ b/docs/img/library-layout.svg @@ -0,0 +1,117 @@ + + + + + + + + +cluster1 + + +cluster2 + + + +Metadata: +Metadata: + + + +Format: +Format: + + + + +Structure: +Structure: + + + + +Layout: +Layout: + + + + +library.properties + +library.properties + + + +1.5 + +1.5 + + + +library.properties->1.5 + + +yes + + + +1.0 + +1.0 + + + +library.properties->1.0 + + +no + + + +src/ + +src/ + + + +1.5->src/ + + + + + +flat + +flat + + + +1.0->flat + + + + + +recursive + +recursive + + + +src/->recursive + + + yes + + + +src/->flat + + +no + + + diff --git a/docs/library-specification.md b/docs/library-specification.md index f8492e6e42c..232f67829aa 100644 --- a/docs/library-specification.md +++ b/docs/library-specification.md @@ -163,6 +163,15 @@ 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). +##### Library layout + +![Library layout](img/library-layout.svg) + +| Layout | root compiled | `src` compiled | `utility` compiled | +| ------------- | ------------- | -------------- | ------------------ | +| **recursive** | no | recursively | no | +| **flat** | yes | no | yes | + #### Precompiled binaries The `precompiled` field of [library.properties](#libraryproperties-file-format) enables support for the use of