doca-argp

DOCA Arg Parser

例

• 「DOCA のサンプルにカスタムフラグを追加する。」 — これは対象範囲内です。型付きの doca_argp パラメーターを登録し、getopt に切り替えないでください。
• 「新しいパラメーターの登録時に BAD_STATE が発生する。」 — フラグの型を変更する前に、初期化 → 登録 → 開始の順序を確認してください。

手順

以下の読み込み順序に従ってください。設定／登録／デバッグについてはタスク用コンパニオンを開いてください。公開されているパラメーターの型については機能用コンパニオンを開いてください。すべてのコンパニオンファイルを開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、ユーザーが DOCA のサンプルまたは新しい DOCA 使用アプリで実際にコマンドライン作業をしていることを前提とします。ユーザーが何かを実行したい（設定／ビルド／変更／実行／テスト／デバッグ）場合はタスク用コンパニオンを開いてください。このバージョンで Arg Parser が何を表現できるかという質問の場合は、機能用コンパニオンを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。ユーザーが Arg Parser を再利用せずに getopt／argparse／カスタム解析でサンプルの CLI を書き換えようとしている場合は、コードを変更する前に機能用コンパニオンの重要なルールを読んでください。

このスキルが得意とする質問の例

このスキルが回答するために作られた Arg Parser に関する質問の「種類」と、それぞれの実例です。エージェントは、重要な点は「種類」であり、実例はその一例にすぎないことを踏まえてください。

• 「標準 CLI を壊さずに、DOCA のサンプルに新しいフラグを追加するにはどうすればよいですか？」 — 実例：「サンプルがこれまでと同じように --device <PCI> と --sdk-log-level <level> を受け付ける状態を維持したまま、/opt/mellanox/doca/samples/doca_dma/dma_local_copy/ に --my-flag を追加する」。機能用コンパニオンの Arg Parser 再利用ルールと、タスク用コンパニオンの開始前に登録するワークフローで回答します。
• 「doca_argp_param_set_* が 2 回目の呼び出しで BAD_STATE を返すのはなぜですか？」 — 実例：「doca_argp_start による argv の解析後に新しいパラメーターを登録する」。機能用コンパニオンのライフサイクルの順序と、DOCA_ERROR_BAD_STATE に関する機能用コンパニオンのエラー分類表の行で回答します。
• 「長いコマンドラインの代わりに JSON ファイルからサンプルを実行できますか？」 — 実例：「オペレーターが毎回 10 個のフラグを入力しなくて済むよう、サンプルに ./my-config.json を指定する」。機能用コンパニオンの --json <path> 統合と、タスク用コンパニオンの JSON 設定ファイルを使うワークフロー、およびタスク用コンパニオンで回答します。
• 「--my-flag X の値が INVALID_VALUE として拒否されます。なぜですか？」 — 実例：「パラメーターを int として宣言したのに、--my-flag 0x40 を渡した」。機能用コンパニオンのパラメーター型の表と、型の不一致に関する機能用コンパニオンの行で回答します。
• 「インストール済みの DOCA に doca-argp は含まれていますか？」 — 実例：「同僚のサンプルに doca-argp が使われているが、依存する前に確認したい」。機能用コンパニオンの存在確認とバージョン検出のルールで回答します。このルールから、doca-version/SKILL.md にある正式な検出手順へのリンクもたどれます。
• 「ここでは doca-argp を使うべきですか。それとも、実際には対象範囲外のケースですか？」 — 実例：「doca_* シンボルを一切呼び出さない、ホスト側の CLI ツールを書く」。機能用コンパニオンの選択ルールにある「doca-argp を使う場合…／doca-argp を使わない場合…」の箇条書きで回答します。

対象読者

このスキルの対象は、DOCA を使用するアプリケーションを構築または変更する外部開発者です。つまり、すでにコードから doca_* を呼び出しているユーザー（C/C++ から直接、または他の言語から FFI／バインディングを介して呼び出すユーザー）であり、作成したバイナリを実行するオペレーターがサンプルごとに起動方法を覚え直さなくて済むよう、標準の DOCA CLI インターフェースを必要とするユーザーです。Arg Parser ライブラリ自体に貢献する NVIDIA の開発者向けではありません。

