Dart Pragma Annotation

​

Syntax

@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

1. 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.
2. Compile-Time Evaluation: Both the name and the options arguments must be strictly evaluated as compile-time constants.
3. 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
  }
}