build_config 0.2.2+1

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 91

Customizing builds

Customizing the build behavior of a package is done by creating a build.yaml file, which describes your configuration.

Dividing a package into Build targets

When a Builder should be applied to a subset of files in a package the package can be broken up into multiple 'targets'. Targets are configured in the targets section of the build.yaml. The key for each target makes up the name for that target. Targets can be referred to in '$definingPackageName:$targetname'. When the target name matches the package name it can also be referred to as just the package name. One target in every package must use the package name so that consumers will use it by default. In the build.yaml file this target can be defined with the key $default or with the name of the package.

Each target may also contain the following keys:

  • sources: List of Strings or Map, Optional. The set of files within the package which make up this target. Files are specified using glob syntax. If a List of Strings is used they are considered the 'include' globs. If a Map is used can only have the keys include and exclude. Any file which matches any glob in include and no globs in exclude is considered a source of the target. When include is omitted every file is considered a match.
  • dependencies: List of Strings, Optional. The targets that this target depends on. Strings in the format '$packageName:$targetName' to depend on a target within a package or $packageName to depend on a package's default target. By default this is all of the package names this package depends on (from the pubspec.yaml).
  • builders: Map, Optional. See "configuring builders" below.

Configuring Builders applied to your package

Each target can specify a builders key which configures the builders which are applied to that target. The value is a Map from builder to configuration for that builder. The key is in the format '$packageName|$builderName'. The configuration may have the following keys:

  • enabled: Boolean, Optional: Whether to apply the builder to this target. Omit this key if you want the default behavior based on the builder's auto_apply configuration. Builders which are manually applied (auto_apply: none) are only ever used when there is a target specifying the builder with enabled: True.
  • generate_for: List of String or Map, Optional:. The subset of files within the target's sources which should have this Builder applied. See sources configuration above for how to configure this.
  • options: Map, Optional: A free-form map which will be passed to the Builder as a BuilderOptions when it is constructed. Usage varies depending on the particular builder.

Defining Builders to apply to dependents (similar to transformers)

If users of your package need to apply some code generation to their package, then you can define Builders and have those applied to packages with a dependency on yours.

The key for a Builder will be normalized so that consumers of the builder can refer to it in '$definingPackageName|$builderName' format. If the builder name matches the package name it can also be referred to with just the package name.

Exposed Builders are configured in the builders section of the build.yaml. This is a map of builder names to configuration. Each builder config may contain the following keys:

  • target: The name of the target which defines contains the Builder class definition.
  • import: Required. The import uri that should be used to import the library containing the Builder class. This should always be a package: uri.
  • builder_factories: A List<String> which contains the names of the top-level methods in the imported library which are a function fitting the typedef Builder factoryName(List<String> args).
  • build_extensions: Required. A map from input extension to the list of output extensions that may be created for that input. This must match the merged buildExtensions maps from each Builder in builder_factories.
  • auto_apply: Optional. The packages which should have this builder automatically to applied. Defaults to 'none' The possibilities are:
    • "none": Never apply this Builder unless it is manually configured
    • "dependents": Apply this Builder to the package with a direct dependency on the package exposing the builder.
    • "all_packages": Apply this Builder to all packages in the transitive dependency graph.
    • "root_package"; Apply this Builder only to the top-level package.
  • required_inputs: Optional, list of extensions. If a Builder must see every input with one or more file extensions they can be specified here and it will be guaranteed to run after any Builder which might produce an output of that type. For instance a compiler must run after any Builder which can produce .dart outputs or those libraries can't be compiled. This option should be rare. Defaults to an empty list.
  • is_optional: Optional, boolean. Specifies whether a Builder can be run lazily, such that it won't execute until one of it's outputs is requested by a later Builder. This option should be rare. Defaults to False.
  • build_to: Optional. The location that generated assets should be output to. The possibilities are:
    • "source": Outputs go to the source tree next to their primary inputs.
    • "cache": Outputs go to a hidden build cache and won't be published. The default is "cache". If a Builder specifies that it outputs to "source" it will never run on any package other than the root - but does not necessarily need to use the "root_package" value for "auto_apply". If it would otherwise run on a non-root package it will be filtered out.
  • defaults: Optional: Default values to apply when a user does not specify the corresponding key in their builders section. May contain the following keys:
    • generate_for: A list of globs that this Builder should run on as a subset of the corresponding target, or a map with include and exclude lists of globs.

Example builders config:

