Arduino公式文書の翻訳

2024年1月16日
 
2024年2月9日

この文書のオリジナルはarduino-cliにあるLibrary specificationです。

下訳にChatGPT 4.0を使った関係で、元ドキュメントにない余分な説明を追加してしまっています。面白いのとよりわかりやすくなったので、特に削除しないで訳や体裁の問題だけ修正してあります。

ライブラリ仕様

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

  • リビジョン1はArduino IDEバージョン1.5.3から実装されました（現在はリビジョン2に置き換えられています）
  • リビジョン2はArduino IDEバージョン1.5.6から実装されます
  • リビジョン2.1はArduino IDEバージョン1.6.10から実装されます
  • リビジョン2.2はArduino IDEバージョン1.8.10から実装されます

この新しいライブラリフォーマットは、Arduino IDE 1.6.2以降で利用可能なLibrary Managerと連携して使用することを意図しています。 ライブラリマネージャーを使用すると、ユーザーはプロジェクトに必要なライブラリを自動的にダウンロードしてインストールすることができます。 これは、Arduino IDE/Arduino IDE 2.0 および Arduino Web Editorのグラフィカルなインターフェースや、arduino-cli libを通じて行うことができます。

Library Managerの動作に関する詳細情報はこちらで入手できます。

Arduinoの開発ソフトウェアは複数のマイクロコントローラーアーキテクチャ(例えばAVR、SAMなど)をサポートしており、ライブラリは複数のアーキテクチャで動作する必要があります。 新しい1.5ライブラリフォーマットには、クロスアーキテクチャライブラリのための特別なサポートは含まれていませんが、ライブラリが特定のアーキテクチャに向けてコードのセクションをターゲットにするためのプリプロセッサベースのメカニズムを提供しています。

参照

1.5ライブラリフォーマット (リビジョン2.2)

ライブラリメタデータ

このフォーマットへの最も重要な追加点は、library.properties というプロパティファイルを通じてライブラリ自体に関する情報を追加する能力です。

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

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

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

  • name - ライブラリの名前。ライブラリ名には基本的な文字（A-Zまたはa-z）と数字（0-9）、スペース（ ）、アンダースコア（_）、ドット（.）およびダッシュ（-）のみを含めることができます。文字または数字で始まり、少なくとも一つの文字を含む必要があります。Arduinoで始まるname値のライブラリは、これらの名前が公式の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ページなど。これはライブラリマネージャーの「詳細情報」リンクで使用されます。
  • architectures - （デフォルトは*）ライブラリがサポートするアーキテクチャのカンマ区切りリスト。ライブラリがアーキテクチャ特有のコードを含まない場合は、*を使用してすべてのアーキテクチャに一致させます。このフィールドは、複数のライブラリが#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ファイルをリンカーコマンドに直接含めるのではなく、.aファイルに保存し、それをリンカーコマンドに含めます。
  • includes - （Arduino IDE 1.6.10から利用可能）（オプション）スケッチに#include <...>行として追加されるライブラリのファイルのカンマ区切りリスト。このプロパティはArduino IDEの「ライブラリを含める」コマンドで使用されます。includesプロパティが欠けている場合、ルートソースフォルダのすべてのヘッダーファイル（.h）が含まれます。
  • precompiled - (Arduino IDE 1.8.6/arduino-builder 1.4.0から利用可能) （オプション）.a（アーカイブ）ファイルや.so（共有オブジェクト）ファイルのサポートを有効にします。これらのファイルに必要なライブラリ内の場所については、“Precompiled binaries” セクションを参照してください。静的ライブラリは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

例えば、

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フィールドに指定された依存関係の最新バージョンがライブラリと共にインストールされます。特定のバージョンまたはバージョンの範囲を指定することもサポートされています。

以下のオペレーターが利用可能です：
= と等しい
> より大きい
>= 以上
< より小さい
<= 以下
! NOT（否定）1
&& AND（論理積）
|| OR（論理和）
(, ) 制約グループ

1 Arduino IDE 2.0.0-rc7/Arduino CLI 0.22.0から利用可能

例

もしライブラリ “ArduinoHttpClient” に以下のリリースがあるとすると:

  • 0.1.0
  • 1.0.0
  • 2.0.0
  • 2.1.0

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

