Attributes

Attributes are compile-time annotations on functions, types, global constants and variables. Similar to Java annotations, an attribute may also take arguments. An attribute can also represent a bundle of attributes.

Built in attributes¶

`@align(alignment)`¶

Used for: struct, bitstructs, union, var, function

This attribute sets the minimum alignment for a field or a variable, for example:

struct Foo @align(32)
{
    int a;
    int b @align(16);
}

Note that following C behaviour, @align is only able to increase the alignment. If setting a smaller alignment than default is desired, then use @packed (which sets the alignment to 1 for all members) and then @align.

`@allow_deprecated`¶

Used for: functions

This attribute suppresses detection of @deprecated for the function's parameters and body.

`@benchmark`¶

Used for: function

Marks the function as a benchmark function. Will be added to the list of benchmark functions when the benchmarks are run, otherwise the function will not be included in the compilation.

`@bigendian`¶

Used for: bitstruct

Lays out the bits as if the data was stored in a big endian type, regardless of host system endianness.

`@builtin`¶

Used for: function, macro, global, const

Allows a macro, function, global or constant be used from another module without the module path prefixed. Should be used sparingly.

`@callconv`¶

Used for: function

Sets the calling convention, which may be ignored if the convention is not supported on the target. Valid arguments are "veccall", "cdecl", "stdcall". Any function without an explicit @callconv will use "cdecl" which is the normal C calling convention.

Caution

On Windows, many calls are tagged stdcall in the C headers. However, this calling convention is only ever used on 32-bit Windows, and is a no-op on 64-bit Windows.

`@cname`¶

Used for: function, global, const, enum, union, struct, faultdef

Sets the external (linkage) name of this declaration.

Caution

Do not confuse this with @export, which is required to export a function or global.

`@compact`¶

Used for: struct, union

This attribute works like @nopadding, but is applied recursively for any sub-elements, ensuring that there is no padding anywhere in the struct.

`@const`¶

Used for: macro

This attribute will ensure that the macro is always compile time folded (to a constant). Otherwise, a compile time error will be issued.

`@constinit`¶

Used for: constdef, typedef

This attribute allows a typedef or constdef to be initialized from a literal without an explicit cast.

`@deprecated`¶

Used for: types, function, macro, global, const, member

Marks the particular type, global, const or member as deprecated, making use trigger a warning.

`@dynamic`¶

Used for: methods

Mark a method for dynamic invocation. This allows the method to be invoked through interfaces.

`@export`¶

Used for: function, global, const, enum, union, struct, faultdef

Marks this declaration as an export, this ensures it is never removed and exposes it as public when linking. The attribute takes an optional string value, which is the external name. This acts as if @cname had been added with that name.

`@feat`¶

Used for: any top-level declaration, module section

Conditionally compiles the declaration based on the compiler's feature flags.

fn void foo_win32() @feat(WIN32)
{
    // Only compiled when the WIN32 feature flag is set.
}

int b @feat(NO_LIBC);

The argument is a feature-list: one or more feature identifiers (CONST_IDENT) combined with &, |, !, and parentheses. A comma at the top level is treated as |, so @feat(POSIX, WIN32) matches when either flag is set. Repeating the attribute is treated as &, so @feat(POSIX) @feat(BIG_ENDIAN) matches only when both are set. Negation is also permitted: @feat(POSIX | !WIN32).

The compiler provides a large set of built-in feature flags for platform and target selection (WIN32, MACOS, LINUX, POSIX, BIG_ENDIAN, and many more); additional flags may be supplied through the build system.

`@finalizer`¶

Used for: function

Make this function run at shutdown. See @init for the optional priority. Note that running a finalizer is a "best effort" attempt by the OS. During abnormal termination it is not guaranteed to run.

The function must be a void function taking no arguments.

`@format`¶

Used for: functions and macros

Declares that this function or macro takes a formatting string followed by parameters, and enables compile time checking of the parameters. The argument of @format is the zero indexed position of the formatting string.

`@if`¶

Used for: declarations inside a generic module, and methods of generic types

Conditionally includes a parameterized declaration at instantiation time based on a compile-time boolean condition. The condition may refer to the declaration's generic parameters:

module container <Ty>;

Ty first_element @if(Ty.kindof == TypeKind.SIGNED_INT);

@if is not available on non-parameterized top-level declarations; use @feat for feature-flag-based conditional compilation.

NOTE: Previous to 0.8.3, this was available for all top-level declarations.

`@init`¶

Used for: function

Make this function run at startup before main. It has an optional priority 1 - 65535, with lower being executed earlier. It is not recommended to use values less than 128 as they are generally reserved and using them may interfere with standard program initialization.

The function must be a void function taking no arguments.

`@inline`¶

Used for: function, call

Declares a function to always be inlined or if placed on a call, that the call should be inlined.

`@jump`¶

Used for: switch statements

Turns switches to guaranteed jump tables, which in some cases may be more efficient.

`@link`¶

Used for: module, function, macro, global, const

Syntax for this attribute is @link(cond, link1, link2, ...), where "link1" etc are strings names for libraries to implicitly link to when this symbol is used.

In the case of a module section, adding @link implicitly places the attribute on all of its symbols.

`@littleendian`¶

Used for: bitstruct

Lays out the bits as if the data was stored in a little endian type, regardless of host system endianness.

`@local`¶

Used for: any declaration

Sets the visibility to "local", which means it's only visible in the current module section.

`@maydiscard`¶

Used for: function, macro

Allows the return value of the function or macro to be discarded even if it is an optional. Should be used sparingly.

`@mustinit`¶

Used for: user-defined types

Prevents the use of the @noinit tag on a variable of the specified type.

`@naked`¶

Used for: function

This attribute disables prologue / epilogue emission for the function. The body of the function should be a text asm statement.

`@noalias`¶

Used for: function parameters

This is similar to restrict in C. A parameter with @noalias should be a pointer type, and the pointer is assumed not to alias to any other pointer.

`@nodiscard`¶

Used for: function, macro

The return value may not be discarded.

`@noinit`¶

Used for: global, local variable

Prevents the compiler from zero initializing the variable.

`@noinline`¶

Used for: function, function call

Prevents the compiler from inlining the function or a particular function call.

`@nopadding`¶

Used for: struct, union

Ensures that a struct of union has no padding, emits a compile time error otherwise.

`@norecurse`¶

Used for: import @norecurse

Import the module but not sub-modules or parent-modules, see Modules Section.

`@noreturn`¶

Used for: function, macro

Declares that the function will never return.

`@nosanitize`¶

Used for: function

This prevents sanitizers from being added to this function.

`@nostrip`¶

Used for: any declaration

This causes the declaration never to be stripped from the executable, even if it's not used. This also transitively applies to any dependencies the declaration might have.

`@obfuscate`¶

Used for: any declaration

Removes any string values that would identify the declaration in some way. Mostly this is used on faults and enums to remove the stored names.

`@operator`, `@operator_s`, `operator_r`¶

Used for: method, macro method

This attribute has arguments [] []= &[] and len allowing subscript operator overloading for [] and foreach. By implementing [] and len, foreach and foreach_r is enabled. In order to do foreach by reference, &[] must be implemented as well.

Furthermore ==, !=, bit operations and arithmetics can all be overloaded.

`@optional`¶

Used for: interface methods

Placed on an interface method, this makes the method optional to implement for types that implements the interface.

See the Printable interface for an example.

`@overlap`¶

Used for: bitstruct

Allows bitstruct fields to have overlapping bit ranges.

`@packed`¶

Used for: struct, union

Causes all members to be packed as if they had alignment 1. The alignment of the struct/union is set to 1. This alignment can be overridden with @align.

`@private`¶

Used for: any declaration

Sets the visibility to "private", which means it is visible in the same module, but not from other modules.

`@public`¶

Used for: any declaration

Sets the visibility to "public", which means it is visible from other modules if its module is included. This is the default visibility.

`@pure`¶

Used for: call

Used to annotate a non pure function as "pure" when checking for conformance to @pure on functions.

`@reflect`¶

Used for: any declaration

Adds additional reflection information. Has no effect currently.

`@safemacro`¶

Used for: macros

Allows a macro to drop the @ name prefix, even if it normally would be required to have one.

`@section(name)`¶

Used for: function, const, global

Declares that a global variable or function should appear in a specific section.

`@simd`¶

Used for: vector types

Turns a vector type into a type matching C SIMD types for the purpose of storage and ABI lowering. Usually it will not offer any additional speed over using regular vector types, and are mostly for conforming to C functions that explicitly use SIMD types.

`@tag(name, value)`¶

Used for: function, macro, user-defined type, struct/union/bitstruct member, global, local variables

Adds a compile time tag to a type, function or member which can be retrieved at compile time using reflection: .has_tag(..) and .get_tag(...). Example: Foo.has_tag("bar") will return true if Foo has a tag "bar". Foo.get_tag("bar") will return the value associated with that tag. For variables and members, access it using $reflect: $reflect(my_global).has_tag("bar").

`@test`¶

Used for: module, function

Marks the function or all functions inside the module section, as a test function. They will be added to the list of test functions when the tests are run, otherwise the function(s) will not be included in the compilation.

`@unused`¶

Used for: any declaration

Marks the declaration as possibly unused (but should not emit a warning).

`@used`¶

Used for: any declaration

Marks a parameter, value etc. as must being used.

`@wasm`¶

Used for: function, global, const

This attribute may take 0, 1 or 2 arguments. With 0 or 1 arguments it behaves identical to @export if it is non-extern. For extern symbols it behaves like @cname.

When used with 2 arguments, the first argument is the wasm module, and the second is the name. It can only be used for extern symbols.

`@winmain`¶

Used for: function

This attribute is ignored on non-windows targets. On Windows, it will create a WinMain entry point which calls the main function. This will give other options for the main argument, and is recommended for Windows GUI applications.

It is only valid for the main function.

`@weak`¶

Used for: function, const, global

Like @weaklink, but if the same definition occurs in the same compilation, the non-weak one is preferred.

`@weaklink`¶

Used for: function, const, global

Emits a weak symbol rather than a global.

User defined attributes¶

User defined attributes are intended for conditional application of built-in attributes.

attrdef @MyAttribute = @noreturn, @inline;
attrdef @MyCname(x) = @cname(x);
// The following two are equivalent:
fn void foo() @MyAttribute { /* */ }
fn void foo() @noreturn @inline { /* */ }

An attribute may also take parameters:

attrdef @MyAttr(val) = @tag("foo", val);

struct Test
{
    int foo @MyAttr("test");
}

$echo Test.foo.tagof("foo"); // Will echo "test" at compile time

The attribute may also be completely empty:

attrdef @MyAttributeEmpty;

Attributes

Built in attributes¶

@align(alignment)¶

@allow_deprecated¶

@benchmark¶

@bigendian¶

@builtin¶

@callconv¶

@cname¶

@compact¶

@const¶

@constinit¶

@deprecated¶

@dynamic¶

@export¶

@feat¶

@finalizer¶

@format¶

@if¶

@init¶

@inline¶

@jump¶

@link¶

@littleendian¶

@local¶

@maydiscard¶

@mustinit¶

@naked¶

@noalias¶

@nodiscard¶

@noinit¶

@noinline¶

@nopadding¶

@norecurse¶

@noreturn¶

@nosanitize¶

@nostrip¶

@obfuscate¶

@operator, @operator_s, operator_r¶

@optional¶

@overlap¶

@packed¶

@private¶

@public¶

@pure¶

@reflect¶

@safemacro¶

@section(name)¶

@simd¶

@tag(name, value)¶

@test¶

@unused¶

@used¶

@wasm¶

@winmain¶

@weak¶

@weaklink¶

User defined attributes¶

`@align(alignment)`¶

`@allow_deprecated`¶

`@benchmark`¶

`@bigendian`¶

`@builtin`¶

`@callconv`¶

`@cname`¶

`@compact`¶

`@const`¶

`@constinit`¶

`@deprecated`¶

`@dynamic`¶

`@export`¶

`@feat`¶

`@finalizer`¶

`@format`¶

`@if`¶

`@init`¶

`@inline`¶

`@jump`¶

`@link`¶

`@littleendian`¶

`@local`¶

`@maydiscard`¶

`@mustinit`¶

`@naked`¶

`@noalias`¶

`@nodiscard`¶

`@noinit`¶

`@noinline`¶

`@nopadding`¶

`@norecurse`¶

`@noreturn`¶

`@nosanitize`¶

`@nostrip`¶

`@obfuscate`¶

`@operator`, `@operator_s`, `operator_r`¶

`@optional`¶

`@overlap`¶

`@packed`¶

`@private`¶

`@public`¶

`@pure`¶

`@reflect`¶

`@safemacro`¶

`@section(name)`¶

`@simd`¶

`@tag(name, value)`¶

`@test`¶

`@unused`¶

`@used`¶

`@wasm`¶

`@winmain`¶

`@weak`¶

`@weaklink`¶