これは、Arduino IDE 1.5.x以降で利用するArduinoライブラリフォーマットの仕様です。

• rev.1は、Arduino IDEバージョン1.5.3で実装を開始しました。今は、rev.2に置き換えられました。
• rev.2は、Arduino IDEバージョン1.5.6から実装を開始しました。
• rev.2.1は、Arduino IDEバージョン1.6.10から実装を開始しました。
• rev.2.2は、Arduino IDEバージョン1.8.10から実装を開始しました。

この新しいライブラリフォーマットは、Arduino IDE 1.6.2から利用できるライブラリマネージャ―とともに利用することを意図しています。ライブラリマネージャ―を使えば、プロジェクトに必要なライブラリを自動的にダウンロード・インストールできます。ライブラリマネージャ―は、arduino-cli libだけではなく、Arduino IDE/Arduino IDE 2.0やArduino Cloud Editorの簡単に利用できるGUIでも利用できます。

ライブラリマネージャ―の動作の詳細は、ここにあります。

Arduinoの開発ソフトウェアは、複数のマイクロコントローラーアーキテクチャ(例えば、AVRやSAMなど)をサポートします。つまり、ライブラリも複数のアーキテクチャで動作する必要があることになります。新しいライブラリフォーマット1.5はクロスアーキテクチャライブラリ用の特別なサポートは含んでいません。しかし、コードのセクションを特定のアーキテクチャ向けにするプリプロセッサベースの機能を提供しています。

参照

• ライブラリ作成用Arduinoスタイルガイド
• スケッチのビルドプロセス

1.5ライブラリフォーマット(rev.2.2)

ライブラリメタデータ

フォーマットへの、もっとも重要な追加は、library.propertiesと呼ばれるプロパティファイルを用いたライブラリ自身の情報を追加できることです。

このファイルを通じて、ライブラリマネージャ―はライブラリを検索でき、ライブラリとその依存関係を簡単かつ自動でインストールできます。このファイルは、ライブラリフォルダのルートに配置する必要があります。

library.propertiesファイルフォーマット

library.properties file formatファイルは、key=valueプロパティのリストです。このファイルの全てのフィールドはUTF-8エンコードされています。記載がない限り、すべてのフィールドが必須です。利用可能なフィールドは以下の通りです。

• name: ライブラリ名。ライブラリ名は、基本文字(A-Z、a-z)や数字(0-9)、空白文字( )、アンダースコア(_)、ドット(.)、ダッシュ(-)だけで構成します。文字か数字で始まる必要があります。最低1文字必要です。nameの値が、Arduinoで始まるライブラリは、公式のArduinoライブラリとして予約されたので、ライブラリマネージャ―インデックスに追加できません。
• version: ライブラリのバージョン。バージョンは、semverに従う必要があります。1.2.0は正しく、1.2は受け入れられますが、r5、003、1.1cは無効です。
• author: 作成者の名前・ニックネームと、電子メールアドレス(オプション)。コンマ(,)で区切ります。
• maintainer: 保守者の名前と電子メールアドレス。
• sentence: ライブラリの目的を説明する文。
• paragraph: ライブラリの長い説明。sentenceの値がこれに付加されるので、ここでは、2文目から開始します。
• category: (デフォルトは、Uncategorized)許可されている値
  • Display
  • Communication
  • Signal Input/Output
  • Sensors
  • Device Control
  • Timing
  • Data Storage
  • Data Processing
  • Other
