スケッチビルドプロセス

Arduino開発ソフトウェアがスケッチをビルドするために使用するプロセス。 より詳細な情報は、Arduinoプラットフォーム仕様に記載されています。 以下は特にAVRターゲット向けのビルドプロセスを指しています。 他のアーキテクチャは類似したビルドプロセスを採用していますが、異なるツールやコンパイラを使用する場合があります。

概要

ArduinoコードをArduinoボードにアップロードするには、いくつかの手順が必要です。 まず、Arduino開発ソフトウェアは、スケッチをC++プログラムに変換するための簡単な前処理を行います。 次に、スケッチの依存関係が特定されます。 その後、コンパイラ(例: avr-gcc)に渡され、人が読めるコードが機械が読める命令(またはオブジェクトファイル)に変換されます。 次に、コードは、digitalWrite()やSerial.print()などの基本的な機能を提供する標準のArduinoライブラリと組み合わせられます(リンクされます)。 その結果、特定のバイトがArduinoボードのチップのプログラムメモリに書き込まれる必要がある単一のIntel HEXファイルが生成されます。 このファイルは、ボードにアップロードされます。これは、チップにすでにあるブートローダーを介してUSBまたはシリアル接続を介して送信されるか、外部のプログラミングハードウェアを使用して行われます。

前処理

Arduino開発ソフトウェアは、スケッチをコンパイラ(たとえば、avr-gcc)に渡す前に、いくつかの変換を行います:

• スケッチフォルダー内のすべての .inoおよび.pdeファイル(Arduino IDEでは拡張子のないタブとして表示されます)が連結されます。 連結はフォルダー名と一致するファイルから始まり、他のファイルはアルファベット順に続きます。 次に、結果のファイルに.cppの拡張子が追加されます
• スケッチに #include <Arduino.h> が含まれていない場合、このヘッダーファイルが追加されます(選択したボードのコアフォルダーにあります)。 このヘッダーファイルには、標準のArduinoコアに必要なすべての定義が含まれています
• .ino/.pdeファイル内のすべての関数定義に対してプロトタイプが生成されます(すでにプロトタイプが存在しない場合)。 一部の稀なケースでは、一部の関数のプロトタイプ生成が失敗することがあります。これを回避するために、これらの関数に独自のプロトタイプを提供することができます
• ワーニングやエラーメッセージが元のスケッチレイアウトを反映するようにするために、#line ディレクティブが追加されます

スケッチ内の .inoまたは.pde以外の拡張子を持つファイルに対しては、事前処理は行われません。 さらに、スケッチ内の.hファイルは、メインのスケッチファイルから自動的に#includeされません。 さらに、スケッチから生成された .cppファイルなどのファイルから.cファイルで定義された関数を呼び出す場合、その宣言を C++ ファイル内でのみ定義される extern "C" {} ブロックでラップする必要があります。

依存関係の解決

スケッチは依存関係を再帰的にスキャンします。事前定義されたインクルード検索パスは次のとおりです：

1. コアライブラリフォルダ({build.core} で定義されたもの)
2. バリアントフォルダ({build.variant} で定義されたもの)
3. 標準のシステムディレクトリ(たとえば、{runtime.tools.avr-gcc.path}/avr/include)
4. 以前の依存関係を解決するために追加されたインクルード検索パス

これらの場所に依存関係が存在しない場合、インストールされたライブラリが検索されます(ライブラリの場所に関するLocation Priorityテーブルを参照してください)。 許可されているライブラリのサブフォルダ構造に関する情報は、Arduinoライブラリ仕様を参照してください。 各ライブラリ依存関係のパスに対して-Iオプションが生成され、includesプロパティに追加されます。 これは、platform.txt内のコンパイルレシピで使用されます。

複数のライブラリに、#includeディレクティブと一致するファイルが含まれている場合、優先度は次のルールを順番に適用し、ルールが勝者を決定するまで続けられます:

