Dart Pragma Annotation

A pragma is a built-in Dart annotation used to provide specific directives, hints, or metadata to the underlying Dart compiler, virtual machine (VM), or static analysis tools. It acts as a mechanism to pass tool-specific instructions that are outside the standard Dart language semantics, allowing developers to influence compilation, optimization, or execution behavior.

Syntax

The @pragma annotation is instantiated with a required string identifier and an optional constant argument.

@pragma('name', [options])

Anatomy of a Pragma

name (String): A compile-time constant string that identifies the directive. By convention, the name is namespaced using a prefix that denotes the target tool, followed by a colon and the specific instruction (e.g., 'vm:prefer-inline', 'dart2js:noInline').
options (Object?): An optional, compile-time constant value that supplies additional parameters or configuration to the tool processing the pragma. If omitted, it defaults to null.

Mechanics and Resolution

Target Agnosticism: Pragmas are designed to be safely ignored by tools that do not understand them. If the Dart VM encounters a dart2js: pragma, or if the analyzer encounters an unrecognized vm: pragma, the tool will bypass the annotation without emitting compilation errors or warnings.
Compile-Time Evaluation: Both the name and the options arguments must be strictly evaluated as compile-time constants.
Application Targets: The @pragma annotation can be attached to almost any Dart declaration, including libraries, classes, mixins, functions, methods, and variables.

Syntax Visualization

// A pragma with only a name directive applied to a top-level function
@pragma('vm:prefer-inline')
int calculateOffset(int x, int y) {
  return x + y;
}

// Multiple pragmas applied to a single class declaration
@pragma('dart2js:noInline')
@pragma('vm:invisible')
class ExecutionHandler {
  
  // A pragma utilizing the optional 'options' parameter with a valid string argument
  @pragma('vm:entry-point', 'call')
  void invoke() {
    // Method implementation
  }
}