• url: 人が参照するための、ライブラリプロジェクトのURL。例えば、ライブラリのGitHubページ。これは、ライブラリマネージャ―の「詳細情報(More info)」リンクに使われます。
• arctectures: (デフォルトは、*)ライブラリがサポートするアーキテクチャをコンマ区切りで並べたリスト。ライブラリがアーキテクチャ依存のコードを含まない場合は、*を使い、すべてのアーキテクチャに適合させます。このフィールドは、複数のライブラリが#include指令に該当する場合の優先度を決定する一要素として利用され、リストにないアーキテクチャのボードでライブラリがコンパイルされたときに、警告メッセージを表示します。
• depends: (Arduino IDE 1.8.10/Arduino CLI 0.7.0から利用可能)(オプション)依存関係(現在のライブラリをビルドするのに必要なライブラリ)のコンマ区切りのリスト。Arduino IDEのライブラリマネージャ―はライブラリのインストール時に、依存関係のあるライブラリのインストールを提案します。arduino-cli lib installは、依存関係を自動でインストールします。ライブラリのnameには空白文字が許可されていますが、コンマは許可されていないので、名前に空白文字を含むライブラリを参照する際に不確実さはありません。例えば、depends=Very long library name, Another library with long-name。依存関係に対するバージョンの制約は、名前の後のカッコ内に示します。depends=ArduinoHttpClient (>=1.0.0)
• dot_a_linkage: (Arduino IDE 1.6.0/arduino-builder 1.0.0-beta13から利用可能)(オプション)trueに設定すると、ライブラリは、.a(アーカイブ)ファイルにコンパイルされます。まず、通常通り、すべてのソースファイルは.oファイルにコンパイルされます。そして、リンカ―コマンドに直接全ての.oファイルを渡すのではなく、すべての.oファイルは.aファイルに保存されます。そして、リンカ―コマンドに渡されます。1.5フォーマットライブラリの構造が必要です。
• includes: (Arduino IDE 1.6.0から利用可能)(オプション)スケッチの#includeに追加するライブラリのファイルの、コンマ区切りのリスト。このプロパティは、Arduino IDEの「ライブラリをインクルード」コマンド使われます。includesプロパティがなければ、ルートソースフォルダのすべてのヘッダファイル(.h)がインクルードされます。
• precompiled: (Arduino IDE 1.8.6/arduino-builder 1.4.0)から利用可能)(オプション).a(アーカイブ)と.so(共有オブジェクト)ファイルのサポートを許可します。これらのファイルがライブラリのどの位置に必要となるかは、コンパイル済みバイナリを参照してください。スタティックライブラリは、ldflagでリンクされます。precompiledフィールドは、2つの値をサポートします。これは、ライブラリの全てのソースファイルがどのように取り扱われるかを制御します。
  • true: ソースファイルは常にコンパイルされます。これは、例えば、オープンソースコードと非公開のソースのコンパイル済みバイナリのような、「混合」ライブラリに有用です。「混合」ライブラリのサポートは、Arduino IDE 1.8.12/arduino-builder 1.5.2/Arduino CLI 0.8.0で、誤って削除され、Arduino IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0で復活しました。
  • full: (Arduino IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0で利用可能)コンパイル対象のボード向けにコンパイル済みバイナリが提供されている場合、ソースファイルはコンパイルされません。選択したボード向けにコンパイル済みバイナリが提供されない場合、代替手段としてソースファイルはコンパイルされます。これは、特定のターゲットハードウェア向けにコンパイル時間を短縮し、かつ、任意のボード向けには実行時のコンパイルを提供するのに有効です。
• ldflags: (Arduino IDE 1.8.6/arduino-builder 1.4.0から利用可能)(オプション)追加のリンカーフラグ。例: ldflags=-lm

例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

name=WebServer
version=1.0.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
includes=WebServer.h
depends=ArduinoHttpClient

バージョンの制約

(Arduino IDE 2.0.0-beta.3/Arduino CLI 0.7.0から利用可能)

デフォルトでは、library.propertiesのdependsフィールドで指定された依存関係の最新バージョンが、対象のライブラリと同時にインストールされます。

以下の演算子が利用可能です。

例

「ArduinoHttpClient」ライブラリに以下のリリースがあるとき、

• 0.1.0
• 1.0.0
• 2.0.0
• 2.1.0

依存関係でインストールされるバージョンは以下の通りです。

フォルダとファイルの配置

各フォルダには特定の目的(ソース、例、ドキュメントなど)があります。フォルダは、この仕様では取り扱われません。将来のリビジョンで必要に応じて追加されるかもしれません。

ライブラリルートフォルダ

ライブラリルートフォルダ名は、文字(A-Z, a-z)か数字(0-9)で始まる必要があり、その後に、基本文字や数字、アンダースコア(_)、ドット(.)、ダッシュ(-)が続きます。最大長は63文字です。

ソースコード

Arduino 1.5.x以降で利用されるライブラリ向け。ソースコードは、srcフォルダに配置します。例えば、

1
2

Servo/src/Servo.h
Servo/src/Servo.cpp

ソースコードはscrフォルダにあり、すべてのサブフォルダがコンパイルされ、ユーザーのスケッチとリンクされます。srcフォルダだけがインクルードサーチパスに追加されます(スケッチとライブラリの双方がコンパイルされるとき)。ユーザーがライブラリをスケッチにインポートするとき(Arduino IDEの「スケッチ > ライブラリをインクルードメニューかArduino Web Editorの「include」ボタン)、デフォルトの動作(library.propertiesで変更可能です)は、srcディレクトリ(サブディレクトリは含みません)のすべてのヘッダ(.h)ファイルが、#include指令に追加されます。結果として、これらのヘッダファイルは、ライブラリに対するデファクトインターフェイスのようなものを形作ります。一般に、ルートsrcフォルダにあるヘッダファイルだけをユーザーのスケッチに提供し、ライブラリの将来のバージョンでも互換性を持つように維持してください。内部ヘッダは、srcフォルダのサブフォルダに配置してください。

