headers: split public and private API headers - #436
Open
jow- wants to merge 1 commit into
Open
Conversation
jow-
force-pushed
the
header-reorg
branch
10 times, most recently
from
September 10, 2026 22:46
2a6613a to
e20fd91
Compare
Split the ucode headers into an installed public API and a private
include/ucode/internal/ tree that is never installed, so downstream
codebases no longer pick up implementation details -- in particular the
bare 'unused' macro that clashed with downstream definitions.
Public (installed) headers:
ucode.h umbrella
types.h value types + public value ABI + struct uc_vm
vm.h VM API (ISA moved out)
compiler.h uc_compile() + parse configuration
source.h source creation + line lookup + refcounting
program.h program creation + serialization + refcounting
lib.h stdlib / native-module authoring API
module.h module entry-point contract
util.h failsafe allocators, vectors, lists, ALIGN/ARRAY_SIZE
platform.h system signal table
Private (include/ucode/internal/, not installed):
types.h, vm.h, compiler.h, source.h, program.h, chunk.h, vallist.h,
lexer.h, platform.h, util.h
Key points:
* The bare 'unused'/'localfunc' macros and __hidden are isolated in
internal/util.h; the installed util.h no longer defines them.
* struct uc_vm stays public: downstream (rpcd, uhttpd, uwsd) embeds
uc_vm_t by value and calls uc_vm_init()/uc_vm_free(), so it cannot
be opaque. uc_source_t/uc_program_t/uc_function_t are opaque
forward decls; their full layouts (plus chunk, thread-context,
object-iterator) live in internal/types.h.
* The bytecode ISA (__insns, uc_vm_insn_t, I_* opcodes) moves to
internal/vm.h; compiler state to internal/compiler.h.
* compile.h is merged into compiler.h (the former is removed); the
public compilation API lives in a single header.
* lexer.h moves to internal/ (no downstream users).
* platform.h is split: the public half keeps UC_SYSTEM_SIGNAL_COUNT
and uc_system_signal_names[]; byte-order helpers, execvpe(), pipe2(),
sigtimedwait() and the environ shim move to internal/platform.h.
* UCODE_BYTECODE_VERSION moves to program.h (it describes the
serialized bytecode, not the VM).
* uc_source_get/put and uc_program_get/put become real functions (the
types are now opaque); the __hidden source/program internals move to
internal/source.h and internal/program.h.
* chunk.h and vallist.h move to internal/ (unused downstream).
* lib.h uc_fn_this reads vm->callframes directly (struct uc_vm is
public).
* UC_GC_ENABLED / UC_GC_DEFAULT_INTERVAL introduced; bare GC_* kept as
deprecated aliases.
* Internal headers include their own public counterpart (where one
exists) plus other internal headers; the lexer additionally includes
the public compiler.h for uc_parse_config_t. .c files include the
internal header only. Redundant includes are dropped from every .c
file (verified by compile-testing each removal); conditional
(#ifdef) includes are preserved.
Fixes: #429
Supersedes: #430
Signed-off-by: Jo-Philipp Wich <jo@mein.io>
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
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.
Split the ucode headers into an installed public API and a private include/ucode/internal/ tree that is never installed, so downstream codebases no longer pick up implementation details -- in particular the bare 'unused' macro that clashed with downstream definitions.
Public (installed) headers:
ucode.h umbrella
types.h value types + public value ABI + struct uc_vm
vm.h VM API (ISA moved out)
compiler.h uc_compile() + parse configuration
source.h, program.h, lib.h, module.h, util.h, platform.h
util.h deprecated shim (kept for compatibility)
Private (include/ucode/internal/, not installed):
types.h, vm.h, compiler.h, source.h, program.h, chunk.h, vallist.h,
lexer.h, platform.h, util.h, util-macros.h
Key points:
Fixes: #429
Supersedes: #430