Arduino IDE 1.5：程式庫規格書

翻譯自官方文件：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程式庫格式，並未對跨架構程式庫提供特殊支援，但提供了前置處理機制，供程式庫判斷，可為不同架構提供不同的程式碼。

其他參考文件：

• Arduino程式庫撰寫風格指引：http://arduino.cc/en/Reference/APIStyleGuide。
• 範例程式撰寫風格：http://arduino.cc/en/Reference/StyleGuide。

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版）。