Rtinycc — Copilot Instructions

This file is the minimum guidance for agentic work on Rtinycc. Read relevant code before changes, keep edits small and focused, and update tests/docs when you change behavior. Agents must read actual implementations before guessing. If you need third-party code or headers, check the .sync directory for local copies of libraries we depend on so you can read them directly instead of assuming behavior. We also generate <package>.llm.txt files for R package docs; for example, treesitter.c docs can be found in treesitter.c.llm.txt. The .sync directory also contains reference implementations that inform the tcc_quick compiler design: codetools (walker/handler), quickr (handler registry, scope tracking), spy (typed C AST, codegen), and Stdlib (the SaC standard library from the SacBase project — array primitives, reductions, transforms, and with-loop patterns that inform our condensation/ψ-reduction architecture).

Rtinycc embeds TinyCC and exposes both CLI and libtcc APIs to R. It provides a Bun-style FFI that generates SEXP wrappers at runtime, compiles them with TinyCC, and calls them via .Call.

tcc_get_symbol() calls RC_libtcc_get_symbol(), which converts the raw void* from TinyCC into a DL_FUNC and wraps it with R_MakeExternalPtrFn (tagged as a native symbol). make_callable() then passes that external pointer to .RtinyccCall (which is base::.Call). There is no Rf_install cast of the function pointer; Rf_install only sets the native symbol tag.

Scalar types: i8, i16, i32, i64, f32, f64, bool, cstring. Array arguments (zero-copy): raw, integer_array, numeric_array, logical_array, character_array. Array returns: returns = list(type = "*_array", length_arg = <index>, free = TRUE) copies into a new R vector and optionally frees the C buffer. Struct array fields: list(type = "u8", size = N, array = TRUE) generates element accessors struct_<name>_get_<field>_elt() / struct_<name>_set_<field>_elt(). Pointers: ptr and sexp are exposed as external pointers; ownership is tracked and enforced in RC_free and tcc_ptr_is_owned().