/doca-argp

DOCA Arg Parser workflows

Where to start: The verbs run configure → build → modify → run → test → debug. Skip ahead only when the user is already past a verb. Enter ## debug directly from any doca_argp_* error or CLI misbehavior. The ## test verb is an iterative loop (presence / register / --help listing / smoke-parse / JSON-config), not a one-shot pass — see the eval-loop overlay in ## test below.

Read this file when the loader sent you here from SKILL.md. For the param-registration model, the parameter-type set, the standard DOCA CLI surface, the --json <path> (-j <path>) rule (note: the real flag is --json, NOT --json-config — do not invent the longer name), the error taxonomy, observability, and the safety / path-selection policy, see CAPABILITIES.md. For the cross-library DOCA patterns layered under everything below (the canonical pkg-config + meson build pattern, the universal modify-a-shipped-sample workflow, the cross-library DOCA_ERROR_* taxonomy), see doca-programming-guide.

Each verb below describes the shape of the workflow, not a copy-paste recipe. The agent's job is to walk the user through the steps in order, verifying preconditions before recommending the next call.

configure

Goal: confirm doca-argp is installed and usable, pick the shipped-sample *_main.c that already wires the Arg Parser, and plan the register-before-start lifecycle for any new params before any code change.

Steps the agent should walk the user through:

