# Attributes and native interop

> Apply compiler hints, CLR attributes, stack and SoA annotations, and P/Invoke declarations.

Canonical: https://alice-lang.org/documentation/language/attributes/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Attribute syntax

An attribute precedes the declaration it affects:

```alice
@[Inline]
def square(x : Int32) : Int32
  x * x
end
puts square(4)
```

Unknown attribute names are treated as .NET attributes, so the target type and constructor must be available from the program's references.

## Compiler-recognized attributes

| Attribute                       | Meaning                                            |
| ------------------------------- | -------------------------------------------------- |
| `@[Inline]`                     | Aggressive-inlining hint                           |
| `@[NoInline]`                   | No-inlining hint                                   |
| `@[Hot]`                        | Aggressive-optimization hint                       |
| `@[Stack]` on a struct          | Stack-only `ref struct`                            |
| `@[SoA]` on a record struct     | Enable the `SoA(T)` column store                   |
| `@[StrictMath]` on a method     | Keep separate floating-point multiply/add rounding |
| `@[Link("library")]` on a `lib` | Link P/Invoke function declarations                |

Hints do not guarantee a JIT decision or a speedup. Measure the complete workload. SoA changes the storage API; stack-only types have CLR lifetime restrictions.

## Calling a native library

A `lib` declaration contains `fun` signatures that map to P/Invoke:

```alice
@[Link("libm.so.6")]
lib LibM
  fun cos(x : Float64) : Float64
end
puts LibM.cos(0.0)
```

This example is Linux-specific: the native library name must exist on the target platform. Other operating systems need the appropriate library name and ABI. A declaration's argument and return types must match the native function exactly. It is not a portable browser example.

`@[Fast]` on a native `fun` requests `SuppressGCTransition`; reserve it for tiny bounded calls that cannot block or call back into managed code. Native `Bool` parameters use one-byte marshalling in the supported ABI mapping.

## Experimental native functions

The source tree also contains an opt-in `@[Native]` path for a restricted numeric function subset. It may invoke a system C compiler and use a managed fallback when the generated library is unavailable. It is separate from ordinary Alice-to-C#-to-IL compilation and from `alice build --native` (NativeAOT).

Treat this as environment-dependent experimental functionality. Supported bodies focus on numeric values, numeric array parameters, locals, loops, conditions, and selected math calls. It does not make arbitrary .NET objects or APIs usable from generated native code. Check the repository's [performance notes](https://github.com/alicelanguage/alice/blob/main/docs/performance.md) and `NativeTests` before depending on it.

For ordinary distribution, start with the managed build or [NativeAOT](https://alice-lang.org/documentation/guides/publishing.md).

## Continue reading

- Previous: [Dynamic features and DSLs](https://alice-lang.org/documentation/language/dynamic.md)
- Next: [Tuples, delegates, and reflection](https://alice-lang.org/documentation/language/tuples.md)