targets:
  # The target containing the builder sources.
  _my_builder: # By convention, this is private
    sources:
      - "lib/src/builder/**/*.dart"
      - "lib/builder.dart"
    dependencies:
      - "build"
      - "source_gen"
builders:
  # The actual builder config.
  my_builder:
    target: ":_my_builder"
    import: "package:my_package/builder.dart"
    builder_factories: ["myBuilder"]
    build_extensions: {".dart": [".my_package.dart"]}
    auto_apply: dependents

Publishing build.yaml files

build.yaml configuration should be published to pub with the package and checked in to source control. Whenever a package is published with a build.yaml it should mark a dependency on build_config to ensure that the package consuming the config has a compatible version. Breaking version changes which do not impact the configuration file format will be clearly marked in the changelog.

0.2.2+1

  • Expand support for package:build to include version 0.12.0.

0.2.2

  • Bug fix: Empty build.yaml files no longer fail to parse.
  • Allow $default as a target name to get he package name automatically filled in.

0.2.1

  • Change the default for BuilderDefinition.buildTo to BuildTo.cache. Builders which want to operate on the source tree will need to explicitly opt in. Allow this regardless of the value of autoApply and the build system will need to filter out the builders that can't run.
  • By default including any configuration for a Builder within a BuildTarget will enabled that builder.

0.2.0

  • Add build_to option to Builder configuration.
  • Add BuildConfig.fromBuildConfigDir for cases where the package name and dependencies are already known.
  • Add TargetBuilderConfig class to configure builders applied to specific targets.
  • Add TargetBuilderConfigDefaults class for Builder authors to provide default configuration.
  • Add InputSet and change sources and generate_for to use it.
  • Remove BuildTarget.isDefault and related config parsing. The default will be determined by the target which matches the package name.
  • Normalize Target and Builder names so they are scoped to the package they are defined in.

Breaking

  • Remove BuildConfigSet class. This was unused.
  • Hide Pubspec class. Construct BuildConfig instances with a package path rather than an already created Pubspec instance.

0.1.1

  • Add auto_apply option to Builder configuration.
  • Add required_inputs option to Builder configuration.
  • Add is_optional option to Builder configuration.

0.1.0

  • Initial release - pulled from package:dazel. Updated to support build_extensions instead of input_extension and output_extensions.

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  build_config: "^0.2.2+1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:build_config/build_config.dart';
        
Version Uploaded Documentation Archive
0.2.2+1 Jan 18, 2018 Go to the documentation of build_config 0.2.2+1 Download build_config 0.2.2+1 archive
0.2.2 Jan 18, 2018 Go to the documentation of build_config 0.2.2 Download build_config 0.2.2 archive
0.2.1 Dec 22, 2017 Go to the documentation of build_config 0.2.1 Download build_config 0.2.1 archive
0.2.0 Dec 21, 2017 Go to the documentation of build_config 0.2.0 Download build_config 0.2.0 archive
0.1.1 Nov 30, 2017 Go to the documentation of build_config 0.1.1 Download build_config 0.1.1 archive
0.1.0 Nov 14, 2017 Go to the documentation of build_config 0.1.0 Download build_config 0.1.0 archive

Analysis

This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • completed on Jan 21, 2018
  • Dart: 2.0.0-dev.15.0
  • pana: 0.10.0

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
82 / 100
Health:
Code health derived from static analysis. [more]
100 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
91

Platforms

Detected platforms: Flutter, other

Primary library: package:build_config/build_config.dart.

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use build_config.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.22.1 <2.0.0
build >=0.11.2 <0.13.0 0.12.0
meta ^1.1.0 1.1.2
path ^1.4.0 1.5.1
yaml ^2.1.11 2.1.13
Transitive dependencies
analyzer 0.30.0+4 0.31.0-alpha.2
args 1.2.0
async 2.0.3
charcode 1.1.1
cli_util 0.1.2+1
collection 1.14.5
convert 2.0.1
crypto 2.0.2+1
csslib 0.14.1
front_end 0.1.0-alpha.4.1 0.1.0-alpha.7
glob 1.1.5
html 0.13.2+2
isolate 1.1.0
kernel 0.3.0-alpha.1.1 0.3.0-alpha.4
logging 0.11.3+1
package_config 1.0.3
plugin 0.2.0+2
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.5
utf 0.9.0+3
watcher 0.9.7+6
Dev dependencies
test ^0.12.24