1. Confirm the installed DOCA version and that doca-argp is present. Run pkg-config --exists doca-argp first (presence); if it succeeds, follow with pkg-config --modversion doca-argp (version). Quote the version observed; do not assume "latest". The four-way match rule lives in doca-version CAPABILITIES.md ## Version compatibility; if the observed sources disagree, route there before any Arg-Parser diagnosis. If --exists fails, the user's install profile does not include doca-argp — route to doca-setup TASKS.md ## configure.
2. Locate the canonical reference: any sample's *_main.c. doca-argp ships no dedicated sample tree; the reference is the *_main.c file in every sample under /opt/mellanox/doca/samples/<library>/<sample>/. Pick one whose other-library context already matches the user's intent (e.g. doca_dma/dma_local_copy/dma_local_copy_main.c when the user is modifying a DMA sample's CLI, or applications/dma_copy/ for the reference application — samples/doca_dma/dma_copy/ does not exist as a sample directory in the public DOCA install; the public samples are dma_local_copy, dma_copy_dpu, dma_copy_host) so the surrounding code is familiar.
3. Sketch the lifecycle on paper before writing code. Per the lifecycle table in CAPABILITIES.md ## Capabilities and modes: doca_argp_init is the FIRST doca_argp_* call; every doca_argp_register_param must run BEFORE doca_argp_start; doca_argp_start runs ONCE; doca_argp_destroy runs on every exit path including error paths. Walking this on paper before editing <sample>_main.c is the cheapest way to avoid the DOCA_ERROR_BAD_STATE first-app failure mode.
4. Plan the new params (if any) by type. For each user-added flag, decide its parameter type per the parameter-type table in CAPABILITIES.md ## Capabilities and modes (STRING, INT, BOOLEAN, DEVICE, DEVICE_REP, or DOUBLE). JSON config is a separate input surface, not a seventh type. The type choice drives both argv validation and JSON-config validation; getting it wrong surfaces later as DOCA_ERROR_INVALID_VALUE.
5. Confirm the standard surface is preserved. The sample's existing *_main.c already registers the standard DOCA CLI flags (per the standard-surface table in CAPABILITIES.md ## Capabilities and modes). The user's modification adds rows; it does not replace them. The agent must surface this rule before any code change.

If any step fails with a DOCA_ERROR_*, route through the error taxonomy in CAPABILITIES.md ## Error taxonomy before taking corrective action. Arg Parser errors are deterministic authoring/operator failures; do not retry them unchanged.

build

Goal: compile a doca-argp-using consumer against the user's installed DOCA, with pkg-config as the source of truth for include + link flags.

The build pattern for any DOCA C/C++ consumer is identical across libraries — pkg-config for include + link flags, meson or CMake as the build system — and is fully documented in doca-programming-guide TASKS.md ## build. This skill carries only the Arg-Parser-specific overlay:

For non-C consumers (Rust, Go, Python), the wrapper consumes libdoca_argp.so through FFI; the build-time version visibility goes through the language's own FFI generator (e.g. bindgen against doca_argp.h). The lifecycle and parameter-type rules still apply — the wrapper consumes a *.so that has its own runtime version per doca-version CAPABILITIES.md ## Version compatibility.

modify

Goal: take a shipped DOCA sample's *_main.c as the verified starting point and apply a minimum-diff modification to add / remove / rename a CLI flag without breaking the standard surface.

The universal modify-a-shipped-sample workflow lives in doca-programming-guide TASKS.md ## modify. Use it as-is. The Arg-Parser-specific overlay is the modify-from-sample schema fill — the slots the agent must elicit from the user before recommending any code-level edit:

The agent's anti-pattern alert: a "swap doca-argp for getopt because it'll be simpler" refactor is always a regression on a shipped sample — it breaks the standard CLI surface, drops the --json integration silently, and removes the error-taxonomy ladder in CAPABILITIES.md ## Error taxonomy. Per CAPABILITIES.md ## Safety policy, the agent must refuse this refactor and explain why before producing any diff.

run

Goal: execute the built binary against the user's installed DOCA and confirm both the new flag and the standard surface parse correctly.

Steps the agent should walk the user through:

1. First run: ./<binary> --help. Confirm the operator-side listing shows the standard surface (--device, --representor, --rep-list, --json, --sdk-log-level) AND the user's new flag with the description from ## modify slot 5. If the new flag is missing, registration never happened (likely a missing doca_argp_register_param call); if the standard flags are missing, doca_argp_init was skipped or replaced. Per CAPABILITIES.md ## Observability, --help is the cheapest first signal.
2. Second run: argv smoke. Invoke "$BINARY" --device "$PCI" --my-flag "$VALUE" after assigning each variable from the user's actual value without eval. Confirm the binary parses successfully and reaches its first non-Arg-Parser code path. A parse failure at this stage is one of the DOCA_ERROR_* rows in CAPABILITIES.md ## Error taxonomy.
3. Third run: JSON-config smoke. Author a small ./my-config.json with the user's new flag as a key plus one or two standard-surface keys (e.g. "device": "0000:03:00.0"), then invoke ./<binary> --json ./my-config.json. Confirm the binary parses the same set of values it parsed in step 2. This confirms the JSON-config path covers the new flag, which is the load-bearing reason to reuse doca-argp.
4. Capture the structured log on first failure. Set DOCA_LOG_LEVEL=trace (see doca-debug CAPABILITIES.md ## Observability) when any of the above three runs fails; the trace shows the per-param parse calls and surfaces the --json file read.

For the runtime version + LD_LIBRARY_PATH cross-checks that underlie "the program built but does nothing", see doca-version TASKS.md ## run.

test

Goal: prove a doca-argp-using consumer is correct end-to-end — the new flag works, the standard surface still works, and the JSON-config path covers both — before claiming the "wire doca-argp into this sample" journey is done.

This is a loop, not a one-shot pass. Each iteration narrows either the registration shape, the parameter type, the standard surface coverage, or the JSON-config coverage. The loop terminates when the user reports a --help smoke + an argv smoke + a JSON-config smoke all pass AND the standard-surface flags still behave the same as in a sibling unmodified sample.

Iteration shape:

1. --help listing. Confirm every registered param (standard surface + user-added) appears with its description. Missing rows mean registration never happened; extra rows mean a stale registration was not removed.
2. Argv smoke for the new flag. Pass the new flag with a valid value; confirm the value-callback fires and writes into the user-config struct as expected. Add a one-line log inside the callback per CAPABILITIES.md ## Observability signal 2 if the callback's effect is hard to observe.
3. Argv smoke for the standard surface. Re-run the sample with the standard flags only (--device <PCI> and any sibling-sample-mandatory flag) and confirm the sample's pre-modification behavior is intact. If the standard flags broke after the user's diff, the modification overrode a default registration.
4. JSON-config smoke. Drive the same configuration from --json ./my-config.json; confirm argv-equivalent behavior. An unknown JSON key surfaces as DOCA_ERROR_NOT_SUPPORTED (pedantic parsing) per CAPABILITIES.md ## Error taxonomy — that's a JSON-file typo or a stale config, not a library bug.
5. Cross-version run (if the user has multiple installs): re-run steps 1-4 on each install; quote the version per doca-version TASKS.md ## configure in the report.

Eval-loop overlay — why this is a loop, not a one-shot pass:

Loop termination: an iteration's identity is its trigger-table row plus the captured DOCA_ERROR_*/output. Run the sweep once and permit at most one corrective mutation and rerun. If the second sweep is still non-green, stop regardless of symptom changes and escalate to doca-debug TASKS.md ## debug with the captured --help, argv-smoke, and JSON-config-smoke evidence.

debug

Goal: when a doca_argp_* call returns a DOCA_ERROR_* (or the program's CLI silently misbehaves), narrow the cause to a specific layer before recommending any code change.

The cross-library debug ladder lives in doca-debug TASKS.md ## debug. Walk through it in order — install → version → build → link → runtime → program → driver — before recommending Arg-Parser-specific fixes. This skill's overlay names the Arg-Parser-specific manifestation at layer 6 (program); the library does not own runtime / driver layers because it has no hardware accelerator behind it.

Layer 6 (program) — Arg Parser overlay.

• Lifecycle order is the first hypothesis. Per the lifecycle table in CAPABILITIES.md ## Capabilities and modes, the most common first-app failure is registering a param after doca_argp_start (returns BAD_STATE), or calling _start twice in the same process. Walk the user's *_main.c against the lifecycle before looking elsewhere.
• Type mismatch is the second hypothesis. A flag that registers cleanly but rejects the operator's value with DOCA_ERROR_INVALID_VALUE is a type mismatch between the registered parameter type (per the parameter-type table in CAPABILITIES.md ## Capabilities and modes) and the value the operator wrote. The fix is on the declaration side OR the operator side, not a retry.
• Unknown JSON key is the third hypothesis. DOCA_ERROR_NOT_SUPPORTED from doca_argp_start when --json <path> is in play (pedantic parsing) means the JSON file references a long name no registered param uses. Diff the registered long names against the JSON keys; one side is stale.
• Unreadable JSON file is the fourth hypothesis. DOCA_ERROR_IO_FAILED is an OS-layer problem (missing file, wrong permission, malformed JSON). Resolve via ls -l <path> and cat <path> | jq . before any code change.
• Standard surface override is the fifth hypothesis. If the user's modification broke a standard flag's behavior, the diff re-registered a name doca_argp_init already owns; remove the redundant registration.

Once the layer is identified, route to the matching debug verb on the matching skill: install / build / link to doca-setup ## debug; version to doca-version ## debug; cross-cutting runtime to doca-debug ## debug; program-layer Core-context patterns (in the downstream code the parsed values feed into) to doca-programming-guide TASKS.md ## debug.

Deferred task verbs

The following verbs are out of scope for this skill but are commonly asked in the same conversations. Route them as follows so the agent does not invent guidance:

• install. Installing DOCA, choosing packages, post-install verification, pkg-config wiring — defer to doca-setup and to the install-tree layout in doca-public-knowledge-map ## Layout of an installed DOCA package. This skill assumes DOCA is already installed.
• deploy. Deploying doca-argp-using applications at scale (sample CI, distributing JSON-config files to operators) — out of scope for Phase 1.
• manage / monitor. Per-operator CLI usage analytics or config-file change auditing — outside doca-argp's surface; the library parses, it does not telemeter.
• shell-completion generation. Out of scope; the Arg Parser exposes --help but does not emit bash / zsh completion scripts. Operators wanting completion can layer a language-native completion generator on top.

Command appendix

Every command below is cross-cutting on DOCA Arg Parser — it answers a recurring class of question that comes up in the verbs above. The agent should treat the class as load-bearing; the worked example is a single instance. Run-as user is the unprivileged user unless noted. Sudo is called out per row.

Infra-aware preamble (every row below). Per the bundle's detect → prefer → fall back → report contract documented in doca-structured-tools-contract ## The agent behavior contract, the agent should:

1. Probe for the matching structured helper FIRST (doca-env --json for version + libraries + sample paths in one shot; version-matrix.json for "available since" lookups).
2. If the probe succeeds, the structured tool's output is the authoritative answer and the agent SHOULD NOT also run the manual command in the row below. Report "using structured <tool>".
3. If the probe fails, fall back to the manual command in the row. Report "falling back to manual chain".
4. The schemas the structured tools emit are defined in doca-structured-tools-contract ## Schemas; the version-handling semantics (four-way match, NGC, headers-win) are owned by doca-version.

For commands shared across libraries (pkg-config --modversion, doca_caps, cat /opt/mellanox/doca/applications/VERSION, DOCA_LOG_LEVEL) the cross-library overlay is in doca-debug TASKS.md ## Command appendix; this table adds the Arg-Parser-specific rows on top.