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 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 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.** 3. **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.