depends フィールドの値 インストールされる
バージョン
ArduinoHttpClient 2.1.0
ArduinoHttpClient (=1.0.0) 1.0.0
ArduinoHttpClient (>1.0.0) 2.1.0
ArduinoHttpClient (>=1.0.0) 2.1.0
ArduinoHttpClient (<2.0.0) 1.0.0
ArduinoHttpClient (<=2.0.0) 2.0.0
ArduinoHttpClient (!=1.0.0) 2.1.0
ArduinoHttpClient (>1.0.0 && <2.1.0) 2.0.0
ArduinoHttpClient (<1.0.0 || >2.0.0) 2.1.0
ArduinoHttpClient ((>0.1.0 && <2.0.0) || >2.1.0) 1.0.0

フォルダとファイルのレイアウト

各フォルダには特定の目的（ソース、例、ドキュメントなど）があります。この仕様でカバーされていないフォルダは、将来の改訂において必要に応じて追加される可能性があります。

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

ライブラリルートフォルダの名前は、基本的な文字（A-Zまたはa-z）または数字（0-9）で始まり、その後に基本的な文字、数字、アンダースコア（_）、ドット（.）、ダッシュ（-）が続きます。最大長は63文字です。

ソースコード

Arduino IDE 1.5.x以降で使用されることを意図したライブラリの場合、ソースコードはsrcフォルダ内にあります。例えば：

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

srcフォルダと_そのすべてのサブフォルダ_にあるソースコードは、ユーザーのスケッチにコンパイルされてリンクされます。 src フォルダのみがインクルード検索パスに追加されます（スケッチとライブラリのコンパイル時に）。ユーザーがライブラリを自分のスケッチにインポートする場合（Arduino IDEの「Sketch > Include Library」メニューやArduino Web Editorの「Include」ボタンから）、デフォルトの動作（library.properties includes フィールドを介して設定可能）は、src/ディレクトリ（ただし、そのサブフォルダではない）内のすべてのヘッダー（.h）ファイルに対して #include ステートメントが追加されることです。 その結果、これらのヘッダーファイルは、あなたのライブラリへの事実上のインターフェースを形成します。 一般的に、ルートのsrc/フォルダにあるヘッダーファイルは、ユーザーのスケッチに公開したいものであり、ライブラリの将来のバージョンでも互換性を維持する予定のものであるべきです。 内部ヘッダーファイルは、src/フォルダのサブフォルダに配置してください。

Arduino IDE 1.0.xとの後方互換性を考慮して、ライブラリの作者はソースコードをsrcと呼ばれるフォルダではなく、ルートフォルダに配置することを選択する場合があります。 この場合、1.0のライブラリ形式が適用され、ソースコードはライブラリルートフォルダとutilityフォルダから検索されます。例えば：

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 layout

レイアウト ルートがコンパイルされる srcがコンパイルされる utilityがコンパイルされる
recursive いいえ 再帰的に いいえ
flat はい いいえ はい

事前コンパイルされたバイナリ

library.propertiesのprecompiledフィールドは、事前コンパイルされたライブラリの使用をサポートするためのものです。これには、特定のプロセッサアーキテクチャ用にコンパイルされた.a（アーカイブ）または.so（共有オブジェクト）ファイルの提供が必要です。ファイルの対象アーキテクチャは、フォルダ名によって示されます。

バイナリはsrc/{build.mcu}に配置される必要があります。ここで{build.mcu}はファイルがコンパイルされた対象のアーキテクチャ名です。例：Arduino Dueの場合はcortex-m3。

コンパイルされたバイナリのファイル名は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コンパイラフラグの値です。(Arduino IDE 1.8.13/arduino-builder 1.5.3/Arduino CLI 0.11.0から利用可能) 浮動小数点設定のフラグが使用されているが、その設定に一致するフォルダが見つからない場合、src/{build.mcu}がフォールバックとして使用されます。

以下は、ライブラリ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アーキテクチャ用のアーカイブファイルを提供する例のライブラリsrcフォルダ構造です。

ライブラリ名/
├── src/
│   ├── ライブラリ名.h          # ライブラリAPIの宣言を含むヘッダーファイル
│   ├── ライブラリ名.cpp        # 他のアーキテクチャ用のフォールバックとしてのソースファイル
│   ├── cortex-m0plus/
│   │   └── libライブラリ名.a   # Arduino SAMDボードのARM Cortex M0+アーキテクチャ用アーカイブファイル
│   ├── cortex-m4/
│   │   └── libライブラリ名.a   # Arduino Nano 33 BLEのARM Cortex M4アーキテクチャ用のフォールバックアーカイブファイル
│   └── cortex-m4/softfp-fpv4-sp-d16/
│       └── libライブラリ名.a   # `-mfloat-abi=softfp -mfpu=fpv4-sp-d16`の浮動小数点ABI設定用のArduino Nano 33 BLEのARM Cortex M4アーキテクチャ用アーカイブファイル

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フォルダの名前は正確にそのように（小文字で）記述される必要があります。

