source_gen 0.9.6

Dart native

Dart构建系统的源代码生成构建器和实用程序

Build Status Pub Package Version Join the chat on Gitter

Overview #

source_gen提供了用于Dart自动生成源代码的实用程序:

  • 用于编写使用和生成Dart代码的Builder的框架 .
  • 人和工具生成的Dart代码可以与纯净的分离共存,并且多个代码生成器可以集成在同一项目中的约定 .

它的主要目的是在分析器build等较低级别的包之上公开对开发人员友好的API. 您不必使用source_gen以生成源代码; 我们还公开了一组可能对您的生成器有用的库API.

Quick Start Guide for writing a Generator #

在发布source_gen中添加对source_gen的依赖关系.

dependencies:
  source_gen:

如果您仅在自己的项目中使用source_gen来生成代码,并且不会发布Generator供其他人使用,则它可能是dev_dependency

dev_dependencies:
  source_gen:

设置source_gen ,应参考以下示例.

Writing a generator to output Dart source code #

扩展GeneratorGeneratorForAnnotation类,并且source_gen将为Dart库或库source_gen有您感兴趣的注释的每个元素调用生成器.

Configuring and Running generators #

source_gen基于构建包,并提供在Builder使用Generator选项. 根据希望生成的代码结束的位置选择一个生成器:

  • 如果你想写入.g.dart被作为参考文件part原始源文件中,使用SharedPartBuilder . 这是零件文件中生成代码的约定,并且该文件可能还包含其他包提供的Generator的代码.
  • 如果要写入作为原始源文件的part引用的.some_name.dart文件,请使用PartBuilder . 您应该选择一个唯一的扩展名. 多个Generator可能会输出到此文件,但是它们全部来自您的软件包,并且在构建构建器时将设置整个列表.
  • 如果要编写可import独立Dart库,请使用LibraryBuilder . 只能将一个Generator用作LibraryBuilder .

为了使Builderbuild_runner一起使用,必须在build.yaml文件中对其进行配置. 有关更多详细信息,请参见build_config . 每当发布包含build.yaml文件的软件包时,都应在pubspec中包括对build_config的依赖.

当使用SharedPartBuilder应该始终被配置为build_to: cache (隐藏文件)并应用combining_builder从这个包. 组合构建器读取由不同共享零件构建器编写的所有片段,并将它们写入用户源目录中的最终.g.dart输出. 切勿将.g.dart扩展名用于任何其他Builder.

builders:
  some_cool_builder:
    import: "package:this_package/builder.dart"
    builder_factories: ["someCoolBuilder"]
    # The `partId` argument to `SharedPartBuilder` is "some_cool_builder"
    build_extensions: {".dart": [".some_cool_builder.g.part"]}
    auto_apply: dependents
    build_to: cache
    # To copy the `.g.part` content into `.g.dart` in the source tree
    applies_builders: ["source_gen|combining_builder"]

Configuring combining_builder ignore_for_file #

有时,生成的代码不支持目标软件包中指定的所有棉绒 . 当使用基于package:source_genBuilder并应用combining_builder ,请将ignore_for_file选项设置为希望在所有生成的库中忽略的棉绒列表.

Example build.yaml configuration:

targets:
  $default:
    builders:
      source_gen|combining_builder:
        options:
          ignore_for_file:
          - lint_alpha
          - lint_beta

如果您提供使用SharedPartBuildercombining_builder的构建器,则应为用户记录此功能.

FAQ #

What is the difference between source_gen and build? #

Build是一个与Dart资产或代码生成无关的平台框架,可插入到构建系统(包括bazel )和独立工具(例如build_runner)中 . 您也可以建立自己的.

同时, source_gen提供了一个API和工具,这些API和工具可在build上轻松使用,以使常见任务更容易且对开发人员更友好. 例如, PartBuilder类包装一个或多个Generator实例以创建一个Builder ,该Builder创建文件的part of ,而LibraryBuilder类包装单个Generator来Builder一个Builder ,该Builder可以创建Dart库文件.

by  ICOPY.SITE