DOCA Arg Parser
Examples
- "Add a custom flag to a DOCA sample." — this is in
scope. Register a typed
doca_argp param; do not drop to
getopt.
- "BAD_STATE registering a new param." — check init →
register → start order before changing the flag type.
Instructions
Follow Loading order below. Open the tasks companion for configure /
register / debug. Open the capabilities companion for the public
param types. Do not open every companion file.
Where to start: This skill assumes DOCA is already installed
and the user is doing hands-on CLI work on a DOCA sample or
new DOCA-using app. Open the tasks companion if the user wants
to do something (configure / build / modify / run / test /
debug); open the capabilities companion when the
question is what can the Arg Parser express on this version. If
the user has not installed DOCA yet, route to
doca-setup/SKILL.md first. If the user is
about to rewrite a sample's CLI with getopt / argparse /
custom parsing instead of reusing the Arg Parser, read the
load-bearing rule in
the capabilities companion
before any code change.
Example questions this skill answers well
The CLASSES of Arg Parser questions this skill is built to
answer, each with one worked example. The agent should treat the
class as the load-bearing piece — the worked example is a
single instance.
- "How do I add a new flag to a DOCA sample without breaking
the standard CLI?" — worked example: "add
--my-flag to
/opt/mellanox/doca/samples/doca_dma/dma_local_copy/ so the
sample still accepts --device <PCI> and --sdk-log-level <level> the same way it did before". Answered by the
reuse-the-Arg-Parser rule in
the capabilities companion
- the register-before-start workflow in
the tasks companion.
- "Why does
doca_argp_param_set_* return BAD_STATE on my
second call?" — worked example: "registering a new param
after doca_argp_start has already parsed argv". Answered by
the lifecycle order in
the capabilities companion
- the error-taxonomy row in
the capabilities companion
for
DOCA_ERROR_BAD_STATE.
- "Can I drive a sample from a JSON file instead of a long
command line?" — worked example: "point a sample at
./my-config.json so the operator does not have to type out
ten flags every time". Answered by the --json <path>
integration in
the capabilities companion
- the JSON-config-file workflow in
the tasks companion and
the tasks companion.
- "My
--my-flag X value is rejected as INVALID_VALUE — why?" —
worked example: "declared the param as int but passed
--my-flag 0x40". Answered by the parameter-type table in
the capabilities companion
- the type-mismatch row in
the capabilities companion.
- "Is
doca-argp even on my installed DOCA?" — worked
example: "a colleague's sample mentions doca-argp but I want
to confirm before I depend on it". Answered by the presence
- version-detection rule in
the capabilities companion,
which cross-links the canonical detection chain in
doca-version/SKILL.md.
- "Should I use doca-argp here, or is this case actually
outside its scope?" — worked example: "writing a host-side
CLI tool that never calls a
doca_* symbol". Answered by the
path-selection rule in
the capabilities companion
Use doca-argp when … / Do not use doca-argp when … bullets.
Audience
This skill serves external developers building or modifying
DOCA-using applications — i.e., users whose code already calls
doca_* (directly in C/C++, or through FFI/bindings from
another language) and who need the standard DOCA CLI surface so
operators of the resulting binary do not have to relearn how to
invoke each sample. It is not for NVIDIA developers
contributing to the Arg Parser library itself.
Language scope. DOCA Arg Parser ships as a C library with
pkg-config module name doca-argp. The shipped samples are
written in C. C and C++ consumers are the canonical case; the
worked examples in the tasks companion assume that path. Other-language
consumers (Rust, Go, Python, …) consume the same *.so through
FFI or language-specific bindings; the skill's contribution in
that case is to keep the lifecycle, parameter-type, JSON-config,
standard-flag-surface, and error-taxonomy guidance
language-neutral, and to route the agent to the public C ABI as
the authoritative surface that any wrapper will eventually call.
When to load this skill
Load this skill when the user is doing hands-on DOCA Arg Parser
work, in any language. Concretely:
- Adding, removing, or renaming a CLI flag on a shipped DOCA
sample or on a new app that wants to share the standard DOCA
CLI surface (
--device <PCI>, --representor <name>,
--rep-list, --json <path>, --sdk-log-level <level>).
- Wiring
doca_argp_init / doca_argp_start /
doca_argp_destroy into a main(), including the
register-before-start lifecycle and the cleanup-on-exit
contract.
- Registering a
doca_argp_param (short name, long name, value
callback, description for --help) with a parameter type
drawn from the six-value public enum: string, int, boolean,
device, device representor, or double. A JSON config file is an
input surface for those parameters, not a parameter type.
- Reading complex configurations from a JSON file via the shared
--json <path> flag instead of expanding the command
line.
- Confirming the build- and runtime-side Arg Parser version on
the user's install (
pkg-config --exists doca-argp,
pkg-config --modversion doca-argp) before depending on it.
- Debugging a
DOCA_ERROR_* returned from a doca_argp_* call
(lifecycle vs. type-mismatch vs. unknown JSON key vs.
unreadable file).
- Designing or extending non-C bindings (Rust, Go, Python, …)
that wrap the Arg Parser C ABI — for the lifecycle,
parameter-type, JSON-config, and standard-flag rules the
wrapper must honor.
Do not load this skill for general DOCA orientation, install
of DOCA itself, or non-Arg-Parser library questions. For those,
use
doca-public-knowledge-map/SKILL.md.
What this skill provides
This is a thin loader. The body keeps only the orientation
needed to pick the right next file. The substantive
Arg-Parser-specific material lives in two companion files:
- the capabilities companion — what the Arg Parser can express on this
version: the param-registration model, the small set of
public parameter types, the standard DOCA CLI surface every
sample shares, the
--json <path> file integration,
the register-before-start lifecycle, the Arg Parser error
taxonomy (mapped onto the cross-library DOCA_ERROR_* set),
the observability surface (the --help output and the
DOCA Log channel), and the safety / path-selection policy
(when reusing doca-argp is mandatory; when a language-native
parser is the right answer).
- the tasks companion — step-by-step workflows for the six in-scope Arg
Parser verbs:
configure, build, modify, run, test,
debug. Plus a Deferred task verbs block that points
out-of-scope questions at the right next skill.
The skill assumes a host or BlueField where DOCA is already
installed at the standard location. It does not cover installing
DOCA — that path goes through
doca-setup/SKILL.md.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:
- Pre-written DOCA Arg Parser usage code, in any language.
The verified Arg Parser usage is the
*_main.c file in every
shipped DOCA sample at
/opt/mellanox/doca/samples/<library>/<sample>/. The agent's
job is to route the user to that file and prescribe a
minimum-diff modification on it via the universal
modify-a-sample workflow in
doca-programming-guide/SKILL.md,
layered with the Arg-Parser-specific overrides in
the tasks companion.
- Standalone build manifests (
meson.build,
CMakeLists.txt, Cargo.toml, …) parked inside the skill.
The agent constructs the build manifest in the user's
project directory against the user's installed DOCA, where
pkg-config --modversion doca-argp is the source of truth.
- A
samples/, bindings/, or reference/ subtree of any
kind. A mock or incomplete artifact in this skill's tree,
even one labeled "reference", is misleading: users will read
it as buildable.
Loading order
- Read this skill first to confirm the user's question is
in scope.
- For the param-registration model, parameter types, the
standard DOCA CLI surface, the
--json <path> rule,
the register-before-start lifecycle, error taxonomy,
observability, and the path-selection / safety policy, see
the capabilities companion.
- For step-by-step workflows — configure, build, modify, run,
test, debug — see the tasks companion.
Both companion files cross-link to each other,
doca-version/SKILL.md for the canonical
version-handling rules, and
doca-public-knowledge-map/SKILL.md
whenever the right answer is "look it up in the public docs or
the installed package layout" rather than "Arg-Parser-specific
guidance".
Related skills
doca-public-knowledge-map/SKILL.md —
the routing table for every public DOCA documentation source
and the on-disk layout of an installed DOCA package. The Arg
Parser URL is
https://docs.nvidia.com/doca/sdk/DOCA-Arg-Parser/index.html;
the canonical on-disk usage example is any sample's
*_main.c under /opt/mellanox/doca/samples/.
doca-setup/SKILL.md — env preparation,
install verification, and the I have no install yet path
with the public NGC DOCA container. This skill assumes its
preconditions are satisfied.
doca-version/SKILL.md — canonical
DOCA version-handling rules. This skill's ## Version compatibility cross-links the four-way match rule and adds
the Arg-Parser-specific presence-check overlay.
doca-structured-tools-contract/SKILL.md —
the bundle's structured-tools precedence rule (detect / prefer
/ fall back / report). The Command appendix in
the tasks companion honors this contract.
doca-programming-guide/SKILL.md —
general DOCA programming patterns shared by every library:
the canonical pkg-config + meson build pattern, the
universal modify-a-shipped-sample first-app workflow, the
universal lifecycle, the cross-library DOCA_ERROR_*
taxonomy, and the program-side debug order. This skill layers
Arg-Parser specifics on top.
doca-debug/SKILL.md — the cross-cutting
debug ladder (install / version / build / link / runtime /
program / driver). Arg-Parser-specific debug (lifecycle
violations, type-mismatch on a registered param, unknown JSON
key) overlays on top of that ladder.
1---2license: Apache-2.03name: doca-argp4description: >5 Use this skill for hands-on DOCA Arg Parser CLI work on a shipped6 sample or new DOCA-using app — adding / removing / renaming flags;7 wiring `doca_argp_init` → register params → `doca_argp_start` →8 `doca_argp_destroy` in order; picking a parameter type from the full9 public enum (`DOCA_ARGP_TYPE_STRING`, `_INT`, `_BOOLEAN`, `_DEVICE`,10 `_DEVICE_REP`, `_DOUBLE` — six values, not three); preserving the11 built-in DOCA flags (`-h` `-v` `-l` `--sdk-log-level` `--log-filter`12 `-j`/`--json`, NOT `--json-config`); `--device` is per-program; or13 debugging `DOCA_ERROR_BAD_STATE` / `INVALID_VALUE` / `NOT_SUPPORTED` /14 `IO_FAILED` from `doca_argp_*`. Trigger on implicit phrasings: "add a15 custom flag to a DOCA sample", "should I use getopt here", "BAD_STATE16 registering a new param", "my JSON config key is rejected", or "my17 sample's --json is ignored". Refuse and route elsewhere for18 variadic-flag / subcommand / shell-completion features, DOCA Core19 context, or DOCA Log internals.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-argp22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: library24 doca_version: "3.5"25 tags:26 - doca27 - argp28 - cli29compatibility: >30 Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu31 22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC32 attached. Reads the user's local install via `pkg-config doca-argp`33 and inspects /opt/mellanox/doca/{lib,include,samples,applications}.34 The validation steps require a live DOCA install.35---3637# DOCA Arg Parser3839## Examples4041- **"Add a custom flag to a DOCA sample."** — this is in42 scope. Register a typed `doca_argp` param; do not drop to43 getopt.44- **"BAD_STATE registering a new param."** — check init →45 register → start order before changing the flag type.4647## Instructions4849Follow Loading order below. Open the tasks companion for configure /50register / debug. Open the capabilities companion for the public51param types. Do not open every companion file.5253**Where to start:** This skill assumes DOCA is already installed54and the user is doing **hands-on CLI work** on a DOCA sample or55new DOCA-using app. Open the tasks companion if the user wants56to *do* something (configure / build / modify / run / test /57debug); open the capabilities companion when the58question is *what can the Arg Parser express* on this version. If59the user has not installed DOCA yet, route to60`doca-setup/SKILL.md` first. If the user is61about to rewrite a sample's CLI with `getopt` / `argparse` /62custom parsing instead of reusing the Arg Parser, read the63load-bearing rule in64the capabilities companion65before any code change.6667## Example questions this skill answers well6869The CLASSES of Arg Parser questions this skill is built to70answer, each with one worked example. The agent should treat the71*class* as the load-bearing piece — the worked example is a72single instance.7374- **"How do I add a new flag to a DOCA sample without breaking75 the standard CLI?"** — worked example: *"add `--my-flag` to76 `/opt/mellanox/doca/samples/doca_dma/dma_local_copy/` so the77 sample still accepts `--device <PCI>` and `--sdk-log-level78 <level>` the same way it did before"*. Answered by the79 reuse-the-Arg-Parser rule in80 the capabilities companion81 + the register-before-start workflow in82 the tasks companion.83- **"Why does `doca_argp_param_set_*` return `BAD_STATE` on my84 second call?"** — worked example: *"registering a new param85 after `doca_argp_start` has already parsed argv"*. Answered by86 the lifecycle order in87 the capabilities companion88 + the error-taxonomy row in89 the capabilities companion90 for `DOCA_ERROR_BAD_STATE`.91- **"Can I drive a sample from a JSON file instead of a long92 command line?"** — worked example: *"point a sample at93 `./my-config.json` so the operator does not have to type out94 ten flags every time"*. Answered by the `--json <path>`95 integration in96 the capabilities companion97 + the JSON-config-file workflow in98 the tasks companion and99 the tasks companion.100- **"My `--my-flag X` value is rejected as `INVALID_VALUE` — why?"** —101 worked example: *"declared the param as `int` but passed102 `--my-flag 0x40`"*. Answered by the parameter-type table in103 the capabilities companion104 + the type-mismatch row in105 the capabilities companion.106- **"Is `doca-argp` even on my installed DOCA?"** — worked107 example: *"a colleague's sample mentions doca-argp but I want108 to confirm before I depend on it"*. Answered by the presence109 + version-detection rule in110 the capabilities companion,111 which cross-links the canonical detection chain in112 `doca-version/SKILL.md`.113- **"Should I use doca-argp here, or is this case actually114 outside its scope?"** — worked example: *"writing a host-side115 CLI tool that never calls a `doca_*` symbol"*. Answered by the116 path-selection rule in117 the capabilities companion118 *Use doca-argp when … / Do not use doca-argp when …* bullets.119120## Audience121122This skill serves **external developers building or modifying123DOCA-using applications** — i.e., users whose code already calls124`doca_*` (directly in C/C++, or through FFI/bindings from125another language) and who need the standard DOCA CLI surface so126operators of the resulting binary do not have to relearn how to127invoke each sample. It is *not* for NVIDIA developers128contributing to the Arg Parser library itself.129130**Language scope.** DOCA Arg Parser ships as a C library with131`pkg-config` module name `doca-argp`. The shipped samples are132written in C. C and C++ consumers are the canonical case; the133worked examples in the tasks companion assume that path. Other-language134consumers (Rust, Go, Python, …) consume the same `*.so` through135FFI or language-specific bindings; the skill's contribution in136that case is to keep the lifecycle, parameter-type, JSON-config,137standard-flag-surface, and error-taxonomy guidance138language-neutral, and to route the agent to the public C ABI as139the authoritative surface that any wrapper will eventually call.140141## When to load this skill142143Load this skill when the user is doing hands-on DOCA Arg Parser144work, in any language. Concretely:145146- Adding, removing, or renaming a CLI flag on a shipped DOCA147 sample or on a new app that wants to share the standard DOCA148 CLI surface (`--device <PCI>`, `--representor <name>`,149 `--rep-list`, `--json <path>`, `--sdk-log-level150 <level>`).151- Wiring `doca_argp_init` / `doca_argp_start` /152 `doca_argp_destroy` into a `main()`, including the153 register-before-start lifecycle and the cleanup-on-exit154 contract.155- Registering a `doca_argp_param` (short name, long name, value156 callback, description for `--help`) with a parameter type157 drawn from the six-value public enum: string, int, boolean,158 device, device representor, or double. A JSON config file is an159 input surface for those parameters, not a parameter type.160- Reading complex configurations from a JSON file via the shared161 `--json <path>` flag instead of expanding the command162 line.163- Confirming the build- and runtime-side Arg Parser version on164 the user's install (`pkg-config --exists doca-argp`,165 `pkg-config --modversion doca-argp`) before depending on it.166- Debugging a `DOCA_ERROR_*` returned from a `doca_argp_*` call167 (lifecycle vs. type-mismatch vs. unknown JSON key vs.168 unreadable file).169- Designing or extending non-C bindings (Rust, Go, Python, …)170 that wrap the Arg Parser C ABI — for the lifecycle,171 parameter-type, JSON-config, and standard-flag rules the172 wrapper must honor.173174Do **not** load this skill for general DOCA orientation, install175of DOCA itself, or non-Arg-Parser library questions. For those,176use177`doca-public-knowledge-map/SKILL.md`.178179## What this skill provides180181This is a **thin loader**. The body keeps only the orientation182needed to pick the right next file. The substantive183Arg-Parser-specific material lives in two companion files:184185- the capabilities companion — what the Arg Parser can express on this186 version: the param-registration model, the small set of187 public parameter types, the standard DOCA CLI surface every188 sample shares, the `--json <path>` file integration,189 the register-before-start lifecycle, the Arg Parser error190 taxonomy (mapped onto the cross-library `DOCA_ERROR_*` set),191 the observability surface (the `--help` output and the192 DOCA Log channel), and the safety / path-selection policy193 (when reusing doca-argp is mandatory; when a language-native194 parser is the right answer).195- the tasks companion — step-by-step workflows for the six in-scope Arg196 Parser verbs: `configure`, `build`, `modify`, `run`, `test`,197 `debug`. Plus a `Deferred task verbs` block that points198 out-of-scope questions at the right next skill.199200The skill assumes a host or BlueField where DOCA is already201installed at the standard location. It does not cover installing202DOCA — that path goes through203`doca-setup/SKILL.md`.204205## What this skill deliberately does not ship206207This skill is **agent guidance**, not a samples or templates208bundle. To keep the boundary clean, it deliberately does not209contain — and pull requests should not add:210211- **Pre-written DOCA Arg Parser usage code, in any language.**212 The verified Arg Parser usage is the `*_main.c` file in every213 shipped DOCA sample at214 `/opt/mellanox/doca/samples/<library>/<sample>/`. The agent's215 job is to route the user to that file and prescribe a216 minimum-diff modification on it via the universal217 modify-a-sample workflow in218 `doca-programming-guide/SKILL.md`,219 layered with the Arg-Parser-specific overrides in220 the tasks companion.221- **Standalone build manifests** (`meson.build`,222 `CMakeLists.txt`, `Cargo.toml`, …) parked inside the skill.223 The agent constructs the build manifest *in the user's224 project directory* against the user's installed DOCA, where225 `pkg-config --modversion doca-argp` is the source of truth.226- **A `samples/`, `bindings/`, or `reference/` subtree** of any227 kind. A mock or incomplete artifact in this skill's tree,228 even one labeled "reference", is misleading: users will read229 it as buildable.230231## Loading order2322331. Read this skill first to confirm the user's question is234 in scope.2352. **For the param-registration model, parameter types, the236 standard DOCA CLI surface, the `--json <path>` rule,237 the register-before-start lifecycle, error taxonomy,238 observability, and the path-selection / safety policy, see239 the capabilities companion.**2403. **For step-by-step workflows — configure, build, modify, run,241 test, debug — see the tasks companion.**242243Both companion files cross-link to each other,244`doca-version/SKILL.md` for the canonical245version-handling rules, and246`doca-public-knowledge-map/SKILL.md`247whenever the right answer is "look it up in the public docs or248the installed package layout" rather than "Arg-Parser-specific249guidance".250251## Related skills252253- `doca-public-knowledge-map/SKILL.md` —254 the routing table for every public DOCA documentation source255 and the on-disk layout of an installed DOCA package. The Arg256 Parser URL is257 `https://docs.nvidia.com/doca/sdk/DOCA-Arg-Parser/index.html`;258 the canonical on-disk usage example is any sample's259 `*_main.c` under `/opt/mellanox/doca/samples/`.260- `doca-setup/SKILL.md` — env preparation,261 install verification, and the *I have no install yet* path262 with the public NGC DOCA container. This skill assumes its263 preconditions are satisfied.264- `doca-version/SKILL.md` — canonical265 DOCA version-handling rules. This skill's `## Version266 compatibility` cross-links the four-way match rule and adds267 the Arg-Parser-specific presence-check overlay.268- `doca-structured-tools-contract/SKILL.md` —269 the bundle's structured-tools precedence rule (detect / prefer270 / fall back / report). The Command appendix in271 the tasks companion honors this contract.272- `doca-programming-guide/SKILL.md` —273 general DOCA programming patterns shared by every library:274 the canonical `pkg-config` + meson build pattern, the275 universal modify-a-shipped-sample first-app workflow, the276 universal lifecycle, the cross-library `DOCA_ERROR_*`277 taxonomy, and the program-side debug order. This skill layers278 Arg-Parser specifics on top.279- `doca-debug/SKILL.md` — the cross-cutting280 debug ladder (install / version / build / link / runtime /281 program / driver). Arg-Parser-specific debug (lifecycle282 violations, type-mismatch on a registered param, unknown JSON283 key) overlays on top of that ladder.