doca-argp

# DOCA Arg Parser

**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 [`TASKS.md`](TASKS.md) if the user wants
to *do* something (configure / build / modify / run / test /
debug); open [`CAPABILITIES.md`](CAPABILITIES.md) 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`](../../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
[`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
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
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the register-before-start workflow in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **"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
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the error-taxonomy row in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  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
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the JSON-config-file workflow in
  [`TASKS.md ## modify`](TASKS.md#modify) and
  [`TASKS.md ## run`](TASKS.md#run).
- **"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
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the type-mismatch row in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).
- **"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
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility),
  which cross-links the canonical detection chain in
  [`doca-version`](../../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
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  *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 `TASKS.md` 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 wra