doca-argp

DOCA Arg Parser

示例

• “为 DOCA 示例添加自定义标志。”——这属于适用范围。注册一个有类型的 doca_argp 参数；不要改用 getopt。
• “注册新参数时出现 BAD_STATE。”——在更改标志类型之前，先检查 init → register → start 的顺序。

说明

请遵循下方的加载顺序。需要配置 / 注册 / 调试时，打开任务配套文件。需要查看公开参数类型时，打开功能配套文件。不要打开所有配套文件。

从这里开始： 此技能假设 DOCA 已安装，且用户正在对 DOCA 示例或使用 DOCA 的新应用进行实际命令行操作。如果用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文件；如果用户的问题是此版本的 Arg Parser 能表达什么，请打开功能配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户打算用 getopt / argparse / 自定义解析来重写示例的命令行界面，而不是复用 Arg Parser，请先阅读功能配套文件中的关键规则，再进行任何代码更改。

此技能擅长回答的问题示例

此技能旨在回答的 Arg Parser 问题类别，每类都附有一个实际示例。Agent 应将问题类别视为关键内容——实际示例只是其中一个具体情况。

• “如何在不破坏标准命令行界面的情况下，为 DOCA 示例添加新标志？”——实际示例：“为 /opt/mellanox/doca/samples/doca_dma/dma_local_copy/ 添加 --my-flag，确保示例仍以原来的方式接受 --device <PCI> 和 --sdk-log-level <level>”。答案见功能配套文件中的复用 Arg Parser 规则，以及任务配套文件中的先注册后启动工作流。
• “为什么我第二次调用 doca_argp_param_set_* 时会返回 BAD_STATE？”——实际示例：“在 doca_argp_start 已经解析 argv 后注册新参数”。答案见功能配套文件中的生命周期顺序，以及功能配套文件中针对 DOCA_ERROR_BAD_STATE 的错误分类表项。
• “能否通过 JSON 文件运行示例，而不是输入很长的命令行？”——实际示例：“让示例读取 ./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_* 符号的主机端命令行工具”。答案见功能配套文件中的路径选择规则，即 何时使用 doca-argp / 何时不使用 doca-argp 两组要点。

适用对象

此技能面向构建或修改使用 DOCA 的应用的外部开发者——也就是说，他们的代码已经调用 doca_*（直接使用 C/C++，或通过其他语言的 FFI/绑定调用），并且需要使用标准 DOCA CLI 界面，以便生成的二进制文件的操作人员无需重新学习如何调用每个示例。此技能不面向为 Arg Parser 库本身做贡献的 NVIDIA 开发者。

语言范围。 DOCA Arg Parser 以 C 库的形式提供，其 pkg-config 模块名称为 doca-argp。随附的示例使用 C 编写。C 和 C++ 是标准使用场景；配套任务中的操作示例也以此为前提。其他语言的使用者（Rust、Go、Python，……）通过 FFI 或特定语言的绑定使用相同的 *.so；在这种情况下，此技能的作用是确保生命周期、参数类型、JSON 配置、标准标志界面和错误分类方面的指导与语言无关，并引导 Agent 将公共 C ABI 作为权威接口，因为任何封装最终都会调用它。

何时加载此技能

当用户正在使用任何语言实际处理 DOCA Arg Parser 时，加载此技能。具体包括：

• 为已发布的 DOCA 示例或希望采用标准 DOCA CLI 界面的新应用添加、移除或重命名 CLI 标志（--device <PCI>、--representor <name>、--rep-list、--json <path>、--sdk-log-level <level>）。
• 将 doca_argp_init / doca_argp_start / doca_argp_destroy 接入 main()，包括先注册再启动的生命周期以及退出时清理的约定。
• 注册 doca_argp_param（短名称、长名称、值回调、--help 的描述），并从六种公共枚举类型中选择参数类型：string、int、boolean、device、device representor 或 double。JSON 配置文件是这些参数的输入界面，而不是一种参数类型。
• 通过通用的 --json <path> 标志从 JSON 文件读取复杂配置，而不是扩展命令行。
• 在依赖 Arg Parser 之前，确认用户安装中的构建端和运行时 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 专属的实质内容位于两个配套文件中：

• 功能配套文件——说明当前版本的 Arg Parser 能实现什么：参数注册模型、少量公共参数类型、所有示例共用的标准 DOCA CLI 界面、--json <path> 文件集成、先注册再启动的生命周期、Arg Parser 错误分类（映射到跨库的 DOCA_ERROR_* 集合）、可观测性界面（--help 输出和 DOCA Log 通道），以及安全和路径选择策略（何时必须复用 doca-argp，何时应使用语言原生解析器）。
• 任务配套文件——针对六种适用范围内的 Arg Parser 操作（configure、build、modify、run、test、debug）提供分步工作流。此外还包括一个 Deferred task verbs 部分，将范围外的问题指向适当的后续技能。

此技能假设 DOCA 已安装在标准位置的主机或 BlueField 上。不涵盖 DOCA 的安装——相关流程请参阅 doca-setup/SKILL.md。

本技能有意不提供的内容

本技能是Agent 指引，而非示例或模板包。为保持边界清晰，本技能有意不包含以下内容，拉取请求也不应添加：

• 任何语言的预写 DOCA Arg Parser 用法代码。 经验证的 Arg Parser 用法是每个随附 DOCA 示例中的 *_main.c 文件，路径为 /opt/mellanox/doca/samples/<library>/<sample>/。Agent 的任务是引导用户找到该文件，并通过 doca-programming-guide/SKILL.md 中的通用 修改示例工作流，指导用户对其进行最小差异修改， 再结合任务配套文档中针对 Arg Parser 的覆盖规则。
• 独立的构建清单（meson.build、 CMakeLists.txt、Cargo.toml，……），放在技能目录中。 Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-argp 是权威依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录树。 技能目录树中的模拟或不完整产物，即使标注为“参考”，也会造成误导：用户会将其视为可构建内容。

加载顺序

1. 先阅读本技能，确认用户的问题属于适用范围。
2. 有关参数注册模型、参数类型、标准 DOCA CLI 接口、--json <path> 规则、注册后再启动的生命周期、错误分类、可观测性以及路径选择／安全策略，请参阅功能配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

这两个配套文件会相互链接，并链接到 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 会链接到四方匹配规则，并补充 Arg Parser 专属的存在性检查覆盖规则。
• doca-structured-tools-contract/SKILL.md — 此软件包的结构化工具优先级规则（检测／优先使用／回退／报告）。任务配套文档中的 Command 附录遵循此契约。
• doca-programming-guide/SKILL.md — 各库通用的 DOCA 编程模式： 规范的 pkg-config + meson 构建模式、通用的“先修改随附示例”首个应用工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序端调试顺序。本技能在此基础上补充 Arg Parser 专属内容。
• doca-debug/SKILL.md — 跨领域 调试步骤（安装／版本／构建／链接／运行时／程序／驱动）。Arg Parser 专属调试（生命周期违规、已注册参数的类型不匹配、未知 JSON 键）会叠加在这些步骤之上。