1. arduino-cli compileの--libraryオプションで指定されたライブラリは、他の場所のライブラリに優先します。
2. アーキテクチャ互換性のあるライブラリは、アーキテクチャ互換性のないライブラリよりも優先されます(Architecture Matchingを参照)
3. インクルードに一致するライブラリ名およびフォルダ名を持つライブラリが優先されます
4. "ライブラリ名の優先度"または"フォルダ名の優先度"が高いライブラリが優先されます(Library Name PriorityおよびFolder Name Priorityを参照)
5. アーキテクチャ最適化されたライブラリは、アーキテクチャ最適化されていないライブラリよりも優先されます(Architecture Matchingを参照)
6. "location priority"が高いライブラリが優先されます(Location Priorityを参照)
7. "closest-match"アルゴリズムを使用してスコアが高いフォルダ名を持つライブラリが優先されます
8. アルファベット順に最初に来るフォルダ名を持つライブラリが優先されます

アーキテクチャのマッチング

ライブラリは、library.propertiesのarchitecturesフィールドに次のように指定されている場合、アーキテクチャXと互換性があると見なされます:

• 明示的にアーキテクチャXを含む
• キャッチオールの*を含む
• 何も指定されていない

ライブラリがアーキテクチャX向けに最適化されていると見なされるのは、library.propertiesのarchitecturesフィールドにアーキテクチャXが明示的に含まれている場合のみです。 これは、アーキテクチャX向けに最適化されたライブラリは、それと互換性があるということです。

例:

library.propertiesのarchitecturesフィールド	avrと互換性あり	avr向けに最適化されている
未指定	YES	NO
architectures=*	YES	NO
architectures=avr	YES	YES
architectures=*,avr	YES	YES
architectures=*,esp8266	YES	NO
architectures=avr,esp8266	YES	YES
architectures=samd	NO	NO

ライブラリ名の優先順位

ライブラリの名前は、library.propertiesのnameフィールドによって定義されます。この値は、比較のためにファイル名にスペースを_で置換してから、使用されます。

「ライブラリ名の優先度」は、以下のように決定されます(優先度が高い順から低い順に):

ルール	Arduino_Low_Power.h の例
ライブラリ名が include と完全に一致する	Arduino Low Power
ライブラリ名が include と 100% 一致するが、-main 接尾辞がある場合	Arduino Low Power-main
ライブラリ名が include と 100% 一致するが、-master 接尾辞がある場合	Arduino Low Power-master
ライブラリ名に一致する接頭辞がある	Arduino Low Power Whatever
ライブラリ名に一致する接尾辞がある	Awesome Arduino Low Power
ライブラリ名に include が含まれている	The Arduino Low Power Lib

フォルダー名の優先順位

「フォルダー名の優先度」は以下のように決定されます(優先度の高い順から低い順):

ルール	Servo.hに対する例
フォルダー名がインクルードと完全に一致する	Servo
フォルダー名がインクルードと100%一致するが、-main接尾辞が付いている	Servo-main
フォルダー名がインクルードと100%一致するが、-master接尾辞が付いている	Servo-master
フォルダー名に一致するプレフィックスがある	ServoWhatever
フォルダー名に一致するサフィックスがある	AwesomeServo
フォルダー名がインクルードを含んでいる	AnAwesomeServoForWhatever

location priority

「location priority」は以下のように決定されます(優先度が高い順):

1. arduino-cli compileの--librariesオプションで指定されたカスタムライブラリパスの下にライブラリが存在する(複数のカスタムパスが定義されている場合は、優先度が高い順に)
2. ライブラリがIDEのスケッチブックまたはArduino CLIのユーザーディレクトリのlibrariesサブフォルダにある
3. ライブラリがボードプラットフォーム/コアとバンドルされている({runtime.platform.path}/libraries)
4. ライブラリが参照されているボードプラットフォーム/コアとバンドルされている
5. ライブラリがArduino IDEとバンドルされている(この場所はArduino CLIの設定で決定されます directories.builtin.libraries)

