RFC: Custom symbol export names for FFI, plugins, and embedding

[nglmercer]

Problem

Perry currently generates all LLVM symbol names automatically using the pattern perry_fn_<module_prefix>__<function_name>. There is no mechanism for TypeScript code to control the exported symbol name.

This limitation affects multiple use cases beyond plugins:

Use Case	What is Needed
Plugins (perry/plugin)	Export plugin_activate, plugin_deactivate, perry_plugin_abi_version with exact names
C/C++ FFI	Export functions that C can call by a known name
WASM	Human-readable export names instead of __wasm_func_<idx>
Embedding	Other languages need to find functions by name via dlsym or equivalent
Dynamic loading	Any scenario requiring runtime symbol lookup

Concrete Example: Plugin System Gap

The documentation (docs/src/plugins/creating-plugins.md) states:

Perry automatically:

• Generates perry_plugin_abi_version() returning the current ABI version
• Generates plugin_activate(api_handle) calling your activate() function
• Generates plugin_deactivate() calling your deactivate() function

However, the codegen does not emit these symbols. What actually gets exported:

# From nm -D theme.dylib
perry_module_init
perry_fn_theme_plugin_dylib_ts__activate      # wrong name
perry_fn_theme_plugin_dylib_ts__deactivate    # wrong name
__perry_wrap_perry_fn_theme_plugin_dylib_ts__activate

What the runtime expects (crates/perry-runtime/src/plugin.rs:507-528):

let activate_sym = CString::new("plugin_activate").unwrap();
let activate_ptr = libc::dlsym(handle, activate_sym.as_ptr());
if activate_ptr.is_null() {
    eprintln!("[plugin] No plugin_activate symbol in {}", path_str);
    return 0;  // Plugin fails to load
}

Root Cause

The codegen in crates/perry-codegen/src/codegen/entry.rs only emits perry_module_init for dylib output (line 133). There is no mechanism to:

1. Detect that the module exports activate/deactivate functions
2. Generate wrapper functions with specific symbol names
3. Allow users to control symbol names in general

The scoped_fn_name helper (crates/perry-codegen/src/codegen/helpers.rs:111-112) hardcodes the naming pattern:

pub(super) fn scoped_fn_name(module_prefix: &str, hir_name: &str) -> String {
    format!("perry_fn_{}__{}", module_prefix, sanitize(hir_name))
}

Questions

Before proposing a solution, I would like feedback on:

1. Is this a recognized gap? The documentation promises auto-generated plugin symbols, but they are not implemented.

2. What should the general capability be? This is not just a plugin problem -- it is a general FFI/embedding limitation. Should Perry provide a way to control exported symbol names?

3. What approach fits Perry's design? Some options:

   • TypeScript decorator (e.g. @exportName("symbol_name"))
   • Manifest configuration (e.g. perry.toml export map)
   • Compiler directive or special comment
   • Something else entirely

4. Should plugin-specific wrappers be auto-generated (as documented) or explicit (user-controlled via the general mechanism)?

Context

I am working on a plugin system for a text editor and encountered this gap. I implemented a working runtime plugin system using QuickJS (rquickjs) as a workaround, but compiled plugins would be preferable for type safety and performance.

Impact

Without this capability:

• The documented plugin system does not work on any platform
• Users cannot create FFI boundaries with custom symbol names
• WASM exports remain index-based (__wasm_func_<idx>)
• Embedding Perry-compiled code requires knowing the mangled symbol names

With this capability:

• Plugin system works as documented
• General FFI/embedding use cases are enabled
• WASM can have readable export names
• Users have full control over their binary interface

[proggeramlug]

Sorry for taking so long to get back to you on this. That wasn't fair to a writeup this careful.

You're right on the facts. The line references made it quick to check. Let me split the two things you raised, because they have different answers.

First, the plugin symbol gap. This is a real bug, and I'm going to treat it as one. The runtime in crates/perry-runtime/src/plugin.rs:507-605 looks up perry_plugin_abi_version, plugin_activate, and plugin_deactivate via dlsym. The docs in docs/src/plugins/creating-plugins.md:21-24 say the compiler generates exactly those. But nothing in crates/perry-codegen emits them. So the documented plugin path can't load a plugin on any platform. That's a broken contract between the runtime, the docs, and codegen, not a feature request. The fix is small: emit the three wrappers for a dylib that exports activate/deactivate, mirroring how entry.rs already emits perry_module_init, and reusing the _perry_wrap* wrapper machinery your nm output shows we already have. At a minimum I'll correct the docs so they stop promising something that isn't there.

Second, the general "control any exported symbol name" capability. That part I'm deferring for now, which is what I meant the closure to signal even though I didn't say it. It's a real ABI surface and I don't want to commit to it until there's a concrete use case beyond plugins. The concerns are specific: once user code dlsyms a custom name we've promised that name forever and can't remangle, we'd need a collision rule against js_* and perry_* symbols, and the plugin/C FFI/WASM cases in your table don't actually share an implementation. If we do build it, I'd want one mechanism, probably an @exportName("...") decorator at the declaration, and I'd rebuild the plugin wrappers on top of it rather than keep two systems.

Short version: plugin wrappers are a bug I'll fix or track, the general symbol export is a deferred RFC I'll revisit when a second use case shows up. Thanks again for the report, and for the QuickJS context.

[proggeramlug]

Filed the narrow plugin codegen bug as #5273. Keeping this issue closed as the deferred general symbol-export RFC; the actionable plugin-wrapper fix lives there.