Stata C/C++ Plugin Development

Stata C/C++ Plugin Development

Build high-performance C/C++ plugins for Stata. This skill covers the full lifecycle from SDK setup through cross-platform distribution, based on real experience building production Stata plugins for statistical imputation, random forests, string matching, and causal inference.

This skill assumes macOS (Apple Silicon or Intel) as the development platform. Build commands, cross-compilation workflows, and Docker instructions are all Mac-oriented. The plugins themselves target all four platforms (macOS ARM64, macOS x86_64, Linux x86_64, Windows x86_64), but the development environment is macOS. If you need to develop on Linux or Windows natively, adapt the compilation and Docker sections accordingly.

How to Approach Every Task

Before writing any code, enter plan mode. A good plan covers:

1. Complete inventory — every feature, option, and component to build (for translation: exhaustive catalog of the source package's API)
2. Architecture decisions — wrap C++ backend vs. write C from scratch vs. pure Stata
3. Relevant reference files — identify up front which of this skill's reference files contain info you'll need, and cite them explicitly in the plan steps so they get loaded at the right time:
   • references/translation_workflow.md — full translation workflow, test repurposing, fidelity audit
   • references/testing_strategy.md — test layers, reference data generation, Layer 0 (repurpose original tests)
   • references/performance_patterns.md — pthreads, XorShift RNG, quickselect, pre-sorted indices
   • references/packaging_and_help.md — .toc/.pkg/.sthlp templates, build scripts
   • references/cpp_plugins.md — C++ wrapping, extern "C", exception safety, compilation
4. Phase-by-phase steps with dependencies between them
5. For each step: what gets built, what tests get written, and that the review loop runs before proceeding
6. For translation projects: a final fidelity audit as the last step (see translation_workflow.md)

Implement sequentially across components, in parallel within each component. Once an interface is defined, dispatch independent sub-tasks as parallel subagents (e.g., C plugin implementation, .ado wrapper, and test suite can run simultaneously). Merge their work, run the full test suite, then proceed to the review loop before moving to the next component.

Run the review loop after every component:

• Default: dispatch 2-3 review agents in parallel, ideally from different models (e.g., Claude + GPT + Gemini) for diversity of perspective. Use whatever multi-model tools are available in your environment.
• If only one model is available: dispatch 2-3 agents with different review focuses (correctness, completeness, architecture). Different prompts approximate the diversity of different models.
• Each agent reviews the diff, test results, and requirements — instruction: "List any gaps, bugs, or issues. Say LGTM if everything looks correct."
• Fix all issues raised, re-dispatch, loop until all agents say LGTM. Then proceed.

Wrap First, Write From Scratch Second

When translating a package, always check for an existing C/C++ backend before writing any algorithm code. Many R packages have C++ in src/. Many Python packages have Cython or vendored C/C++ libraries. Standalone C++ libraries exist for string matching, linear algebra, tree algorithms, and more.

If a C++ implementation exists, wrap it. Do not reimplement the algorithm in C. Wrapping gives you identical output (same code path), production-grade performance, and a fraction of the code. The plugin is just a thin extern "C" glue layer between Stata's SDK and the library's API. Binary size is irrelevant — statically link everything (-static-libstdc++ -static-libgcc) and ship whatever size the binary turns out to be, even 10-15 MB on Windows. Users don't care about plugin file size; they care about correct results.

See references/cpp_plugins.md for the full pattern and references/translation_workflow.md for the workflow. Working examples of this approach (wrapping C++ backends, multi-plugin dispatching, save/load for scoring on new data) can be found in the repos listed in the project CLAUDE.md under "Example Applications."

For translation projects, also: repurpose the original package's test suite and data (see references/testing_strategy.md Layer 0), write additional Stata-specific tests, and end the plan with a multi-agent fidelity audit. See references/translation_workflow.md for the complete workflow.