doca-argp

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 TASKS.md (the tasks companion) for configure / register / debug. Open CAPABILITIES.md (the capabilities companion) for the public param types. Do not open every companion file. Load only these two bundled files from the same directory as this skill; if one is missing, stop and report it to the user. For run, test, and debug work, follow the device gate in ## run of TASKS.md before any step that touches hardware.

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 a user-owned copy of /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 smoke steps in the ## run and ## test sections of TASKS.md.
• "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 a user-owned copy of it (copy the sample directory into the user's own workspace as the unprivileged user first, then edit and build only that copy; leave the installed files under /opt/mellanox/doca unchanged) 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

1. Read this skill first to confirm the user's question is in scope.
2. 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 CAPABILITIES.md for these topics.
3. For step-by-step workflows — configure, build, modify, run, test, debug — see the tasks companion TASKS.md for these steps.

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

Load sibling skills only from the same bundle and revision as this skill. If a sibling skill is missing, tell the user and fall back to the installed doca_argp.h header and the shipped sample *_main.c files under /opt/mellanox/doca/samples/. Offer the public Arg Parser documentation only as a reference the user may open, and report any gap rather than filling it in.

• 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. The ## Version compatibility section of CAPABILITIES.md 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.