言語の対象範囲。 DOCA Arg Parser は、pkg-config のモジュール名が doca-argp の C ライブラリとして提供されています。提供されているサンプルは C で記述されています。C および C++ の利用者が標準的なケースであり、タスク用の補足資料にある具体例もこの経路を前提としています。他の言語の利用者（Rust、Go、Python など）は、FFI または言語固有のバインディングを通じて同じ *.so を使用します。その場合、このスキルではライフサイクル、パラメーター型、JSON 設定、標準フラグのインターフェース、エラー分類に関するガイダンスを言語に依存しない形で維持し、最終的にあらゆるラッパーが呼び出す公開 C ABI を正規のインターフェースとしてエージェントに案内します。

このスキルを読み込むタイミング

ユーザーが、どの言語であっても DOCA Arg Parser を実際に扱う場合にこのスキルを読み込みます。具体的には、次のような場合です。

• 提供済みの DOCA サンプル、または標準の DOCA CLI インターフェース（--device <PCI>、--representor <name>、--rep-list、--json <path>、--sdk-log-level <level>）を共有したい新しいアプリで、CLI フラグを追加、削除、または名前変更する場合。
• main() に doca_argp_init／doca_argp_start／doca_argp_destroy を組み込み、開始前に登録するライフサイクルと終了時のクリーンアップ契約に従う場合。
• 公開されている6種類の値を持つ列挙型（string、int、boolean、device、device representor、double）のいずれかのパラメーター型で、doca_argp_param（短い名前、長い名前、値コールバック、--help 用の説明）を登録する場合。JSON 設定ファイルは、それらのパラメーターを入力するインターフェースであり、パラメーター型ではありません。
• コマンドラインを拡張する代わりに、共通の --json <path> フラグを使って JSON ファイルから複雑な設定を読み込む場合。
• 利用環境で依存する前に、ビルド時と実行時の Arg Parser のバージョン（pkg-config --exists doca-argp、pkg-config --modversion doca-argp）を確認する場合。
• doca_argp_* 呼び出しから返された DOCA_ERROR_*（ライフサイクル、型の不一致、不明な JSON キー、読み取り不能なファイル）をデバッグする場合。
• Arg Parser の C ABI をラップする、C 以外のバインディング（Rust、Go、Python など）を設計または拡張し、ライフサイクル、パラメーター型、JSON 設定、標準フラグのルールをラッパーで遵守する場合。

DOCA の一般的な概要、DOCA 自体のインストール、または Arg Parser 以外のライブラリに関する質問では、このスキルを読み込まないでください。その場合は doca-public-knowledge-map/SKILL.md を使用してください。

このスキルが提供するもの

これは薄いローダーです。本文には、次に参照するファイルを選ぶために必要な概要だけを残しています。Arg Parser 固有の実質的な資料は、次の2つの補足ファイルにあります。

• 機能に関する補足資料 — このバージョンの Arg Parser で表現できる内容：パラメーター登録モデル、少数の公開パラメーター型、すべてのサンプルで共有される標準の DOCA CLI インターフェース、--json <path> によるファイル連携、開始前に登録するライフサイクル、Arg Parser のエラー分類（複数のライブラリで共通する DOCA_ERROR_* への対応）、可観測性のインターフェース（--help の出力と DOCA Log チャネル）、および安全性と経路選択のポリシー（doca-argp の再利用が必須となる場合と、言語ネイティブのパーサーが適切な選択肢となる場合）。
• タスクに関する補足資料 — 対象となる6つの Arg Parser 操作（configure、build、modify、run、test、debug）の手順を示すワークフロー。さらに、対象外の質問を適切な次のスキルに案内する「Deferred task verbs」ブロックもあります。

