Writing Rules

my_rule = rule(
    implementation = _my_rule_impl,
    attrs = { ... },
    ...
)

genrule(
    name = "tar_genrule",
    srcs = [
        ":fixture1",
        "src_file",
    ],
    outs = ["1.tar"],
    cmd = "$(BSDTAR_BIN) --create --dereference --file $@ -s '#$(BINDIR)##' $(execpath :fixture1) $(execpath src_file)",
    toolchains = ["@bsd_tar_toolchains//:resolved_toolchain"],
)

assert_archive_contains(
    name = "test_genrule",
    archive = "1.tar",
    expected = [
        "lib/tests/tar/a",
        "lib/tests/tar/src_file",
    ],
)

# Declare the attributes our rule accepts in the public API
_attrs = {
    "args": attr.string_list(
        doc = "Additional flags permitted by the tool; see the man page.",
    ),
    "srcs": ...
}

# A factory function to create actions.
# This might be useful for someone who wants to reuse it in some other context.
def _run_action(ctx, executable, inputs, arguments, outputs):
    # At some point it calls through to one of these functions
    ctx.actions.run()
    ctx.actions.run_shell(cmd = "bash -c ...")

# The implementation function takes a rule context argument and adapts the attributes to the
# form needed by the action.
def _my_rule_impl(ctx):
    inputs = ctx.attr.srcs[:]
    args = ctx.attr.args()
    outputs = [ctx.outputs.my_out]

    if ctx.attr.interesting:
        args.add("--interesting=" + ctx.file.interesting.path)
        inputs.append(ctx.file.interesting)

    _run_action(
        ctx,
        executable = some_binary,
        inputs = inputs,
        arguments = args,
        outputs = outputs,
    )

    # Must return a list of Providers.
    return [
        # This is the common provider that results in outputs printed by the CLI
        DefaultInfo(files = depset(outputs), runfiles = ctx.runfiles(outputs))
    ]

# Expose a Starlark library from this module
my_lib = struct(
    attrs = _attrs,
    implementation = _my_rule_impl,
)

tar = rule(
    doc = "Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly.",
    implementation = tar_lib.implementation,
    attrs = tar_lib.attrs,
    toolchains = ["@aspect_bazel_lib//lib:tar_toolchain_type"],
)

load("//lib/private:tar.bzl", _tar = "tar")

tar_rule = _tar

def tar(name, mtree = "auto", **kwargs):
    # The leading underscore implies this is a "private" target
    mtree_target = "_{}.mtree".format(name)

    # Polymorphic attribute type
    if mtree == "auto":
        mtree_spec(
            name = mtree_target,
            srcs = kwargs["srcs"],
            out = "{}.txt".format(mtree_target),
        )
    elif types.is_list(mtree):
        write_file(
            name = mtree_target,
            out = "{}.txt".format(mtree_target),
            # Ensure there's a trailing newline, as bsdtar will ignore a last line without one
            content = mtree + [""],
        )
    else:
        mtree_target = mtree

    tar_rule(
        name = name,
        mtree = mtree_target,
        **kwargs
    )