Arduino Web エディターでの場所の優先順位

ライブラリの場所の優先順位システムは、Arduino Web Editorでも同様に機能しますが、クラウドベースの性質からライブラリの場所が明らかになりにくい場合があります。

1. カスタム: Libraries > Custom タブに表示されるインポートされたライブラリ。
   • これらのライブラリは /tmp/<some number>/custom の下にあります
2. ピン留め: スケッチと関連付けられたライブラリで、ライブラリの「Include」ドロップダウンメニューから特定のバージョンを選択して選択されたもの
   • これらのライブラリは /tmp/<some number>/pinned の下にあります
   • 注:「Include」ボタンをクリックしても、ライブラリがスケッチにピン留めされるわけではありません
3. プラットフォームバンドル: これらはLibraries > Default タブにリストされていますが、ライブラリ名に"for <architecture name>"が追加されています(例: “SPI for AVR”)
   • これらのライブラリは /home/builder/.arduino15/packages の下にあります
     1. ボードプラットフォームバンドル
     2. コアプラットフォームバンドル
4. ビルトイン:
   • Libraries > Default タブにリストされているプラットフォームバンドルされていないライブラリ
   • Libraries > Library Manager にリストされているライブラリ
   • これらのライブラリは /home/builder/opt/libraries/latest の下にあります

コンパイル

スケッチは、選択されたボードのプラットフォームのboards.txtファイル内の変数に従って、アーキテクチャ固有のバージョンの gcc と g++ によってコンパイルされます。

スケッチは、システム全体の一時ディレクトリ(例: Linuxの場合は/tmp)内の一時ディレクトリにビルドされます。

ビルドプロセスのソースファイルとして取られるファイルは、.S, .cおよび .cpp ファイルです(スケッチの .ino および .pde ファイルから生成される .cpp ファイルも含まれます)。 ターゲットのソースファイルはこのビルドディレクトリに .o 拡張子でコンパイルおよび出力されます。 また、スケッチ内のメインスケッチファイルやスケッチ内で #include されているライブラリの他のソースファイルも同様に処理されます。

ソースファイルをコンパイルする前に、以前にコンパイルされた .o ファイルを再利用しようとします。 これにより、ビルドプロセスが高速化されます。 特別な .d(依存)ファイルは、ソースによって含まれるすべての他のファイルのリストを提供します。 .oおよび.dファイルが存在し、そのタイムスタンプがソースおよびすべての依存ファイルより新しい場合、コンパイルステップはスキップされます。 ソースまたは依存ファイルのいずれかが変更された場合、またはファイルの検証中にエラーが発生した場合、コンパイラは通常通り実行され、新しい .o および.dファイルが書き込まれます。 IDEのボードメニューから新しいボードが選択されると、次のコンパイル時にすべてのソースファイルが再構築されます。

これらの.oファイルは、次に静的ライブラリにリンクされ、メインスケッチファイルがこのライブラリに対してリンクされます。 スケッチに必要なライブラリの部分だけが最終的な .hexファイルに含まれるため、ほとんどのスケッチのサイズが削減されます。

.hexファイルはコンパイルの最終出力であり、その後ボードにアップロードされます。

コンパイル時の詳細な出力が有効になっている場合、ビルドプロセスの一部として実行される各外部コマンドの完全なコマンドラインがコンソールに出力されます。

アップロード

スケッチは、プラットフォーム固有のアップロードツール(例: avrdude)によってアップロードされます。 アップロードプロセスも、ボードおよびメインの設定ファイル内の変数によって制御されます。 詳細についてはArduinoプラットフォーム仕様ページを参照してください。

アップロード中の詳細な出力が有効になっている場合、デバッグ情報がコンソールに出力され、アップロードツールのコマンドラインと詳細な出力が表示されます。