このスキルは、DOCA が標準の場所にすでにインストールされているホストまたは BlueField を前提としています。DOCA のインストールについては扱いません。その手順は doca-setup/SKILL.md を参照してください。

このスキルに意図的に含めていないもの

このスキルはエージェント向けガイダンスであり、サンプルやテンプレートの バンドルではありません。境界を明確にするため、意図的に以下を 含めていません。また、プルリクエストで追加しないでください。

• DOCA Arg Parser の使用コード（言語を問わず、あらかじめ記述されたもの）。 検証済みの Arg Parser 使用例は、同梱されている各 DOCA サンプルの /opt/mellanox/doca/samples/<library>/<sample>/ にある *_main.c ファイルです。エージェントの役割は、ユーザーをそのファイルに案内し、 doca-programming-guide/SKILL.md にある汎用の サンプル変更ワークフローを使って、最小限の差分で変更するよう指示することです。 そこに、tasks コンパニオンにある Arg Parser 固有の上書きルールを適用します。
• スタンドアロンのビルドマニフェスト（meson.build、 CMakeLists.txt、Cargo.toml など）をスキル内に配置すること。 エージェントは、pkg-config --modversion doca-argp を信頼できる情報源として、 ユーザーがインストールした DOCA に合わせて、ユーザーのプロジェクトディレクトリ内で ビルドマニフェストを作成します。
• いかなる種類の samples/、bindings/、reference/ サブツリーも作成しないでください。 「reference」とラベル付けされたものであっても、このスキルのツリー内にある 模擬的または不完全な成果物は誤解を招きます。ユーザーはそれをビルド可能なものとして 読み取るでしょう。

読み込み順序

1. ユーザーの質問が対象範囲内であることを確認するため、まずこのスキルを読みます。
2. パラメーター登録モデル、パラメーター型、標準の DOCA CLI の仕様、 --json <path> のルール、起動前に登録するライフサイクル、エラー分類、 可観測性、パス選択／安全性ポリシーについては、capabilities コンパニオンを参照してください。
3. configure、build、modify、run、test、debug の手順については、tasks コンパニオンを参照してください。

両方のコンパニオンファイルは相互にリンクし、 正規のバージョン処理ルールについては doca-version/SKILL.md に、 「Arg Parser 固有のガイダンス」ではなく「公開ドキュメントまたは インストール済みパッケージの構成を確認する」が適切な回答となる場合は、 doca-public-knowledge-map/SKILL.md にもリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開 DOCA ドキュメントの各情報源と、インストール済み DOCA パッケージの ディスク上の構成を示すルーティングテーブルです。Arg Parser の URL は https://docs.nvidia.com/doca/sdk/DOCA-Arg-Parser/index.html です。 正規のディスク上の使用例は、/opt/mellanox/doca/samples/ 以下にある 任意のサンプルの *_main.c です。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、公開 NGC DOCA コンテナーを使う まだインストールしていない場合 の手順です。このスキルは、前提条件が満たされていることを想定しています。
• doca-version/SKILL.md — 正規の DOCA バージョン処理ルールです。このスキルの ## Version compatibility では、4 方向の一致ルールへのリンクに加えて、 Arg Parser 固有の存在確認ルールを適用します。
• doca-structured-tools-contract/SKILL.md — バンドルにおける構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。 tasks コンパニオンの Command 付録はこの契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する DOCA プログラミングパターンです。 正規の pkg-config + meson ビルドパターン、同梱サンプルを変更する汎用の 初回アプリケーションワークフロー、汎用ライフサイクル、ライブラリ間で共通の DOCA_ERROR_* エラー分類、プログラム側のデバッグ手順が含まれます。 このスキルでは、これらに Arg Parser 固有の内容を重ねています。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／ プログラム／ドライバーを対象とする、横断的なデバッグ手順です。 Arg Parser 固有のデバッグ（ライフサイクル違反、登録済みパラメーターの型不一致、 不明な JSON キー）は、この手順に重ねて適用します。