Servo/examples/...

examplesフォルダ内に含まれるスケッチは、Arduino IDEおよびArduino Web EditorのExamplesメニューに表示されます。

詳細情報：

追加のドキュメント

extras フォルダは、開発者がライブラリにバンドルするドキュメントやその他のアイテムを置くために使用できます。このフォルダ内に配置されたファイルはライブラリのサイズを増加させるので、数キロバイトのライブラリに20MBのPDFを入れることはあまり良い考えではないかもしれません。

extras フォルダの内容はArduino開発ソフトウェアによって完全に無視されるので、中に何を置いても自由です。

キーワード

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

Servo/keywords.txt

keywords.txtファイルの例：

# ExampleLibrary用のシンタックスカラーリングマップ

# データタイプ (KEYWORD1)
Test	KEYWORD1

# メソッドと関数 (KEYWORD2)
doSomething	KEYWORD2

# インスタンス (KEYWORD2)

# 定数 (LITERAL1)

このファイルは、Arduino IDEにTestをデータタイプとして、doSomethingをメソッド/関数としてハイライトするよう指示します。

keywords.txtのフォーマット

keywords.txtは、単一の真のタブ（スペースではない）で区切られた4つのフィールドでフォーマットされます：

KEYWORD	KEYWORD_TOKENTYPE	REFERENCE_LINK	RSYNTAXTEXTAREA_TOKENTYPE

フィールドを空白のままにしておくことも許可されています。

KEYWORD_TOKENTYPE
KEYWORD_TOKENTYPE 用途 テーマプロパティ
KEYWORD1 データタイプ editor.data_type.style
KEYWORD2 関数 editor.function.style
KEYWORD3 構造体 editor.function.style
LITERAL1 定数 editor.reserved_word_2.style
LITERAL2 ? editor.function.style

この表は、KEYWORD_TOKENTYPEの各値がkeywords.txtファイル内でどのように使用され、Arduino IDEのテーマプロパティとどのように関連しているかを示しています。たとえば、KEYWORD1はデータタイプ用に、KEYWORD2は関数用に、LITERAL1は定数用に使用されます。これらのキーワードは、Arduino IDE内の対応するテーマプロパティに従って色付けされます。

このフィールドは、カーソルがそのキーワード上にあるときに、Arduino IDEの 右クリック > リファレンスで検索 または ヘルプ > リファレンスで検索 を通じて開くArduino言語リファレンスページを指定します。一般的に、第三者のライブラリキーワードにREFERENCE_LINKフィールドを定義することは意味がありません。なぜなら、それらはArduino言語リファレンスに掲載されている可能性が低いためです。

RSYNTAXTEXTAREA_TOKENTYPE

Arduino IDE 1.6.5以降では、このフィールドはKEYWORD_TOKENTYPEを上書きします。以前のIDEバージョンでは、RSYNTAXTEXTAREA_TOKENTYPEフィールドは無視され、代わりにKEYWORD_TOKENTYPEが使用されます。

RSYNTAXTEXTAREA_TOKENTYPE テーマプロパティ KEYWORD_TOKENTYPEの同等項目
RESERVED_WORD editor.reserved_word.style KEYWORD3
RESERVED_WORD_2 editor.reserved_word_2.style LITERAL1
DATA_TYPE editor.data_type.style KEYWORD1
PREPROCESSOR editor.preprocessor.style KEYWORD3
LITERAL_BOOLEAN editor.literal_boolean.style LITERAL1

この表は、RSYNTAXTEXTAREA_TOKENTYPEの各値がArduino IDEのテーマプロパティとどのように関連しており、KEYWORD_TOKENTYPEと同等のものが何かを示しています。たとえば、RESERVED_WORDはeditor.reserved_word.styleテーマプロパティに関連しており、KEYWORD_TOKENTYPEのKEYWORD3に相当します。

開発フラグファイル

通常、Arduino IDEはライブラリフォルダの内容を読み取り専用として扱います。これは、ユーザーが誤って例示スケッチを変更するのを防ぐためです。ライブラリの開発プロセス中には、Arduino IDEを使用してその場で例示スケッチを編集したい場合があるでしょう。Arduino IDE 1.6.6以降では、ライブラリフォルダのルートに.developmentという名前のファイルを追加することで、読み取り専用の挙動を無効にすることができます。library.propertiesファイルも存在している必要があります。Library Manager indexerは、.developmentファイルを含むリリースをピックアップしないので、このファイルをリモートリポジトリにプッシュしないように注意してください。

