Builtins (v0.2.2)
Compiler-provided functions, low-level memory and ABI operations, and builtin types for type, target, host, and compile-time work.
Latest
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.
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.isUnix()- returns true when the target is a Unix-like platform (Linux, Darwin, BSD, Solaris/Illumos, AIX, or Haiku).isBSD()- returns true when the target OS is a BSD derivative.isFreeBSD()- returns true when the target OS is FreeBSD.isNetBSD()- returns true when the target OS is NetBSD.isOpenBSD()- returns true when the target OS is OpenBSD.isAndroid()- returns true when the target OS is Android.isIOS()- returns true when the target OS is iOS.isSolaris()- returns true when the target OS is Solaris or Illumos.isHaiku()- returns true when the target OS is Haiku.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.isWasm32()- returns true when the target architecture is WebAssembly 32-bit.isWasm64()- returns true when the target architecture is WebAssembly 64-bit.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.
Atomic Builtins (Unstable)
These builtins perform atomic read-modify-write and compare-and-swap operations. They require the compiler to run in unstable mode. The destination must be a variable declared with an atomic ordering modificator, and the operation inherits that ordering.
atomicStore(counter, value)- stores a new value and returns the previous one.atomicAdd(counter, value)- atomic addition. The destination and value must be integers.atomicSubtract(counter, value)- atomic subtraction.atomicAnd(counter, value)- atomic bitwise and.atomicNand(counter, value)- atomic bitwise nand.atomicOr(counter, value)- atomic bitwise or.atomicXor(counter, value)- atomic bitwise xor.atomicSignedMaximum(counter, value)- atomic signed maximum.atomicSignedMinimum(counter, value)- atomic signed minimum.atomicUnsignedMaximum(counter, value)- atomic unsigned maximum.atomicUnsignedMinimum(counter, value)- atomic unsigned minimum.atomicCompareAndSwap(counter, expected, new, success, failure)- compares and swaps; returns true when the swap happened. expected is updated with the current value on failure.
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.processorCount()- returns the number of logical processors available to the host as usize.hostName()- returns the host machine name as a constant string (CString).
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");
}struct PacketHeader @public {
kind: u16,
length: u16,
}
const HEADER_SIZE: usize = sizeOf(PacketHeader);
const HEADER_ALIGN: u32 = alignOf(PacketHeader);
fn hasHeader(bytes: usize) bool @public {
staticAssert(HEADER_SIZE >= 4, "packet header is too small");
staticAssert(HEADER_ALIGN >= 1, "packet header alignment is invalid");
return bytes >= HEADER_SIZE;
}@if(isLinux()) const DEFAULT_CONFIG_DIR: CString = "/etc/thrust";
@elif(isDarwin()) const DEFAULT_CONFIG_DIR: CString = "/Library/Application Support/Thrust";
@else const DEFAULT_CONFIG_DIR: CString = ".";
fn configDir() CString @public {
return DEFAULT_CONFIG_DIR;
}