Flutter网页组件编译插件jaspr_web_compilers的使用

Flutter网页组件编译插件jaspr_web_compilers的使用

Fork of package:build_web_compilers to be used with package:jaspr。

Web compilers for users of package:build.

• 安装
• 使用
• 配置
• 手动使用

安装 #

该包旨在作为用户开发依赖项，这些用户希望在浏览器中运行代码。只需将以下内容添加到你的pubspec.yaml文件中：

dev_dependencies:
  build_web_compilers:

使用 #

如果你正在使用自动生成的构建脚本（通过dart run build_runner <command>而不是手写一个build.dart文件），那么你只需要上述的dev_dependency即可。

配置 #

默认情况下，此包使用Dart开发编译器（dartdevc）将Dart编译为JavaScript。在发布构建（使用--release运行构建工具时），使用dart2js作为编译器。

除了编译为JavaScript之外，此包还支持编译为WebAssembly。目前，需要使用生成器选项启用dart2wasm。要理解这些选项的影响，请注意编译为JavaScript和编译为WebAssembly之间的差异：

1. Dart有两个编译器输出JavaScript：dart2js和dartdevc（后者支持增量重建，但通常仅用于开发）。对于两个JavaScript编译器，build_web_compilers根据编译器选项生成主要入口脚本和附加模块文件或源映射。
2. 使用dart2wasm编译会生成一个WebAssembly模块（.wasm文件）和一个JavaScript模块（.mjs文件）导出函数以实例化该模块。dart2wasm单独不会生成可以作为<script>标签添加的入口文件。

除了调用编译器外，build_web_compilers还可以生成适合dart2wasm的入口文件。当同时启用dart2wasm和JavaScript编译器时，入口文件会运行特性检测以加载WebAssembly模块或JavaScript文件，具体取决于浏览器支持的功能。

编译器参数 #

要自定义编译器，你需要添加一个build.yaml文件来配置build_web_compilers:entrypoint生成器，类似于以下内容：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        # 这些是你要编译的入口点的通配符。
        generate_for:
        - test/**.browser_test.dart
        - web/**.dart
        options:
          compilers:
            # 列出所有启用的编译器：
            dart2js:
              # 列出任何dart2js特定的参数，或省略它。
              args:
                - O2
            dart2wasm:
              args:
                - O3

build_runner默认运行开发构建，但可以使用具有不同配置的生成器进行--release构建。例如，如果你想仅在开发中使用dartdevc，而在发布构建中使用dart2js和dart2wasm，你可以使用以下配置作为起点：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        generate_for:
        - test/**.browser_test.dart
        - web/**.dart
        dev_options:
          compilers:
            dartdevc:
        release_options:
          compilers:
            dart2js:
              args:
                - O2
            dart2wasm:
              args:
                - O3

自定义发出的文件名 #

build_web_compilers发出的文件名可以更改。默认名称取决于启用的编译器：

1. 当仅启用dart2js或dartdevc时，会发出单个.dart.js入口点。
2. 当仅启用dart2wasm时，会生成单个.dart.js入口点（通过.mjs辅助文件加载生成的.wasm模块）。
3. 当同时启用dart2wasm和JavaScript编译器时，则：
   • JavaScript编译器的输出命名为.dart2js.js或.ddc.js，具体取决于编译器。
   • dart2wasm继续发出.wasm和.mjs文件。
   • 生成一个名为.dart.js的入口点加载器，根据浏览器功能加载适当的输出。

所有名称都可以通过使用loader选项或编译器选项中的extension标志来覆盖：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          loader: .load.js
          compilers:
            dart2js:
              extension: .old.js
            dart2wasm:
              extension: .new.mjs

此配置使用了dart2js和dart2wasm，但将main.dart文件的最终入口点命名为main.load.js。该加载器将加载.new.mjs文件用于WebAssembly或.old.js用于纯JavaScript。

请注意，当未启用dart2wasm时，忽略loader选项，因为它需要额外的加载器文件。

自定义WebAssembly加载器 #

在某些情况下，例如针对Node.js时，生成的dart2wasm加载器可能不合适。可以通过设置选项为null来禁用内置加载器：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          loader: null
          compilers:
            dart2js:
            dart2wasm:

在这种情况下，你需要使用另一个生成器或预定义的加载器。

配置-D环境变量 #

dartdevc是一个模块化编译器，为了确保每个模块的一致构建，必须全局配置环境变量。使用YAML中的映射进行配置。环境定义的变量可以通过const String.fromEnvironment和const bool.fromEnvironment读取。例如：

global_options:
  build_web_compilers:ddc:
    options:
      environment:
        SOME_VAR: some value
        ANOTHER_VAR: false

这些也可以通过命令行--define参数指定。

webdev serve -- '--define=build_web_compilers:ddc=environment={"SOME_VAR":"changed"}'

对于dart2js，使用dart2js编译器条目中的args选项。这可以在全局或每目标上进行配置。

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          compilers:
            dart2js:
              args:
                - -DSOME_VAR=some value
                - -DANOTHER_VAR=true

要跨多个编译器应用变量，必须将其添加到每个编译器：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          compilers:
            dart2js:
              args:
                - -DSOME_VAR=some value
                - -DANOTHER_VAR=true
            dart2wasm:
              args:
                - -DSOME_VAR=some value
                - -DANOTHER_VAR=true

旧版生成器选项 #

以前版本的build_web_compilers仅支持单个启用编译器，该编译器将使用compiler选项启用。 如果只想在所有构建中使用dart2js，则可以使用该选项：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        # 这些是你想要编译的入口点的通配符。
        generate_for:
        - test/**.browser_test.dart
        - web/**.dart
        options:
          compiler: dart2js
          # 列出任何dart2js特定的参数，或省略它。
          dart2js_args:
          - -O2

类似地，仅使用dart2wasm进行编译：

targets:
  $default:
    builders:
      build_web_compilers:entrypoint:
        options:
          compiler: dart2wasm
          # 列出应转发给`dart compile wasm`的标志。
          dart2wasm_args:
          - -O2

如果没有设置选项，则compiler选项在发布构建中隐式设置为dart2js，在其他情况下设置为dartdevc。 请注意，当设置了compilers选项时，它优先于compiler选项。

手动使用 #

如果你正在使用自定义构建脚本，你将需要向现有内容添加以下生成器应用，几乎肯定是在列表末尾（除非你需要对js文件进行后处理）。

[
    apply(
        'build_web_compilers:ddc',
        [
        (_) => new ModuleBuilder(),
        (_) => new UnlinkedSummaryBuilder(),
        (_) => new LinkedSummaryBuilder(),
        (_) => new DevCompilerBuilder()
        ],
        toAllPackages(),
        // 推荐，但不是必需的。这样只有由入口点导入的模块才会被编译。
        isOptional: true,
        hideOutput: true),
    apply('build_web_compilers:entrypoint',
        // 你也可以使用`WebCompiler.Dart2Js`。如果你完全不关心dartdevc，你也可以完全省略前面的生成器应用。
        [(_) => new WebEntrypointBuilder(WebCompiler.DartDevc)], toRoot(),
        hideOutput: true,
        // 这些通配符应该匹配你的入口点。
        defaultGenerateFor: const InputSet(
            include: const ['web/**', 'test/**.browser_test.dart'])),
]