完全な例

仕様に従っている架空のライブラリ “Servo” の例を以下に示します：

Servo/
├── library.properties     # ライブラリのプロパティファイル
├── keywords.txt           # キーワード定義ファイル
├── src/                   # ソースコードフォルダ
│   ├── Servo.h            # ヘッダーファイル
│   ├── Servo.cpp          # メインのソースファイル
│   └── ServoTimers.h      # タイマー関連のヘッダーファイル
├── examples/              # 例示スケッチフォルダ
│   ├── Sweep/             # 「Sweep」例
│   │   └── Sweep.ino
│   └── Pot/               # 「Pot」例
│       └── Pot.ino
└── extras/                # 追加ドキュメントフォルダ
    └── Servo_Connectors.pdf

この構造は、library.propertiesとkeywords.txtでライブラリの設定とキーワードを定義し、srcフォルダでソースコードを管理し、examplesフォルダでユーザーが参考にできる例示スケッチを提供し、extrasフォルダで追加のドキュメントを提供する、Arduinoライブラリの一般的な形式を示しています。

複数のアーキテクチャとの作業

スケッチブックフォルダ（別名 “ユーザーディレクトリ”）の libraries サブフォルダに配置されたライブラリは、複数の異なるプロセッサアーキテクチャを含むすべてのボードで利用可能になります。アーキテクチャ固有のコードや最適化を提供するために、ライブラリ作者は ARDUINO_ARCH_XXX プリプロセッサマクロ（#define）を使用できます。ここで、XXXはボードのプラットフォームのアーキテクチャフォルダの名前によって決定されるアーキテクチャの名前です。例えば、AVRベースのボードでコンパイルするときに ARDUINO_ARCH_AVR が定義されます。

この機能を使用することで、ライブラリ開発者は異なるアーキテクチャに基づいて異なるコードを実行させることができます。これにより、特定のアーキテクチャに特化した最適化や機能を実装することが可能になり、より効率的で高性能なArduinoプロジェクトの開発が可能になります。

複数のアーキテクチャとの作業

スケッチブックフォルダ（別名 “ユーザーディレクトリ”）の libraries サブフォルダに配置されたライブラリは、複数の異なるプロセッサアーキテクチャを含むすべてのボードで利用可能になります。アーキテクチャ固有のコードや最適化を提供するために、ライブラリの著者は ARDUINO_ARCH_XXX プリプロセッサマクロ（#define）を使用できます。ここでXXXは、ボードのプラットフォームのアーキテクチャフォルダの名前によって決定されるアーキテクチャの名前です。たとえば、AVRベースのボードでコンパイルする場合は ARDUINO_ARCH_AVR が定義されます。

例：

#if defined(ARDUINO_ARCH_AVR)
  // AVR専用のコード
#elif defined(ARDUINO_ARCH_SAM)
  // SAM専用のコード
#else
  // 汎用、プラットフォーム非依存のコード
#endif

あるいは、ライブラリが特定のアーキテクチャでのみ動作する場合は、コンパイルが難解な方法で失敗するのを防ぐために、明示的なエラーメッセージを提供することもできます：

#if defined(ARDUINO_ARCH_AVR)
  // AVR専用のコード
#elif defined(ARDUINO_ARCH_SAM)
  // SAM専用のコード
#else
  #error "このライブラリはAVRまたはSAMプロセッサを搭載したボードのみをサポートしています。"
#endif

このような方法で、ライブラリの著者は特定のアーキテクチャに対応したコードを効果的に管理し、互換性のないプラットフォームでの混乱やエラーを防ぐことができます。

旧ライブラリ形式（1.5以前）

Arduino IDE 1.0.xの古いライブラリをサポートするために、Arduino IDEとArduino CLIは、library.propertiesメタデータファイルがないライブラリもコンパイルします（ヘッダーファイルは依然として必要です）。その結果、これらのライブラリはArduino IDE 1.0.xでの動作と同様に振る舞うはずですが、AVR以外のボードを含むすべてのボードで利用可能になります（これらはArduino IDE 1.0.xでは存在しなかったでしょう）。

この対応により、Arduino IDEとArduino CLIは古いライブラリと新しいライブラリの両方との互換性を保ちながら、開発者が新しいハードウェアプラットフォームを活用できるようになります。ただし、古いライブラリが新しいボードで完全に機能するとは限らないため、問題が発生した場合はライブラリの更新が必要になることがあります。