Polymerize 0.9.6 with build tool support

Introducing support for build in polymerize.

What is build

build is the new build tool for dart and will eventually replace pub build in the dart developer workflow (or being integrated with it).

There are many advantages but one of the main changes between the “old” pub build and build is that transformers (the mechanism used in pub to modify your source code on the fly while building) will be progressively deprecated and replaced with source generation.

That also means that (at least for now) source generation happens outside the build phase (pub build). A build.dart script have to be written that describes the build actions to be executed and it may be executed during the coding phase but before pub build/pub serve at least once (see more details on the tool site).

Polymerize is going to support the new dart developer workflow, starting from this release.

Build tool support in polymerize

Internally some of the polymerize transformer are being rewritten as source_gen’s generators and wrapped again as transfomers. This means that you can continue to use polymerize in the usual way if you want.

If you want to start using a more build like workflow instead you can shut down those polymerize’s transformers by using the new option (skip-generate: true in the pubspec) and provide a build.dart script to manually generate the polymerize files that contains the polymerize build action in order to generate the extra files needed. You also have to add a part directive to your files containing annotation used by polymerize.

To summarize :

  1. add skip-generate to pubspec.yaml:
    ...
    transformers:
     polymerize:
      entry-points:
        - web/**.dart
        - lib/**.dart
      skip-generate: true
    ...
    
    
  2. write a build.dart (and execute it when appropriate)
  3. add part directive to include the generated parts (only once of course):
    ...
     imports/exports directives
    ...
    // Add a part directive to include generated files
    part 'myfile.polymerize.dart'
    
    ...
     my normal code here
    ...
    

Sample build.dart file

This a sample build.dart file for a project whose package-name is myproject:

    
        import 'package:build_runner/build_runner.dart';
        import 'package:source_gen/source_gen.dart';
        import 'package:polymerize/polymerize.dart';

        main() {
          build([
            new BuildAction(polymerizePartBuilder(), 'myproject',inputs:[
              'lib/**.dart',
              'web/**.dart',
              'test/**.dart',
              ]),
          ]);
        }

So you just have to call polymerizePartBuilder() and create a BuildAction with it (see build documentation for that). The default extension for generated files is .polymerize.dart. You can change it by passing an extension named parameter : polymerizeBuilder(extension:'myext.dart') (beware that build/source_gen requires the extension to end with .dart ).

Using ‘skip-generate’ in libs

You can use skip-generate option in libraries too (not only in the main application package). BUt this means that you also have to distribute the generated code with the library (that’s actually obvious because otherwise the code won’t even build).

What’s missing

Not all the polymerize transformers are being replaced by build code generation. Some of them will be replaced in the near future but others are waiting for the dart team to better consolidate the tools.