Document C shims in the C-FFI tutorial#586
Open
SeanTAllen wants to merge 1 commit into
Open
Conversation
✅ Deploy Preview for pony-tutorial ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
ponylang-main
added
the
discuss during sync
jemc
reviewed
Jun 17, 2026
|
|
||
| `cdefine:` is unrelated to ponyc's own `--define`/`-D` flag, which drives Pony's `ifdef`. One sets a C preprocessor macro for your shims; the other selects Pony build flags. | ||
|
|
||
| `use "cinclude:PATH"` adds an include search directory (clang's `-I`). A relative path is resolved against the package's directory. |
Member
There was a problem hiding this comment.
These will need to be updated to match the name change discussed today (cincludedir)
jemc
approved these changes
Jun 17, 2026
jemc
left a comment
jemc
left a comment
Member
There was a problem hiding this comment.
Approved conditional on the name change mentioned
ponylang/ponyc#5469 lets ponyc compile a .c placed next to your .pony files and link it directly, with no separate build system. The tutorial needs to cover it, so this adds a C Shims page. This also reframes the section. We no longer teach how to hand-compile C into a library; the choice is now "link a library or write a shim," with shims framed as glue that bridges Pony to C rather than a way to author C libraries. That retires the old C ABI page, which was mostly a compile-it-yourself walkthrough. A redirect points the old URL at C Shims, and the one piece worth keeping from it, the extern "C" name-mangling note, moves to the linking page. The feature is not in a release yet, so this is a draft: hold the merge until ponyc ships it.
SeanTAllen
force-pushed
the
tutorial-c-shims
branch
from
0813345 to
805934d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the C shims feature from ponylang/ponyc#5469: a
.cfile placed next to a package's.ponyfiles is compiled by ponyc with an embedded clang and linked directly, withcdefine:/cincludedir:use schemes to configure the compile.The change adds a C Shims page and reframes the C-FFI section around two paths: link a library, or write a shim for glue that bridges Pony to C. It retires the old C ABI page (almost entirely a hand-compile-a-library walkthrough), redirects its URL to C Shims, and moves the
extern "C"name-mangling note to the linking page. Shims are framed as helper/bridge code, not a way to write C libraries; for a library's worth of C, the guidance is to build it as a library and link it.Draft / do not merge: the feature isn't in a ponyc release yet. Before un-holding, re-verify against the shipping release:
Compiling C shimsbuild-step label and the exact Windows error string the page quotes--safegates shim compilation, and that acdefine:/cincludedir:in a package with no.cis an error (both are implemented in #5469 but listed as parked items in that PR, so they could still change)