Add extensive runfiles examples (bazelbuild#129)

Author: c-parsons

.bazelci/presubmit.yml

@@ -156,6 +156,8 @@ tasks:
     working_directory: rules
     build_targets:
     - "..."
+    # TODO(bazel-team): Make runfiles examples work on Windows.
+    - "-//runfiles/..."
     # TODO(bazel-team): Make //test_rule:80columns work on Windows
     # test_targets:
     # - "--"

rules/WORKSPACE

@@ -1,3 +1,5 @@
+workspace(name = "examples")
+
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
 http_archive(

rules/runfiles/BUILD

@@ -1,7 +1,14 @@
+load(":complex_tool.bzl", "complex_tool", "sub_tool")
 load(":execute.bzl", "execute")
+load(":library.bzl", "runfiles_library", "runfiles_binary")
+load(":tool.bzl", "tool", "tool_user")
 
-# `bazel build //runfiles:all` will create an executable.
-# `bazel run //runfiles:all` will run it.
+# Tests in this package do not currently work on Windows (as they create
+# shell-script binaries not compatible with Windows).
+
+# 1. Basic example
+# `bazel build //runfiles:e` will create an executable.
+# `bazel run //runfiles:e` will run it.
 execute(
     name = "e",
     # The location will be expanded to "pkg/data.txt", and it will reference
@@ -10,3 +17,47 @@ execute(
     command = "cat $(location :data.txt)",
     data = [":data.txt"],
 )
+
+# 2. Library runfiles
+# A library which declares a file which is needed at runtime, and a binary
+# which invokes this library without direct knowledge of its runtime requirement.
+# `bazel run //runfiles:bin` to run this example.
+runfiles_library(
+    name = "lib",
+    command = "cat $(location :data.txt)",
+    data = [":data.txt"],
+)
+runfiles_binary(
+    name = "bin",
+    lib = ":lib",
+)
+
+# 3. Tool with runfiles
+# An action may require use of a tool that needs files at runtime. This demonstrates
+# the definition of such a tool and a rule which uses that tool.
+# `bazel build //runfiles:tool_user` to build this example.
+tool(
+    name = "tool",
+)
+tool_user(
+    name = "tool_user",
+    tool = ":tool",
+)
+
+# 4. Tool with runfiles depending on another tool
+# Same as (3), except adds the complexity of a tool which depends on another tool
+# with its own runfiles. This adds complexity, as the runfiles of the "inner tool"
+# is in a different location than if the inner tool were run itself.
+# `bazel build //runfiles:complex_tool_user` to build this example.
+sub_tool(
+    name = "subtool",
+)
+complex_tool(
+    name = "complex_tool",
+)
+tool_user(
+    name = "complex_tool_user",
+    tool = ":complex_tool",
+)
+
+

rules/runfiles/complex_tool.bzl

@@ -0,0 +1,90 @@
+"""Create a complex tool with runfiles and a rule which uses it.
+
+A tool (executable used for action registration) may depend on another
+tool with its own runfiles. This example demonstrates this scenario."""
+
+def _sub_tool_impl(ctx):
+    # Since this tool may be used by another tool, it must support accepting
+    # a different runfiles directory root. The runfiles directory is always
+    # adjacent to the *root* tool being run, which may not be this tool.
+    # (In this case, this is done by environment variable RUNFILES_DIR.)
+    command = """
+if [[ -z "${RUNFILES_DIR}" ]]; then
+  RUNFILES_DIR=${0}.runfiles
+fi
+
+cat ${RUNFILES_DIR}/examples/runfiles/data.txt > $1"""
+
+    # Using root_symlinks or symlinks for a tool is very brittle if the
+    # tool may be used by another tool; there will be a collision when merging
+    # runfiles if the other tool defines a symlink of the same name as one
+    # defined by this rule.
+    ctx.actions.write(
+        output = ctx.outputs.executable,
+        content = command,
+        is_executable = True,
+    )
+
+    # Subtool depends on RUNFILES_DIR/<workspace_name>/runfiles/data.txt.
+    return [DefaultInfo(
+        runfiles = ctx.runfiles(files = [ctx.files._data[0]]),
+    )]
+
+sub_tool = rule(
+    implementation = _sub_tool_impl,
+    executable = True,
+    attrs = {
+        "command": attr.string(),
+        "_data": attr.label(
+            allow_files = True,
+            default = "//runfiles:data.txt"),
+    },
+)
+
+def _complex_tool_impl(ctx):
+    my_runfiles = ctx.runfiles(files = [ctx.files._data[0]])
+    # Use runfiles.merge to merge the runfiles of both tools. All runfiles will
+    # be rooted under the runfiles directory owned by this rule, however.
+    my_runfiles = my_runfiles.merge(ctx.attr._subtool[DefaultInfo].default_runfiles)
+
+    # Thus the example directory structure is:
+    # runfiles/complex_tool     (executable)
+    # runfiles/complex_tool.runfiles/
+    #     <workspace_name>/
+    #         runfiles/
+    #             complex_tool_data.txt
+    #             data.txt
+    #             subtool
+
+    runfiles_relative_tool_path = ctx.workspace_name + "/" + ctx.attr._subtool[DefaultInfo].files_to_run.executable.short_path
+
+    # This tool forwards its runfiles directory via the RUNFILES_DIR to the
+    # subtool, otherwise the subtool would be looking to $0.runfiles, which does
+    # not exist.
+    command = ("#!/bin/bash\nexport RUNFILES_DIR=\"$0.runfiles\" && "
+             + "${RUNFILES_DIR}/%s $1 && cat ${RUNFILES_DIR}/examples/%s >> $1") % (
+                   runfiles_relative_tool_path, ctx.files._data[0].short_path)
+
+    ctx.actions.write(
+        output = ctx.outputs.executable,
+        content = command,
+        is_executable = True,
+    )
+
+    return [DefaultInfo(
+        runfiles = my_runfiles,
+    )]
+
+complex_tool = rule(
+    implementation = _complex_tool_impl,
+    executable = True,
+    attrs = {
+        "command": attr.string(),
+        "_subtool": attr.label(
+            allow_files = True,
+            default = "//runfiles:subtool"),
+        "_data": attr.label(
+            allow_files = True,
+            default = "//runfiles:complex_tool_data.txt"),
+    },
+)

rules/runfiles/complex_tool_data.txt

@@ -0,0 +1 @@
+I like turtles

rules/runfiles/execute.bzl

@@ -18,9 +18,7 @@ def _impl(ctx):
 
     # Create runfiles from the files specified in the data attribute.
     # The shell executable - the output of this rule - can use them at
-    # runtime. It is also possible to define data_runfiles and
-    # default_runfiles. However if runfiles is specified it's not possible to
-    # define the above ones since runfiles sets them both.
+    # runtime.
     return [DefaultInfo(
         runfiles = ctx.runfiles(files = ctx.files.data),
     )]

rules/runfiles/lib.txt

@@ -0,0 +1 @@
+cat rules/runfiles/data.txt

rules/runfiles/library.bzl

@@ -0,0 +1,60 @@
+"""Create a library with runfiles and a rule which uses it.
+
+A library might need some external files during runtime, and every dependent
+binary should know about them. This demonstrates best practices for handling
+such a scenario.
+"""
+
+# When possible, use custom providers to manage propagating information
+# between dependencies and their dependers.
+RuntimeRequiredFiles = provider(fields = ["file", "data_files"])
+
+def _library_impl(ctx):
+    # Expand the label in the command string to a runfiles-relative path.
+    # The second arg is the list of labels that may be expanded.
+    command = ctx.expand_location(ctx.attr.command, ctx.attr.data)
+
+    my_out = ctx.actions.declare_file(ctx.attr.name + "_out")
+    ctx.actions.write(
+        output = my_out,
+        content = command,
+        is_executable = True,
+    )
+
+    return [
+        RuntimeRequiredFiles(file = my_out, data_files = depset(ctx.files.data)),
+    ]
+
+runfiles_library = rule(
+    implementation = _library_impl,
+    attrs = {
+        "command": attr.string(),
+        "data": attr.label_list(allow_files = True),
+    },
+    provides = [RuntimeRequiredFiles],
+)
+
+def _binary_impl(ctx):
+    # Create the output executable file, which simply runs the library's
+    # primary output file (obtained from RuntimeRequiredFiles.file).
+    ctx.actions.write(
+        output = ctx.outputs.executable,
+        content = "$(cat " + ctx.attr.lib[RuntimeRequiredFiles].file.short_path + ")",
+        is_executable = True,
+    )
+
+    my_runfiles = ctx.runfiles(
+        files = [ctx.attr.lib[RuntimeRequiredFiles].file],
+        transitive_files = ctx.attr.lib[RuntimeRequiredFiles].data_files)
+
+    return [DefaultInfo(
+        runfiles = my_runfiles
+    )]
+
+runfiles_binary = rule(
+    implementation = _binary_impl,
+    executable = True,
+    attrs = {
+        "lib": attr.label(mandatory = True, providers = [RuntimeRequiredFiles]),
+    },
+)

rules/runfiles/tool.bzl

@@ -0,0 +1,88 @@
+"""Create a tool with runfiles and a rule which uses it.
+
+A rule may register an action that uses a tool which requires external files
+during runtime. This demonstrates best practices for handling such a scenario.
+"""
+
+def _tool_impl(ctx):
+    # Runfiles expansion for tools (executables that are to be run
+    # as part of other build actions) is tricky and error-prone.
+
+    # There is a {rulename}.runfiles directory adjacent to the tool's
+    # executable file which contains all runfiles. This is not guaranteed
+    # to be relative to the directory in which the executable file is run.
+    runfiles_path = "$0.runfiles/"
+
+    # Each runfile under the runfiles path resides under a directory with 
+    # with the same name as its workspace.
+    data_file_root = runfiles_path + ctx.workspace_name + "/"
+
+    data_file_path = data_file_root + ctx.files._data[0].path
+
+    # Alternatively, one can use the root_symlinks parameter of `runfiles`
+    # to create a symlink rooted directly under the {rulename}.runfiles
+    # directory.
+    my_runfiles = ctx.runfiles(files = [ctx.files._data[0]],
+        root_symlinks = {"data_dep" : ctx.files._data[0]})
+
+    # Even root symlinks are under the runfiles path.
+    data_dep_path = runfiles_path + "data_dep"
+
+    # Thus the example directory structure is:
+    # runfiles/tool     (executable)
+    # runfiles/tool.runfiles/
+    #     data_dep   (symlink to data.txt)
+    #     <workspace_name>/
+    #         runfiles/
+    #        udata.txt
+
+    # Create the output executable file with command as its content.
+    ctx.actions.write(
+        output = ctx.outputs.executable,
+        # Simple example, effectively puts the contents of data.txt into
+        # the output twice (read once via symlink, once via normal file).
+        content = "#!/bin/bash\ncat %s %s > $1" % (data_file_path, data_dep_path),
+        is_executable = True,
+    )
+
+    return [DefaultInfo(
+        # The tool itself should just declare `runfiles`. The build
+        # system will automatically create a `files_to_run` object
+        # from the result of this declaration (used later).
+        runfiles = my_runfiles,
+    )]
+
+tool = rule(
+    implementation = _tool_impl,
+    executable = True,
+    attrs = {
+        "_data": attr.label(
+            allow_files = True,
+            default = "//runfiles:data.txt"),
+    },
+)
+
+def _tool_user_impl(ctx):
+    my_out = ctx.actions.declare_file(ctx.attr.name + "_out")
+
+    # If the tool dependency attribute was declared with `executable = True`,
+    # then the tool's file can be found under `ctx.executable.<attr_name>`.
+    # If this file is passed to `ctx.actions.run()`, the runfiles for this file
+    # are automatically added to the action.
+    tool = ctx.executable.tool
+
+    ctx.actions.run(
+        outputs = [my_out],
+        executable = tool,
+        arguments = [my_out.path]
+    )
+
+    return [DefaultInfo(files = depset([my_out]))]
+
+tool_user = rule(
+    implementation = _tool_user_impl,
+    attrs = {
+        "tool": attr.label(mandatory = True, executable = True, cfg = "host"),
+    },
+
+)