Arduino公式文書の翻訳

2024年1月16日

2024年2月9日

この文書のオリジナルはarduino-cliにあるSketch project fileです。

スケッチプロジェクトファイル

スケッチのメタデータは、sketch.yaml という名前のファイルで定義されます。このファイルは YAML 形式です。

プロファイルを作成する

Arduino CLI は、ビルドプロファイルを使って再現可能なビルドの提供をします。

プロファイルは、スケッチの構築に必要なすべてのリソースの完全な説明です。スケッチプロジェクトァイルには複数のプロファイルが含まれる場合があります。

各プロファイルは以下のものを定義しています。

ボードのFQBN
ターゲットのコアプラットフォームの名前とバージョン(必要に応じてサードパーティプラットフォームのインデックスURLも含みます)
想定されるコアプラットフォームの名前とバージョン、ターゲットコアプラットフォームの依存関係(必要に応じてサードパーティプラットフォームのインデックスURLも含みます)
スケッチで使用されているライブラリ(それらのバージョンも含みます)

ファイルの形式は次のとおりです。

profiles:
  <PROFILE_NAME>:
    notes: <USER_NOTES>
    fqbn: <FQBN>
    platforms:
      - platform: <PLATFORM> (<PLATFORM_VERSION>)
        platform_index_url: <3RD_PARTY_PLATFORM_URL>
      - platform: <PLATFORM_DEPENDENCY> (<PLATFORM_DEPENDENCY_VERSION>)
        platform_index_url: <3RD_PARTY_PLATFORM_DEPENDENCY_URL>
    libraries:
      - <LIB_NAME> (<LIB_VERSION>)
      - <LIB_NAME> (<LIB_VERSION>)
      - <LIB_NAME> (<LIB_VERSION>)

  ...more profiles here...

profiles:には、すべてのプロファイルを含むオプションのセクションがあります。(特に明記されていない限り)プロファイルの各フィールドは必須です。使用可能なフィールドは以下のとおりです。

<PROFILE_NAME>はプロファイル識別子で、ユーザー定義フィールドです。使用できる文字は英数字、アンダースコア_、ドット.、およびダッシュ-です
<PLATFORM>は、ターゲットコアプラットフォームの識別子です(たとえば、arduino:avr や adafruit:samd)
<PLATFORM_VERSION> は、ターゲットコアプラットフォームの要求されているバージョンです
<3RD_PARTY_PLATFORM_URL> は、ターゲットコアプラットフォームをダウンロードするためのインデックス URL (Arduino IDE では“Additional Boards Manager URLs”(追加のボードマネージャーURL)とも呼ばれます)です。公式の arduino:* プラットフォームでは、このフィールドは省略できます
<PLATFORM_DEPENDENCY>、<PLATFORM_DEPENDENCY_VERSION>、および <3RD_PARTY_PLATFORM_DEPENDENCY_URL> には、それぞれメインコアプラットフォームの<PLATFORM>、<PLATFORM_VERSION>、および <3RD_PARTY_PLATFORM_URL> とほぼ同じ情報が含まれていますが、コアプラットフォームの依存関係が異なります。これらのフィールドはオプションです
libraries: は、プロジェクトをビルドするために必要なライブラリが定義されるセクションです。このセクションはオプションです
<LIB_VERSION> は、ライブラリに必要なバージョン(たとえば、1.0.0)です
<USER_NOTES> は、開発者がコメントを追加するために使用できるフリーテキスト文字列です。このフィールドはオプションです。

以下はスケッチプロジェクトファイルの完全な例です。

profiles:
  nanorp:
    fqbn: arduino:mbed_nano:nanorp2040connect
    platforms:
      - platform: arduino:mbed_nano (2.1.0)
    libraries:
      - ArduinoIoTCloud (1.0.2)
      - Arduino_ConnectionHandler (0.6.4)
      - TinyDHT sensor library (1.1.0)

  another_profile_name:
    notes: testing the limit of the AVR platform, may be unstable
    fqbn: arduino:avr:uno
    platforms:
      - platform: arduino:avr (1.8.4)
    libraries:
      - VitconMQTT (1.0.1)
      - Arduino_ConnectionHandler (0.6.4)
      - TinyDHT sensor library (1.1.0)

  tiny:
    notes: testing the very limit of the AVR platform, it will be very unstable
    fqbn: attiny:avr:ATtinyX5:cpu=attiny85,clock=internal16
    platforms:
      - platform: attiny:avr@1.0.2
        platform_index_url: https://raw.githubusercontent.com/damellis/attiny/ide-1.6.x-boards-manager/package_damellis_attiny_index.json
      - platform: arduino:avr@1.8.3
    libraries:
      - ArduinoIoTCloud (1.0.2)
      - Arduino_ConnectionHandler (0.6.4)
      - TinyDHT sensor library (1.1.0)

  feather:
    fqbn: adafruit:samd:adafruit_feather_m0
    platforms:
      - platform: adafruit:samd (1.6.0)
        platform_index_url: https://adafruit.github.io/arduino-board-index/package_adafruit_index.json
    libraries:
      - ArduinoIoTCloud (1.0.2)
      - Arduino_ConnectionHandler (0.6.4)
      - TinyDHT sensor library (1.1.0)

default_profile: nanorp

スケッチのビルド

スケッチプロジェクトファイルが存在する場合には、compile コマンドで--profile/-m フラグを使用してスケッチをコンパイルできます。

arduino-cli compile --profile nanorp

この例の場合、スケッチは、nanorp プロファイルで指定されたコアプラットフォームとライブラリを使用してコンパイルされます。コアプラットフォームまたはライブラリが見つからない場合は、自動的にダウンロードされ、データフォルダー内の分離されたディレクトリに(コンパイルを)実行しながらインストールされます。専用ストレージにはユーザーはアクセスできず、スケッチの構築に使用されるリソースの「キャッシュ」として使用されます。

プロファイルベースのビルドを使用する場合、グローバルにインストールされたプラットフォームとライブラリはコンパイルから除外され、いかなる方法でも使用できなくなります。言い換えれば、ビルドはシステムから分離され、プロファイルで指定されたリソースのみに依存します。これにより、ビルドはシステムにインストールされているプラットフォームやライブラリから独立して移植可能で再現可能になります。

デフォルトのプロファイルを使用する

sketch.yamlにdefault_profileが指定されている場合、“classic” コンパイルコマンド：

arduino-cli compile [sketch]

は、代わりにsketch.yamlに指定されたデフォルトプロファイルを使用してプロファイルベースのビルドを起動します。

Arduino CLI使用のためのデフォルトのフラグ

スケッチプロジェクトファイルは、Arduino CLIのいくつかのコマンドラインフラグのデフォルト値を設定するために使用される場合があります。特に：

default_fqbn キーは --fqbn フラグのデフォルト値を設定します
default_port キーは --port フラグのデフォルト値を設定します
default_protocol キーは --protocol フラグのデフォルト値を設定します
default_profile キーは --profile フラグのデフォルト値を設定します

例えば：

default_fqbn: arduino:avr:uno
default_port: /dev/ttyACM0
default_protocol: serial
default_profile: myprofile

この設定がされている場合、スケッチをコンパイルまたはアップロードする際にarduino-cli compile または arduino-cli upload コマンドに --fqbn、--port、--protocol、または --profile フラグを指定する必要はありません。