Arduino IDE 1.0.xとの後方互換性のために、ライブラリ作者は、ソースコードをsrcフォルダではなく、ルートフォルダに配置することも選択できます。この場合、1.0ライブラリフォーマットが適用され、ソースコードは、ライブラリのルートフォルダとutilityフルだから検索されます。例えば、

1
2
3
4

Servo/Servo.h
Servo/Servo.cpp
Servo/utility/ServoTimers.h
Servo/utility/ServoTimers.cpp

これにより、既存の1.0フォーマットのライブラリがArduino IDE 1.5.x以上でもコンパイルできます。その逆も同様です。ライブラリをArduino IDE 1.5.x以上でだけ動作させる場合は、すべてのソースコードをsrcフォルダに配置することを推奨します。ライブラリが、ネストしたソースフォルダの再帰的なコンパイルを必要とするとき、コードはsrcフォルダに配置する必要があります(Arduino IDE 1.0.xは、再帰コンパイルをサポートしていません。後方互換性はありません)。

ライブラリレイアウト

コンパイル済みバイナリ

library.propertiesのprecompiledフィールドにより、コンパイル済みライブラリが利用可能です。このためには、特定のプロセッサアーキテクチャ向けにコンパイルされた、.a(アーカイブ)か.so(共有オブジェクト)ファイルを提供することが必要です。ファイルのターゲットアーキテクチャは、フォルダ名により示されます。

バイナリは、src/{build.mcu}に配置します。ここで{build.mcu}は、ファイルをコンパイルしたターゲットのアーキテクチャ名です。例えば、cortex-m3は、Arduino Due向けです。

コンパイルしたバイナリのファイル名は、libで始まる必要があります(例えば、libFoo.a)。

(Arduino IDE 1.8.12/arduino-builder 1.5.2/Arduino CLI 0.8.0から利用可能)ARMコアマイクロコントローラーの浮動小数点数ABI設定は、コンパイラフラグで調整します。特別なサブフォルダレベルが特定の浮動小数点数設定でコンパイルされたファイルを提供するのに使われます。src/{build.mcu}/{build.fpu}-{build.float-abi}で、{build.fpu}は、-mfpuコンパイラフラグの値で、{build.float-abi}が、-mfloat-abiの値です。

(IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0から利用可能)浮動小数点数設定フラグが使われたのに、その設定に合うフォルダがない場合は、src/{build.mcu}が代わりに利用されます。

以下を提供するライブラリのsrcフォルダ構造の例です。

• ライブラリAPIの宣言を含むヘッダファイル
• 他のアーキテクチャ向けに代替利用されるソースファイル(precompiled=fullモード)
• Arduino SAMDボードのARM Cortex M0+アーキテクチャ用アーカイブファイル
• 代替手段として浮動小数点数設定がサポートされる前にArduino開発ソフトウェアと互換性のあるArduino Nano 33 BLEのARM Cortex M4アーキテクチャ用アーカイブファイル
• -mfloat-abi=softfp -mfpu=fpv4-sp-d16浮動小数点数ABI設定ようにコンパイルされた、Arduino Nano 33 BLEのARM Cortex M4アーキテクチャ用アーカイブファイル

1
2
3
4
5

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

ライブラリ例

ライブラリ例は、examplesフォルダに配置する必要があります。examplesフォルダの名前は、その通りでなければなりません(小文字で)。

1

Servo/examples/...

examplesフォルダに配置したスケッチは、Arduino IDEとArduino Webエディタにより、「スケッチ例」メニューに表示されます。

詳細は以下を参照してください。

• スケッチの仕様
• コンテンツ記述用Arduinoスタイルガイド

その他のドキュメント

extrasフォルダは、ドキュメントやライブラリに付属するその他のものを配置するのに、開発者により利用されます。このフォルダに配置したファイルは、ライブラリのサイズを増やします。このため、数キロバイトのライブラリに、20MBのPDFファイルを入れることはいいアイデアではありません。

extrasフォルダのコンテンツを、Arduino開発ソフトウェアとArduino Webエディタは完全に無視します。何を置いても問題ありません。

キーワード

