flutter_eval

The EvalWidget is a versatile widget that automatically switches behavior based on the build mode:

• Debug Mode: It dynamically compiles the provided Dart code into EVC bytecode, saves it to the assetPath, and runs it. This allows for hot-reloading during development.
• Release Mode: It ignores the provided Dart code and attempts to load EVC bytecode from the assetPath or a network uri.

Use EvalWidget when you want a seamless transition from local development (writing Dart) to production (loading pre-compiled EVC).

return EvalWidget(
    packages: {
      'example': {
        'main.dart': '''
  import 'package:flutter/material.dart';
  class MyWidget extends StatelessWidget {
    MyWidget(this.name);
    final String name;
    @override
    Widget build(BuildContext context) => Text(name);
  }
''',
      },
    },
    assetPath: 'assets/program.evc',
    library: 'package:example/main.dart',
    function: 'MyWidget.',
    args: [$String('Example name')]
);

To enable over-the-air updates (code-push), follow these steps:

1. Setup the Loader: Wrap your application (e.g., MaterialApp) in a HotSwapLoader widget and provide a uri pointing to your hosted .evc update file.
2. Identify Hot-swappable areas: Place HotSwap widgets at the specific locations in your widget tree that you want to update dynamically. Each HotSwap requires a unique id (prefixed with #) and an args list. Use $BuildContext.wrap(context) to pass the current context.
3. Update Strategies: HotSwap widgets support three loading strategies:
   • immediate: Loads the update immediately (default in debug/profile mode).
   • cache: Uses a cached version.
   • cacheApplyOnRestart: Applies the cached update upon the next app restart (default in release mode).
4. Loading State: You can provide a placeholder widget via the loading parameter to display while the update is being fetched from the cache.

// 1. Setup HotSwapLoader at the root
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return HotSwapLoader(
        uri: 'https://mysite.com/app_update/version_xxx.evc',
        child: MaterialApp(
          ...
        ),
    );
  }
}

// 2. Use HotSwap at specific locations
class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return HotSwap(
      id: '#myHomePage',
      args: [$BuildContext.wrap(context)],
      childBuilder: (context) => Scaffold(
        ...
      ),
    );
  }
}

For development, you can run both the compilation and execution steps within your app to receive immediate feedback on code errors. This involves using the Compiler class to transform Dart source into EVC bytecode and the Runtime class to execute it.

1. Initialize a Compiler and add the flutterEvalPlugin.
2. Call compiler.compile() with a map containing your package and source code.
3. Write the resulting bytecode to a file using program.write().
4. Initialize a Runtime using Runtime.ofProgram(program) and add the flutterEvalPlugin.

class ExampleState extends State<Example> {
  late Runtime runtime;

  @override
  void initState() {
    super.initState();

    final compiler = Compiler();
    compiler.addPlugin(flutterEvalPlugin);

    final program = compiler.compile({
      'example': { 'main.dart': '''
          import 'package:flutter/material.dart';
          
          class HomePage extends StatelessWidget {
            HomePage(this.number);
            final int number;
            
            @override
            Widget build(BuildContext context) {
              return Padding(
                padding: EdgeInsets.all(2.3 * 5),
                child: Container(
                  color: Colors.green,
                  child: Text('Current amount: ' + number.toString())
                )
              );
            }
          }
        ''' }
    });

    final file = File('out.evc');
    file.writeAsBytesSync(program.write());
    
    runtime = Runtime.ofProgram(program);
    runtime.addPlugin(flutterEvalPlugin);
  }

  @override
  Widget build(BuildContext context) {
    return (runtime.executeLib('package:example/main.dart', 'HomePage.', [$int(55)]) as $Value).$value;
  }
}

To create the .evc files used for code-push, follow this workflow:

1. Install the CLI:

   dart pub global activate dart_eval

2. Prepare the Hot Update Package:
   • Create a new Flutter package (flutter create --template=package).
   • Add eval_annotation to the package's pubspec.yaml.
   • Download the flutter_eval.json binding file from the flutter_eval GitHub Releases page (matching your current flutter_eval version).
   • Place the JSON file in .dart_eval/bindings/flutter_eval.json within your hot update package.
3. Annotate Updates: In your hot update package, create top-level functions for each HotSwap widget and annotate them with @RuntimeOverride('#your_id').
4. Compile: Run the following command in the root of your hot update package:

   dart_eval compile -o version_xxx.evc

   The resulting .evc file can then be uploaded to your server.

In production, you should avoid running the Compiler at runtime as it is slow. Instead, use the pre-compiled EVC bytecode (.evc file) generated during development. EVC bytecode is platform-agnostic; you can generate it on Flutter Desktop and use it in a Flutter Mobile app.

To use pre-compiled bytecode:

1. Include the .evc file in your app's assets.
2. Load the bytecode using rootBundle.load().
3. Initialize the Runtime with Runtime(ByteData.sublistView(bytecode)).
4. Add the flutterEvalPlugin to the runtime.

You can also load the bytecode over a network. Since EVC bytecode compresses well (approx. 4x ratio), using gzip compression for network transfers is recommended.

import 'package:flutter/services.dart' show rootBundle;

class ExampleState extends State<Example> {
  Runtime? runtime;

  @override
  void initState() {
    super.initState();
    
    rootBundle.load('assets/out.evc').then((bytecode) => setState(() {
      runtime = Runtime(ByteData.sublistView(bytecode));
      runtime.addPlugin(flutterEvalPlugin);
    }));
  }

  @override
  Widget build(BuildContext context) {
    if (runtime == null) return CircularProgressIndicator();
    return (runtime.executeLib('package:example/main.dart', 'HomePage.', [$int(55)]) as $Value).$value;
  }
}