Dart rules for Bazel

This is an unofficial set of rules for using Dart with Bazel.

Support is limited to:

• Bazel 7 using WORKSPACE and Bzlmod;
• ARM64 Macs¹, Intel Macs, or Linux x64.

In addition, only Dart 3.3.1 is tested on CI.

Installation

Bzlmod is required to use these rules.

New to Bazel?

Install bazelisk: https://github.com/bazelbuild/bazelisk. To get started:

touch WORKSPACE.bazel
touch BUILD.bazel
echo "7.2.0" > .bazelversion

bazel --version

You'll also want to become failiar with the Bazel documentation, and/or check out our examples for a quick start, as the rest of the documentation assumes you have a basic understanding of Bazel.

Add Dependency

Add the following to your MODULE.bazel file to use dev_lurey_rules_dart:

bazel_dep(
    name = "dev_lurey_rules_dart",
    version = "0.0.0",
)

# This package is not yet published, so you must use an override.
# See also: https://bazel.build/rules/lib/globals/module.
git_override(
    module_name = "dev_lurey_rules_dart",
    remote = "https://github.com/matanlurey/rules_dart",
    # TODO: Pin to a specific commit.
    # commit = '...',
)

dart = use_extension("@dev_lurey_rules_dart//dart:extensions.bzl", "dart")
dart.toolchain(
    name = "dart",
    version = "3.3.1",
)

Rules

Build rules for Dart.

load(
    "@dev_lurey_rules_dart//dart:defs.bzl",
    "dart_binary",
    "dart_library",
    "dart_package_config",
)

Tip

For tested example usage, see the examples.

dart_binary

Creates a new Dart binary target, which can be run using bazel run.

// example.dart
void main() {
  print('Hello, World!');
}

# BUILD.bazel
load("@dev_lurey_rules_dart//dart:defs.bzl", "dart_binary")

dart_binary(
    name = "example",
    main = "example.dart",
)

$ bazel run :example
> Hello, World!

Argument	Description
name	The name of the target (required).
main	The entrypoint Dart file (required).
srcs	Additional source files to include in the binary. For a binary target, this is typically not needed.
deps	Dependencies (dart_library) required to run the binary.
packages	dart_package_config target to resolve package URIs. A default package config is generated if not provided.

dart_library

Creates a new Dart library target, which can be imported by other Dart code.

// example.dart
class Example {}

# BUILD.bazel
load("@dev_lurey_rules_dart//dart:defs.bzl", "dart_library")

dart_library(
    name = "example",
    srcs = ["example.dart"],
)

Argument	Description
name	The name of the target (required).
srcs	The source files to include in the library (required).
deps	Dependencies (dart_library) used by the library.

dart_package_config

Specifies a Dart package configuration file.

# BUILD.bazel
load("@dev_lurey_rules_dart//dart:defs.bzl", "dart_package_config")

dart_package_config(
    name = "package_config",
    src = ":package_config.json",
)

Argument	Description
name	The name of the target (required).
src	The path to the package_config.json file (required).

dart_package_config_gen

Generates a package_config.json file given a (transitive) list of dependencies.

# BUILD.bazel
load("@dev_lurey_rules_dart//dart:defs.bzl", "dart_package_config_gen")

dart_package_config_gen(
    name = "package_config",
    deps = [
        "//packages/foo",
    ],
)

[!INFO] Dart package names are not the same as Bazel targets, and are automatically named by a naive heurustic based on the Bazel package's path:

• A library within your repository: Replace / with .

  For example, //packages/foo becomes packages.foo.

• A library within from a remote repository: Use the package name.

  For example, @collection becomes collection.

Argument	Description
name	The name of the target (required).
deps	A list of dependencies to include in the package config.

Extensions

Module extensions for the Dart ecosystem, in this case interaction with pub.

pub = use_extension(
    "@dev_lurey_rules_dart//dart/extensions:pub.bzl",
    "pub",
)

pub.package

Downloads a Dart package from the pub.dev repository.

pub.package(
    name = "foo",
    version = "1.2.3",
    sha256 = "...",
    build_file = "//packages:foo.BUILD",
)

Argument	Description
name	The name of the package (required).
version	The version of the package to download (required).
sha256	The SHA256 hash of the package archive (required).
build_file	The path to the BUILD.bazel file for the package (required).

Contributing

Follow the official style guide at https://bazel.build/rules/deploying.

To automatically generate (some) parts of BUILD.bazel files:

bazel run //:gazelle update

To format the rules:

bazel run //:buildifier.fix

To run the tests:

bazel test //...

Adding a new version

See versions.bzl.

See also

• https://github.com/bazel-contrib/rules-template
• https://github.com/bazelbuild/examples/tree/main/rules

Footnotes

1. I develop on an ARM64 Mac, but it not running on CI. ↩