ライブラリ用のキーワードのリストは、ライブラリのルートフォルダにあるkeywords.txtという名前のファイルに記載します。すべてのインストールされているライブラリのキーワードが、スケッチで使われると、Arduino IDEは色付けします。

1

Servo/keywords.txt

keywords.txtファイルの例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Syntax Coloring Map For ExampleLibrary

# Datatypes (KEYWORD1)
Test    KEYWORD1

# Methods and Functions (KEYWORD2)
doSomething KEYWORD2

# Instances (KEYWORD2)

# Constants (LITERAL1)

このファイルにより、Arduino IDEは、Testをデータ型、doSomethingをメソッド・関数として、色付けします。

keywords.txtのフォーマット

keywords.txtは、4つのフィールドで構成され、それぞれは、一つの本当のタブ(空白ではなく)で区切ります。

1

KEYWORD KEYWORD_TOKENTYPE   REFERENCE_LINK  RSYNTAXTEXTAREA_TOKENTYPE

フィールドを空欄にしても問題ありません。

REFERENCE_LINK

このフィールドは、カーソルがそのキーワード上にあるとき、Arduino IDEの「右クリック > リファレンスで検索」や「ヘルプ > リファレンスで検索」で開く言語リファレンスを指定します。(訳者註: 私は、右クリックメニューは見つけられませんでした)。一般に、サードパーティのライブラリでは、言語リファレンスに掲載されていないので、REFERENCE_LINKを定義する意味はありません。

RSYNTAXTEXTAREA_TOKENTYPE

Arduino IDE 1.6.5以降で、このフィールドは、KEYWORD_TOKENTYPEを上書きします。それよりも古いバージョンのIDEは、RSYNTAXTEXTAREA_TOKENTYPEフィールドは無視され、KEYWORD_TOKENTYPEが利用されます。

開発フラグファイル

通常、Arduino IDEは、ライブラリフォルダのコンテンツを読み取り専用として取り扱います。これは、スケッチ例を誤ってユーザーが変更しないようにするためです。ライブラリを開発している間は、Arduino IDEを使い、その場でスケッチ例を編集したい場合があります。Arduino IDE 1.6.6以降では、ライブラリフォルダのルートに、.developmentというファイルを置くことで、読み取り専用を解除することができます。library.propertiesファイルが存在する必要があります。Library Manager indexerは、.developmentファイルを含むリリースを対象としません。リモートリポジトリにこのファイルをプッシュしないよう気をつけてください。

完全な例

仕様に従う「Servo」という仮想ライブラリは以下の通りです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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

複数のアーキテクチャを取り扱う

スケッチブックフォルダ(ユーザーディレクトリ)のlibrariesサブフォルダにあるライブラリは、すべてのボードで利用可能です。ボードは複数のプロセッサアーキテクチャを含む場合があります。特定のアーキテクチャ用のコードや最適化したコードを提供する場合、ライブラリ製作者は、ARDUINO_ARCH_XXXプリプロセッサマクロ(#define)を使うことができます。XXXは、アーキテクチャ名です。これは、ボードのプラットフォームのアーキテクチャフォルダの名前です。例えば、ARDUNO_ARCH_AVRは、AVRベースのボード用にコンパイルするときに定義されます。

例:

1
2
3
4
5
6
7

#if defined(ARDUINO_ARCH_AVR)
  // AVR-specific code
#elif defined(ARDUINO_ARCH_SAM)
  // SAM-specific code
#else
  // generic, non-platform specific code
#endif

一方、ライブラリが特定のアーキテクチャ向けの場合、理解困難な方法でコンパイルが失敗するのではなく、明示的なエラーメッセージを表示することもできます。

1
2
3
4
5
6
7

#if defined(ARDUINO_ARCH_AVR)
  // AVR-specific code
#elif defined(ARDUINO_ARCH_SAM)
  // SAM-specific code
#else
  #error “This library only supports boards with an AVR or SAM processor.”
#endif

古いライブラリフォーマット(pre-1.5)

古いライブラリ(Arduino IDE 1.0.x以降)をサポートするために、Arduino IDEとArduino CLIは、libraries.propertiesメタデータファイルがないライブラリもコンパイルします。ヘッダファイルは必要です。結果として、これらのライブラリは、Arduino IDE 1.0.xでコンパイルしていたのと同じように振舞います。Ardino IDE 1.0.xのときには存在していなかった、AVR以外のボードを含む、すべてのボードで利用できます。

オリジナルのページ

https://docs.arduino.cc/arduino-cli/library-specification/

最終更新日

August 16, 2026