This is a complete invocation. With no -A, xcc builds a native executable for
the machine it is running on, finds the standard library relative to its own
binary, and optimises at -O3. A simple program needs nothing else.
Output file. On a native target this is a runnable executable unless the path ends in .s (assembly) or .o (object). On 6502 and m68k the extension picks the container (see below).
-c
Compile and assemble to a relocatable object (.o), but do not link.
-a, --assemble-only
Stop after producing assembly; don’t assemble or link.
-E <path>, --preprocessed <path>
Write the preprocessed source to <path> and continue. Shows what the lexer sees.
-I <path>, --include <path>
Add an include-search path. Repeatable.
-D <name>[=<value>]
Define a preprocessor symbol. -DDEBUG is #define DEBUG 1; -DLEVEL=3 defines it as 3.
-q, --quiet
Suppress informational output. Errors and warnings still print.
-V, --verbose
Print the resolved support root and every include path at startup. First stop when Cannot find include file fires.
These apply when xcc produces a native executable or library. By default it
assembles, links and (on macOS) signs in-house, with no system assembler,
linker or clang.
Flag
Effect
-l<name>
Link a system library, forwarded to the linker, for example -lobjc.
-framework <F>
Link a macOS framework, for example -framework AppKit.
-Xlinker <arg>, -Wl,<arg>
Pass an argument to the linker. $XTC_LDFLAGS is also appended.
--self-host
In-house assemble + link + sign. This is the default; the flag is accepted but has no effect.
--no-self-host
Use the clang link path instead.
-fpic, -fPIC, -mpic
Position-independent code. Implied by --emit-lib; on arm9 it is what produces an ET_DYN.so rather than a fixed-load ELF.
Emit a shared library instead of an executable, together with a sibling .xtc.iface describing the classes, protocols, structs and enums it exports. Implies -fpic.
-L <path>, --library-path <path>
Add a search path for #import <Lib>, which resolves to lib<Lib>.so and reads its interface (or, for a C library, its DWARF). Repeatable.
Terminal window
xcc--emit-lib-olibXtg.soxtg.xc# build the library
xcc-L.-oappapp.xc# build a client against it
#import <Lib> type-checks the client against the actual binary, so there is no
header to fall out of sync. It also works on a plain C.so, whose DWARF
supplies its functions, types and enum constants. See
Modules & shared libraries.
Root holding the support tree. Rarely needed, because xcc finds it relative to its own binary. See Install.
-m <layout>, --memory-model <layout>
Load a memory layout (.lnk). Searches <layout> as a path (appending .lnk), then the built-in layout directories. -m xt is the banked 6502 map and implies -A 6502. There is no default: with neither -m nor -A, xcc targets the host.
-ll, --list-layouts
List every built-in layout, grouped by platform, and exit.
-dl, --dump-layout
Print the active layout’s memory-map diagram and exit. Use with -m.
-dp, --dump-placement
After codegen, print every function’s final placement (main / banked page N / irq / vbi) with per-bank byte usage.
-du, --dump-usage
After codegen, print a per-segment usage summary for every region and bank in the layout.
No optimisation. A debug aid; the production level is -O3.
-O, -O1
Peephole + register tracking.
-O2
Adds const propagation, dead code / dead store elimination, tail-call optimisation, leaf-function inlining, loop unrolling for small trip counts.
-O3
The default. Adds branch inversion and threading, strength reduction, cross-function dead-code elimination, label cleanup, and on arm64 the NEON auto-vectoriser.
-Fli <n>, --fn-leaf-inline <n>
Max leaf-function size (instructions) eligible for inlining. Default 100; needs -O2+.
-Flu <n>, --fn-loop-unroll <n>
Auto-unroll counted for loops with trip count ≤ n. Default 5 at -O2+, 0 below.
-Fmb <n>, --fn-min-banked <n>
Minimum function size (6502 instructions) to be banked. Smaller functions stay in main RAM so their call sites skip the _xcall trampoline. Default 0 (off).
Coalescing free-list allocator; supports delete. Default on targets with a dedicated heap region: the xt layouts and the native hosts.
-farc[=on|off]
Automatic reference counting. on (default) emits retains and releases and rejects manual retain / release; off disables auto-emit and accepts manual lifecycle.
-fthread-safe-arc
Force atomic ARC refcounts, so two threads can share an object.
-fno-thread-safe-arc
Force plain, non-atomic refcounts.
Atomic refcounts are decided per module and switch on when the module spawns a
thread. These flags override that choice. See
Allocator & ARC and
Threading.
Compile as if the standard library were still <base>: methods annotated since("V") with V newer than <base> are removed from lookup, so a call whose meaning changed between the versions is an error instead of resolving to the new method. Use it when a library you depend on has renamed or repurposed a method between its versions.