Compile-Time Flag Matrix: Listing of binary stripping and diagnostic compiler switches.

Key Topics & Information

• --strip-docs (-Dno_doc): Strips doc comments and EditorHelp XML strings
• --no-thread-safety (-Dno_thread_safety): Bypasses main-thread runtime guards
• --no-testing (-Dno_testing): Excludes test suites from consumer deliverables
• --no-crash-handler (-Dno_crash_handler): Disables Windows VEH handler for clean radare2 execution
• --leak-tracker (-Dleak_tracker): Tracks object allocations, call sites, and surviving instances
• --profile-dispatches (-Dprofile_dispatches): Records nanosecond virtual method dispatch latency
• --trace-dead-pointers (-Dtrace_dead_pointers): Maintains deallocation callstacks for DisposedObjectError
• --trace-signals (-Dtrace_signals): Intercepts and logs scene tree signal emissions

Producing Ultra-Lean Production Binaries: Stripping docstrings, XML help registries, and test scaffolding.

During release compilation, binary size can be minimized by stripping metadata unnecessary for runtime gameplay:

# Strip docs, XML help, and test scaffolding
lapis build --release --strip-docs --no-testing

• --strip-docs (-Dno_doc): Strips out hundreds of kilobytes of extracted doc comments and XML help structures from src/libgodot/macros.cr and src/libgodot/doc_macro.cr. Automatically enabled in --release.
• --no-testing (-Dno_testing): Omit test runners and benchmark harnesses from consumer games.

High-Throughput Thread-Safety Bypass: Eliminating main-thread assertions for maximum scene graph dispatch speed.

By default, LibGodot guards scene tree mutations (add_child, remove_child) with Godot::ThreadSafety.assert_main_thread!. For battle-tested, single-threaded game loops, these checks can be completely elided at compile time:

lapis build --release --no-thread-safety

When compiled with --no-thread-safety (or -Dfast_dispatch), assert_main_thread! becomes a zero-cost compiler no-op, eliminating thread ID queries and branch predictions on hot loops.

Opt-In Diagnostic Instrumentation: Enabling memory leak tracking, method dispatch profiling, and dead-pointer callstacks.

When debugging complex engine interactions, Lapis provides low-overhead diagnostic modules:

Memory Leak Tracking:

lapis build --leak-tracker

Logs every object allocation with source file and line. At shutdown, inspect surviving objects:

Virtual Method Dispatch Latency Profiling:

lapis build --profile-dispatches

Captures invocation count, average nanoseconds, minimum, and maximum latency for all virtual calls into Crystal.

Dead-Pointer Destruction Callstack History:

lapis build --trace-dead-pointers

Maintains a ring buffer of deallocated instances so any subsequent DisposedObjectError pinpoints where the node was freed.

CLI Switches & Environment Variables: Invoking flags via lapis CLI options or environment variables.

All optimization and diagnostic flags can be specified through CLI switches or environment variables: