Attributes

Compiler attributes for metadata and behavior annotations

Attributes annotate declarations with metadata that influences compilation behavior. They use the form #[attribute_name] for item-level attributes and #![attribute_name] for module-level attributes.

Item Attributes

Item attributes are placed before the item they annotate (functions, structs, etc.) using #[attribute_name].

#[test]

#[test]
fn test_addition() {
    result := add(2, 3)
    assert(result == 5)
}

Marks a function as a unit test. Test functions are run by the test runner and are not included in release builds.

Usage

  • Applied to functions
  • Test functions typically contain assertions
  • Tests are run with the test framework

#[bench]

#[bench]
fn bench_sorting() {
    data := create_test_data(1000)
    sort(data)
}

Marks a function as a benchmark. Benchmark functions are run by the benchmarking framework to measure performance.

Usage

  • Applied to functions
  • Used for performance testing
  • Not included in regular builds

#[host_call]

#[host_call]
fn render_sprite(x: Int, y: Int, sprite_id: Int) {
    // Will be called from the host
}

Marks a function that will be called from the super level (Host). The host environment calls into this Swamp function.

Usage

  • Applied to functions
  • The function will be invoked by the host runtime
  • Used to expose Swamp functions to the host environment
  • The function contains normal Swamp code that the host can call

#[repr]

#[repr(Uniform)]

#[repr(Uniform)]
struct MaterialProperties {
    color: Vec4
    roughness: F32
    metallic: F32
}

Specifies that a struct should use uniform memory layout, typically for WebGPU buffer compatibility. It only allows the somewhat “basic types”:

  • Int – 32-bit signed integer
  • U32 – 32-bit unsigned integer
  • F32 – 32-bit float
Vector
  • vec2<f32>
  • vec3<f32>
  • vec4<f32>
  • vec2<i32>
Matrix
  • mat2x2<f32>
  • mat3x3<f32>
  • mat4x4<f32>
Block
  • Block<T>

Usage

  • Applied to structs
  • Ensures the struct layout matches GPU uniform buffer requirements
  • Used when passing data to shaders

#[api]

#[api]
fn create_entity(name: String, position: Vec2) -> EntityId {
    // ... implementation
}

Suppresses compiler warnings about unused functions or definitions. Useful for public API functions that may not be used within the crate itself.

Usage

  • Applied to functions or types
  • Prevents “unused” warnings from the compiler
  • Indicates the item is part of a public interface

#[extensions]

#[extensions("png", "jpeg", "jpg")]
struct Image {
    width: Int
    height: Int
}

Specifies file extensions for resource type verification. The compiler may use this information during resource ID checking.

Usage

  • Applied to structs
  • Used for compile-time resource validation
  • Accepts a list of file extension strings

Module Attributes

Module attributes are placed at the top of a file and affect the entire module using #![attribute_name].

#![api]

#![api]

// All declarations in this module won't generate unused warnings
fn create_player() -> Player { ... }
fn update_player(mut player: Player) { ... }

Suppresses compiler warnings about unused functions or definitions for all items in the module.

Usage

  • Applied to modules (placed at the top of a file)
  • Affects all declarations in the module
  • Prevents “unused” warnings for the entire module

Syntax

Item Attribute Syntax

#[attribute_name]
#[attribute_name(argument)]
#[attribute_name("arg1", "arg2")]

Module Attribute Syntax

#![attribute_name]

Module attributes use #! instead of # and must appear at the top of the file.