esp-idf-components

ESP-IDF コンポーネント

使用する場面

• プロジェクト固有のコンポーネント、または単独で再利用できるコンポーネントを作成する場合。
• Registry の依存関係と新規実装のどちらを選ぶか判断する場合。
• コンポーネントの API、CMake の依存関係、Kconfig、マニフェスト、テスト、CI を定義する場合。
• ESP Component Registry パッケージを準備またはレビューする場合。

ワークフロー

1. 新しいコンポーネントが必要か判断する

• まず ESP Component Registry を検索します。利用できる場合は Registry MCP ツールを優先し、代替手段として公開 API またはウェブサイトを使用します。
• 候補を ESP-IDF とターゲットの互換性、メンテナンス状況、ライセンス、API との適合性で比較します。残った選択肢が重要な場合にのみ、ユーザーに確認します。
• 適切な既存コンポーネントがあれば、重複して実装するのではなく、それを利用します。
• 製品固有のコードはアプリケーションの components/ の下に置き、独立してバージョン管理する再利用可能なコードには単独パッケージを使用します。

2. 既存の依存関係を追加する

• プロジェクトのルートから idf.py add-dependency "namespace/component^<VERSION>" を実行します。デフォルトでは main が更新されます。
• components/ の下にあるコンポーネントには --component=<NAME> を、別のコンポーネントディレクトリには --path=<PATH> を使用します。
• 再現性が重要な場合は、バージョン制約を明示します。dependencies.lock や managed_components/ を手動で編集しないでください。

3. 新しいコンポーネントのひな形を作成する

• ボイラープレートを手動で生成せず、idf.py create-component <COMPONENT_NAME> を使用します。目的の親ディレクトリで実行するか、-C <PATH> を使用します。
• ローカルコンポーネントの場合は、components/ の下にひな形を作成します。
• 単独パッケージの場合は、リポジトリのルートにひな形を作成し、必要なパッケージファイルのみを追加します。
• idf.py create-manifest でマニフェストを作成します。必要に応じて --component=<NAME> または --path=<PATH> を使用します。Compote がインストールされている場合は、最新の Component Manager 相当コマンドとして compote manifest create を使用できます。
• CLI、構成、Registry、CI の詳細については、references/component_manager.md をお読みください。

4. わかりやすい構成にする

• 公開ヘッダーは include/ に配置します。
• 実装ファイルと非公開ヘッダーは、公開インクルードディレクトリの外に配置します。複数のソースファイルで非公開ヘッダーを共有する場合は、PRIV_INCLUDE_DIRS で非公開インクルードディレクトリを追加します。
• 最小限のコンポーネントには、CMakeLists.txt、include/<name>.h、ソースファイルが含まれます。再利用可能なパッケージには通常、idf_component.yml、README.md、LICENSE、および少なくとも 1 つのサンプルまたはテストアプリケーションを追加します。
• build/ の下にある生成ファイルは編集しないでください。

5. コンポーネントを正しく登録する

• コンポーネントの CMakeLists.txt で idf_component_register(...) を使用します。
• SRCS と INCLUDE_DIRS を明示的に宣言します。
• コンポーネントの公開ヘッダーを通じて公開される依存関係には REQUIRES を使用します。
• 実装でのみ使用する依存関係には PRIV_REQUIRES を使用します。
• 偶発的な推移的依存関係に頼らないでください。

例：

idf_component_register(
    SRCS "my_component.c"
    INCLUDE_DIRS "include"
    REQUIRES esp_timer
    PRIV_REQUIRES driver
)

6. 明確なコンポーネント境界を定義する

• 公開 API は小さく、安定したものにします。
• 意図した API の一部でない限り、無関係な ESP-IDF ヘッダーを公開ヘッダー経由で漏らさないようにします。
• 複雑なコンポーネントでは、不透明なハンドル、明示的な初期化／終了処理関数、esp_err_t の戻り値を優先します。
• 1 つの大きなユーティリティコンポーネントを作るのではなく、無関係な役割は別々のコンポーネントに分割します。

7. 設定ファイルを意図的に使う

• コンポーネント固有のオプションには Kconfig を使用します。
• menuconfig でプロジェクトスコープに表示する必要がある場合にのみ、Kconfig.projbuild を使用します。
• たとえば MY_COMPONENT_* のように、設定シンボルに名前空間を設けます。
• 新しい設定オプションには、次の内容を含めます。
  • わかりやすいプロンプトテキスト
  • 適切なデフォルト値
  • 簡潔なヘルプテキスト
• Kconfig または Kconfig.projbuild を変更した後は、idf.py reconfigure を実行するかどうかを確認します。通常のビルドでは定義の変更が検出されますが、sdkconfig にすでに保存されている値は、デフォルト値を変更しても上書きされない場合があります。

再利用可能なコンポーネントのチェックリスト

• アプリケーションのグローバル変数、シークレット、ハードコードされたボードの選択肢に依存しないパッケージにします。
• Component Manager のメタデータや依存関係が必要な場合は、通常の Registry 公開前に idf_component.yml を追加します。
• 目的、設定、依存関係、使用方法を説明する README.md を追加します。
• プロジェクト外でコンポーネントを共有する場合は、LICENSE ファイルを追加します。
• 動作が自明でない場合は、少なくとも 1 つのサンプルまたはテストアプリを含めます。
• 対応ターゲットのビルドと、サンプルまたはテストアプリがある場合はその検証を最低限実施する CI を追加します。
• Kconfig のオプションとデフォルトは最小限に抑え、説明を記載します。
• 対応ターゲットでコンポーネントが問題なくビルドできることを確認します。
• コンポーネントを実際に公開する予定がある場合に限り、レジストリへのアップロード手順を使用します。
• CI で更新されたレジストリリリースを公開する前に、新しい idf_component.yml の version を必須にします。

検証と引き継ぎ

• コンポーネントが対応するターゲットのマトリックスに合わせて、関連するすべてのサンプルまたはテストアプリをビルドします。リポジトリの CI でマトリックスが定義されている場合は、それに従います。
• コンポーネントのルートから compote component pack --name <NAME> を実行して、パッケージ作成を検証します。
• Registry の認証情報と名前空間へのアクセスが許可されている場合は、公開せずにアップロードを検証します。 compote component upload --name <NAME> --namespace <NAMESPACE> --dry-run
• 公開ワークフローは、デフォルトでドライランモードにします。不変の Registry バージョンを作成する前に、本番環境への公開を明示的に選択するよう求めます。
• ESP-IDF のバージョン、ビルドしたターゲット、実行したテスト、パッケージ検証の結果、未検証の項目を報告します。

避けること

• 既存の依存関係を確認する前に、新しいローカルコンポーネントを作成する
• components/ 内の一度限りのプロジェクトローカルヘルパーに、再利用可能なコンポーネント用テンプレートを使用する
• 明確なコンポーネント境界があるのに、アプリのコードをすべて main/ に置く
• 公開ヘッダーで非公開の実装詳細を公開する
• PRIV_REQUIRES で十分な場合に REQUIRES を使用する
• build/ 内の生成ファイルを編集する
• managed_components/ や dependencies.lock を手動で編集する
• デフォルト値を sdkconfig.defaults* に置くべきところで、sdkconfig に広範囲な設定変更を加える