翻譯自官方文件:Arduino IDE 1.5: Library specification · arduino/Arduino Wiki。
Arduino IDE 1.5.x(以上)的第三方程式庫規格書。
- rev.1,從1.5.3開始實作。(已被rev.2取代)
- rev.2,從1.5.6開始實作此規格。
制定新程式庫格式的用意是為了搭配自動化的
程式庫管理員(
Library Manager),自1.6.2版開始啟用。有了程式庫管理員,使用者就能夠根據專案需求,透過操作簡易的圖形化介面,自動下載並安裝所需程式庫;目前尚未能處理程式庫之間相依性,關於程式庫管理員的進一步資訊,請參閱
此處說明文件。
Arduino 1.5.x支援多種微控制器架構(諸如AVR、SAM、等等),意思是說,程式庫可能需要能在多種架構上運作,新版的1.5.x程式庫格式,並未對跨架構程式庫提供特殊支援,但提供了前置處理機制,供程式庫判斷,可為不同架構提供不同的程式碼。
其他參考文件:
1.5版程式庫格式(rev.2)
程式庫後設資料(metadata)
新格式最重要的地方是透過名為
library.properties這支屬性檔案,描述程式庫本身的資訊。
有了這支檔案,將來的程式庫管理員就能夠以簡易且自動的方式,搜尋並安裝相依的程式庫。
library.properties檔案格式
library.properties檔案含有「鍵=值」的屬性列表,此檔內每一欄位都採用UTF-8文字編碼,可用欄位如下:
name:程式庫的名稱。
version:程式庫的版本,版本編號應相容於
semver,1.2.0是正確的,1.2可接受,但r5、003、1.1c則為無效的版本編號。
author:作者的姓名或暱稱,以及電子郵件地址(非必要),以逗號「,」隔開。
maintainer:維護者的姓名與電子郵件地址。
sentence:以一句話檢視這套程式庫的用途。
paragraph:用更長的句子描述說明。一定會加上sentence的句子,所以你應該從第二個句子開始撰寫。
category:若有此欄位,請從Display、Communication、Signal Input/Output、Sensors、Device Control、Timing、Data Storage、Data Processing、Other之中選一個。
url:程式庫專案的網址,供他人參訪。可以是github或其他類似頁面。
architectures:這套程式庫支援的架構清單,以逗號「,」隔開。若程式庫不含有特定於某架構的程式庫,請使用「*」代表所有架構。
範例:
name=WebServer
version=1.0
author=Cristian Maglie <c.maglie@example.com>, Pippo Pluto <pippo@example.com>
maintainer=Cristian Maglie <c.maglie@example.com>
sentence=A library that makes coding a Webserver a breeze.
paragraph=Supports HTTP1.1 and you can do GET and POST.
category=Communication
url=http://example.com/
architectures=avr
資料夾與檔案的位置規劃
Arduino程式庫由數個資料夾組合而成,每個資料夾皆有其特定用途(原始碼、範例、文件、等等),將來改版時可能會加入底下未提及的新資料夾。
原始碼
只相容於1.5.x版的程式庫,把原始碼檔案放在資料夾
src裡,例如:
Servo/src/Servo.h
Servo/src/Servo.cpp
資料夾
src與它的
所有子資料夾裡的原始碼,都會被編譯並跟使用者的草稿碼連結在一起,只有資料夾src被加入搜尋路徑清單裡(編譯草稿碼與程式庫之時)。當使用者匯入程式庫到他的草稿碼(透過選單「工具」-「匯入程式庫」),src資料夾裡的所有.h標頭檔(但不包括子資料夾),都會加上#include前置處理指令放進草稿碼,因此,這些標頭檔可算是你的程式庫的對外介面,一般來說,放在src資料夾內的標頭檔,會是你想要對外公開的東西,並且計畫在程式庫未來版本維持相容性。程式庫內部自己使用得標頭檔,應放在src的子資料夾裡。
若想向後相容於Arduino 1.0.x,程式庫作者可選擇不要把原始碼放進
src資料夾內,此時應採用1.0版程式庫格式的資料夾規劃,放在
根資料夾以及
utility子資料夾裡,例如:
Servo/Servo.h
Servo/Servo.cpp
Servo/utility/ServoTimers.h
Servo/utility/ServoTimers.cpp
This will allow existing 1.0.x libraries to compile under 1.5.x as well and vice-versa. If a library only needs to run on 1.5.x, we recommend placing all source code in the src/ folder. If a library requires recursive compilation of nested source folders, its code must be in the src/ folder (since 1.0.x doesn’t support recursive compilation, backwards compatibility wouldn’t be possible anyway).
這麼一來,1.0.x程式庫便可在1.5.x之下進行編譯,反之亦然。若程式庫只需相容於1.5.x,我們建議把所有原始碼放進src資料夾,若程式庫需要巢狀原始碼資料夾的遞迴式編譯,那麼原始碼必須放在src資料夾內(因為1.0.x不支援遞迴式編譯,所以無法維持向後相容性)。
程式庫範例
程式庫的範例程式,應放在
examples資料夾裡,此資料夾的名稱必須一字不差,全部都是小寫字母。
Servo/examples/...
範例資料夾內的草稿碼,會顯示在IDE選單「範例」裡。
額外文件
開發人員可在
extra資料夾內,放入說明文件或其他想跟程式庫綁在一起的東西。請記得,此資料夾裡的東西將會增加程式庫的大小,因此若放進僅含數KB內容的20MB PDF檔,大概不會是個好主意。
IDE完全忽視
extra資料夾的內容,你可以放入任何東西,諸如其他說明文件等等。
關鍵字
在名為keywords.txt的檔案裡,放入應特別顯示的關鍵字清單,此檔案的格式與1.0版相同。
Servo/keywords.txt
完整示範
根據上述規格,底下是名為Servo的假想程式庫:
Servo/
Servo/library.properties
Servo/keywords.txt
Servo/src/
Servo/src/Servo.h
Servo/src/Servo.cpp
Servo/src/ServoTimers.h
Servo/examples/
Servo/examples/Sweep/Sweep.ino
Servo/examples/Pot/Pot.ino
Servo/extras/
Servo/extras/Servo_Connectors.pdf
多重架構
In 1.5.x, libraries placed in the user’s sketchbook folder (in the libraries/ subfolder) will be made available for all boards, which may include multiple different processor architectures. To provide architecture-specific code or optimizations, library authors can use the ARDUINO_ARCH_XXX preprocessor macro (#define), where XXX is the name of the architecture (as determined by the name of the folder containing it), e.g. ARDUINO_ARCH_AVR will be defined when compiling for AVR-based boards. For example,
在1.5.x版裡,放在草稿碼簿資料夾裡的程式庫(位於libraries子資料夾內),可供所有板子使用,可能包含不同處理器架構的特定程式碼;若想撰寫特定架構的程式碼或最佳化,程式庫作者可以使用前置處理器的巨集ARDUINO_ARCH_XXX(#define)來判斷,其中XXX是架構的名稱(根據包含該架構的資料夾之名稱),譬如在為AVR板子進行編譯時,將會定義ARDUINO_ARCH_AVR,寫法如下:
#if defined(ARDUINO_ARCH_AVR)
// AVR特定程式碼
#elif defined(ARDUINO_ARCH_SAM)
// SAM特定程式碼
#else
// 泛用、非特定平台的程式碼
#endif
Alternatively, if a library only works on certain architectures, you can provide an explicit error message (instead of allowing the compilation to fail in an difficult to understand way):
或者,若你的程式庫只能用於某些特定架構,可提供明確的錯誤訊息(而不是直接讓編譯失敗,難以了解到底哪裡出錯):
#if defined(ARDUINO_ARCH_AVR)
// AVR特定程式碼
#elif defined(ARDUINO_ARCH_SAM)
// SAM特定程式碼
#else
#error "This library only supports boards with an AVR or SAM processor."
#endif
舊程式庫格式(1.5版之前)
為了支援舊版格式的程式庫(自Arduino 1.0.x版以來),Arduino 1.5.x也能編譯缺少後設資料檔library.properties的程式庫,使用時,這些舊程式庫應如同在Arduino 1.0.x的樣子;可用於所有板子,包括非AVR架構的板子(不會出現於1.0.x版)。