Builtins (v0.2.1)
Compiler-provided functions, low-level memory and ABI operations, and builtin types for type, target, host, and compile-time work.
Overview
Builtins are compiler-provided functions and reserved operations. Some return information about types, some return information about the target or host, and some help validate assumptions while compiling.
They are often used in constants and static checks. For example, sizeOf(u32) can define a constant, staticAssert can stop compilation if an assumption is wrong, and target builtins can select one branch over another before code generation.
Use builtins when the value belongs to the compiler, the ABI, the target machine, or low-level memory operations rather than to ordinary runtime program state.
Primary source: syntax/builtins/README.md
Syntax Signatures
const SIZE: usize = sizeOf(u32);
const ALIGN: u32 = alignOf(u32);
fn verifyTypes() void {
staticAssert(isSameType(u32, u32), "type mismatch");
}Behavior and Use
Compile-time builtins are evaluated while the compiler processes the program, and memory and ABI builtins lower directly to low-level memory operations, ABI queries, or compiler-managed variadic argument access.
When staticAssert or compileError fails, compilation stops immediately. Warnings produced by compileWarning continue compilation but still affect diagnostics output.
Best Practices
- Use staticAssert for layout and target assumptions.
- Store builtin results in named constants when they are reused.
- Prefer the highest-level builtin that states your intent clearly, then drop to memory and ABI builtins only when you really need raw memory behavior or ABI-level access.
- Write staticAssert messages that clearly say what failed.
Type Layout Builtins
These builtins describe the size and layout of a type as the compiler sees it.
sizeOf(Type)- returns the size of a type in bytes as usize.alignOf(Type)- returns the memory alignment of a type as u32.typeWidth(Type)- returns the bit width of a type as usize.fieldCount(Type)- returns the number of fields in a struct type as usize.
Type Information Builtins
These builtins answer structural questions about types.
fixedArraySize(Type)- returns the element count of a fixed-size array type as usize.isSameType(A, B)- returns true when both types are exactly the same.isPtrLike(Type)- returns true when the type is a pointer or another pointer-like type.isFixedArrayOfSize(Type, N)- returns true when the type is a fixed array with exactly N elements.
Source Location Builtins
These builtins expose the source position currently being compiled.
file()- returns the current source file as a constant string.fileLine()- returns the current source line as u32.currentFuncName()- returns the current function name as a constant string.
Compile-Time Check Builtins
These builtins validate assumptions or emit diagnostics during compilation.
staticAssert(condition, "message")- stops compilation when the constant condition is false.compileError("message")- always stops compilation with the given error message.compileWarning("message")- emits a compile-time warning with the given message.
Compiler Information Builtins
These builtins report facts about the compiler itself.
compilerVersion()- returns the compiler version as a constant string.debugBuild()- returns true when the compiler itself is a debug build.
String Builtins
These builtins operate on constant strings known to the compiler.
stringLength(string)- returns the length of a constant string as usize.
Type Predicate Builtins
These builtins return booleans about general type categories.
isSigned(Type)- returns true when the type is a signed integer type.isUnsigned(Type)- returns true when the type is an unsigned integer type.isInteger(Type)- returns true when the type is any integer type.isFloat(Type)- returns true when the type is a floating-point type.isBool(Type)- returns true when the type is bool.isChar(Type)- returns true when the type is char.isPointer(Type)- returns true when the type is a pointer.isArray(Type)- returns true when the type is an array form.isFixedArray(Type)- returns true when the type is a fixed-size array.isStruct(Type)- returns true when the type is a struct type.isVoid(Type)- returns true when the type is void.isConst(Type)- returns true when the type has const qualification.isNumeric(Type)- returns true when the type is numeric.isFunction(Type)- returns true when the type is a function reference type.
Target Information Builtins
These builtins report what kind of machine and ABI the compiler is targeting.
targetOS()- returns the target operating system name as a constant string.targetArch()- returns the target architecture name as a constant string.targetVendor()- returns the target vendor name as a constant string.targetAbi()- returns the target ABI name as a constant string.targetTriple()- returns the full target triple as a constant string.isLinux()- returns true when the target OS is Linux.isWindows()- returns true when the target OS is Windows.isDarwin()- returns true when the target OS is Darwin-based.isApple()- returns true when the target vendor or platform is Apple-related.isAix()- returns true when the target OS is AIX.is64Bit()- returns true when the target pointer width is 64 bits.is32Bit()- returns true when the target pointer width is 32 bits.isBigEndian()- returns true when the target byte order is big-endian.isLittleEndian()- returns true when the target byte order is little-endian.isX86()- returns true when the target architecture is x86.isX8664()- returns true when the target architecture is x86_64.isArm()- returns true when the target architecture is ARM.isAarch64()- returns true when the target architecture is AArch64.isRiscv64()- returns true when the target architecture is RISC-V 64-bit.isPpc()- returns true when the target architecture is PowerPC.isPpc64()- returns true when the target architecture is PowerPC 64-bit.isMips64()- returns true when the target architecture is MIPS64.isSystemz()- returns true when the target architecture is IBM System z.isLoongarch64()- returns true when the target architecture is LoongArch64.isWasm()- returns true when the target architecture is WebAssembly.isElf()- returns true when the target object format is ELF.isMachO()- returns true when the target object format is Mach-O.isCoff()- returns true when the target object format is COFF.hasPosixThreads()- returns true when the target environment supports POSIX threads.hasSysvAbi()- returns true when the target follows the System V ABI family.pointerWidth()- returns the target ptr width in bits as usize.isizeWidth()- returns the target ssize width in bits as usize.usizeWidth()- returns the target usize width in bits as usize.pointerAlign()- returns the pointer alignment in bytes as usize.maxAlignment()- returns the maximum supported alignment in bytes as usize.targetCPU()- returns the target CPU name as a constant string.targetCpuFeatures()- returns the enabled target CPU features as a constant string.hasFeature("name")- returns true when the target CPU supports the named feature.
Host Information Builtins
These builtins report facts about the machine running the compiler, not the machine being targeted.
hostOsName()- returns the host operating system name as a constant string.hostArch()- returns the host architecture name as a constant string.hostEndian()- returns the host endianness as a constant string.currentTimestamp()- returns the current host timestamp as usize.
Memory and ABI Builtins
These builtins lower directly to low-level memory operations, ABI queries, or variadic argument access.
halloc(Type)- allocates heap memory for one value of the given type and returns ptr[Type].memcpy(dst, src, size)- copies a block of memory and returns ptr.memmove(dst, src, size)- moves a block of memory safely for overlapping ranges and returns ptr.memset(dst, value, size)- fills a memory block with a byte value and returns ptr.abiSizeOf(Type)- returns the ABI-defined size of a type in bytes as u64.bitSizeOf(Type)- returns the size of a type in bits as u64.abiAlignOf(Type)- returns the ABI-defined alignment of a type as u32.arbitraryArgs()- returns the current variadic argument list as ptr.arbitraryArg(Type)- reads one variadic argument of the given type.
Builtin Type
The language also exposes one builtin alias that appears in many APIs.
CString- builtin alias for array[char], used for null-terminated string values.
Using Builtins in Declarations
Builtins are most useful when they keep declarations tied to target facts.
- Use sizeOf and alignOf to define capacities or layout checks that follow the referenced type.
- Use target builtins to select platform-specific constants and imports through compile-time conditionals.
- Use compileError and compileWarning for explicit diagnostics when a configuration is unsupported or unusual.
Example
const PTR_BITS: usize = pointerWidth();
fn verify() void @public {
staticAssert(PTR_BITS == 64 or PTR_BITS == 32, "unsupported pointer width");
}