dart_eval

To avoid runtime compilation overhead, pre-compile your Dart code into EVC (eval bytecode) files. This is more efficient than compiling at runtime.

Workflow:

1. Use Compiler.compile() to generate a program.
2. Call program.write() to get the bytecode.
3. Save the bytecode to a file.
4. Load the file using Runtime(bytecode) for execution.

// --- Compiling to a file ---
import 'dart:io';
import 'package:dart_eval/dart_eval.dart';

void main() {
  final compiler = Compiler();
  final program = compiler.compile({'my_package': {
    'main.dart': 'int main() => 42;' 
  }});
  
  final bytecode = program.write();
  final file = File('program.evc');
  file.writeAsBytesSync(bytecode);
}

// --- Loading and executing later ---
void runLater() {
  final file = File('program.evc');
  final bytecode = file.readAsBytesSync().buffer.asByteData();
  
  final runtime = Runtime(bytecode);
  print(runtime.executeLib('package:my_package/main.dart', 'main')); // prints '42'
}

Bridge interop is used when you need to extend a native Dart class or use it as an interface within dart_eval.

Note: Unlike wrapper interop, bridge interop does not allow you to wrap an existing instance of the class; you must instantiate the bridge class itself.

1. Annotate your class with @Bind(bridge: true).
2. Run dart_eval bind to generate bindings and the plugin.
3. Add the plugin to the Compiler and Runtime.

To use classes from other packages without cloning them, you can create a subclass and use the @Bind(implicitSupers: true) annotation to create bindings for all inherited methods and properties.

import 'package:eval_annotation/eval_annotation.dart';

@Bind(bridge: true)
class Book {
  final List<String> pages;
  Book(this.pages);
  String getPage(int index) => pages[index];
}

// Usage in dart_eval:
import 'package:dart_eval/dart_eval.dart';
import 'package:my_app/book.dart';

final compiler = Compiler();
compiler.addPlugin(MyAppPlugin());
final program = compiler.compile({'my_package': {
  'main.dart': '''
    import 'package:my_app/book.dart';

    class MyBook extends Book {
      MyBook(super.pages);

      @override
      String getPage(int index) {
        return 'MyBook: ${super.getPage(index)}';
      }
    }

    MyBook main() {
      final book = MyBook(['Page 1', 'Page 2']);
      return book;
    }
  '''
}});

final runtime = Runtime.ofProgram(program);
runtime.addPlugin(MyAppPlugin());

final book = runtime.executeLib('package:my_package/main.dart', 'main') as Book;
print(book.getPage(0)); // prints 'MyBook: Page 1'

Wrapper interop allows you to use native Dart classes, pass them as arguments, and call their methods within dart_eval.

1. Annotate your class with @Bind() from the eval_annotation package.
2. Run dart_eval bind in your project directory to generate bindings and a plugin.
3. Add the generated plugin to both the Compiler and the Runtime.

Core Dart types are backed by native values. You can access the backing native value using the $value property of a $Value object. This approach also exposes a $ClassName wrapper class to wrap existing instances for use in dart_eval.

import 'package:eval_annotation/eval_annotation.dart';

@Bind()
class Book {
  final List<String> pages;

  Book(this.pages);
  String getPage(int index) => pages[index];
}

// After running `dart_eval bind` and using the generated plugin:
import 'package:dart_eval/dart_eval.dart';

final compiler = Compiler();
compiler.addPlugin(MyAppPlugin());
final program = compiler.compile({'my_package': {
  'main.dart': '''
    import 'package:my_app/book.dart';
    
    Book main() {
      final book = Book(['Page 1', 'Page 2']);
      return book;
    }
  '''
}});

final runtime = Runtime.ofProgram(program);
runtime.addPlugin(MyAppPlugin());

final book = runtime.executeLib('package:my_package/main.dart', 'main').$value as Book;
print(book.getPage(0)); // prints 'Page 1'

The runtime overrides system allows you to dynamically swap function or constructor implementations at runtime.

1. Prepare the code for overriding

In your Dart code, wrap the call site with a null-coalescing call to runtimeOverride() using a unique ID:

final result = runtimeOverride('#myFunction') ?? myFunction();

Note: You may need to cast the return value of runtimeOverride as the compiler cannot specify generic parameters to the Dart type system.

2. Mark the override in eval code

In the code being evaluated, mark the target function with the @RuntimeOverride annotation:

@RuntimeOverride('#myFunction')
String myFunction() => 'Updated version of string';

3. Load overrides

Call loadGlobalOverrides() on the Runtime instance. This sets the runtime as the single global runtime and loads overrides for use by hot wrappers.

void main() {
  // Give the override a unique ID
  final result = runtimeOverride('#myFunction') ?? myFunction();
  print(result);
}

String myFunction() => 'Original version of string';

// In the eval code:
@RuntimeOverride('#myFunction')
String myFunction() => 'Updated version of string';

The dart_eval runtime is sandboxed. By default, programs cannot access the file system, network, or other system resources. You must explicitly grant permissions using runtime.grant or the permissions parameter in eval().

Available Permission Domains:

• FilesystemPermission: Control file access (e.g., FilesystemPermission.any, FilesystemReadPermission.directory(path)).
• NetworkPermission: Control network access (e.g., NetworkPermission.any, NetworkPermission.url(url)).
• ProcessPermission: Control process execution (e.g., ProcessRunPermission(RegExp(pattern))).

Usage:

• Use runtime.grant(permission) to enable access.
• Use runtime.revoke(permission) to remove access.
• Use the @AssertPermission annotation when writing bindings to ensure required permissions are present.

// Using runtime.grant
final runtime = Runtime(bytecode);
runtime.grant(FilesystemPermission.any);
runtime.grant(NetworkPermission.url('example.com'));

// Using eval() with permissions
eval(source, permissions: [
  NetworkPermission.any,
  FilesystemReadPermission.directory('/home/user/mydata'), 
  ProcessRunPermission(RegExp(r'^ls$'))
]);