add example for multi-arch binary (#160)

Documentation for bazelbuild/bazel#5575

Note - this logic isn't actually released in bazel yet but I think it's fine to document it prematurely.

.bazelci/presubmit.yml

@@ -140,6 +140,8 @@ tasks:
     working_directory: rules
     build_targets:
     - "..."
+    # TODO(#160) renable this target when split_attr logic is released
+    - "-//starlark_configurations/multi_arch_binary:foo"
     test_targets:
     - "..."
   rules-macos:
@@ -148,6 +150,8 @@ tasks:
     working_directory: rules
     build_targets:
     - "..."
+    # TODO(#160) renable this target when split_attr logic is released
+    - "-//starlark_configurations/multi_arch_binary:foo"
     test_targets:
     - "..."
   rules-windows:
@@ -156,6 +160,8 @@ tasks:
     working_directory: rules
     build_targets:
     - "..."
+    # TODO(#160) renable this target when split_attr logic is released
+    - "-//starlark_configurations/multi_arch_binary:foo"
     # TODO(bazel-team): Make runfiles examples work on Windows.
     - "-//runfiles/..."
     # TODO(bazel-team): Make //test_rule:80columns work on Windows

rules/starlark_configurations/multi_arch_binary/BUILD

@@ -0,0 +1,10 @@
+load(":defs.bzl", "foo_binary", "simple")
+
+# Defines a rule where its `tool` dependency will be built
+# for multiple cpus
+foo_binary(
+    name = 'foo',
+    tool = ':blah',
+)
+
+simple(name = 'blah')

rules/starlark_configurations/multi_arch_binary/README.md

@@ -0,0 +1,10 @@
+This is an example of how to write a rule that builds a dependency for more than one
+architecture. It covers the following topics:
+- defining a (split or 1:2+) transition
+- attaching a transition to a rule
+- reading the transitioned
+
+To test it out, cd to this directory and run the following:
+```
+$ bazel build :foo
+```

rules/starlark_configurations/multi_arch_binary/defs.bzl

@@ -0,0 +1,57 @@
+def _transition_impl(settings, attr):
+    _ignore = [settings, attr]
+
+    # Return a dict of dicts. The values are the updates to the configuration.
+    # The keys are arbitrary helpful strings that can be used to access the split
+    # targets in the rule context
+    #
+    # Returning a dict of dicts creates a "split transition", which transitions
+    # the dep it's attached to to more than one configuration creating multiple
+    # configured targets. For more info on "split" transitions:
+    # https://docs.bazel.build/versions/master/skylark/config.html#defining-12-transitions
+    return {
+        "x86-platform": {"//command_line_option:cpu": "x86"},
+        "armeabi-v7a-platform": {"//command_line_option:cpu": "armeabi-v7a"}
+	}
+
+
+fat_transition = transition(
+    implementation = _transition_impl,
+    inputs = [],
+    outputs = ["//command_line_option:cpu"]
+)
+
+def _rule_impl(ctx):
+    # Access the split dependencies via `ctx.split_attr.<split-attr-name>`
+    tools = ctx.split_attr.tool
+    # The values of `x86_dep` and `armeabi-v7a_dep` here are regular
+    # dependencies with providers. These keys are pulled from the dict
+    # returned by the transition above. 
+    x86_dep = tools['x86-platform']
+    armeabi_v7a_dep = tools['armeabi-v7a-platform']
+    print("tool 'x86-platform' dep: " + x86_dep[CpuInfo].value)
+    print("tool 'armeabi-v7a-platform' dep: " + armeabi_v7a_dep[CpuInfo].value)
+    return []
+
+foo_binary = rule(
+  implementation = _rule_impl,
+  attrs = {
+    "tool": attr.label(cfg = fat_transition),
+    # This attribute is required to use starlark transitions. It allows 
+    # whitelisting usage of this rule. For more information, see
+    # https://docs.bazel.build/versions/master/skylark/config.html#user-defined-transitions
+    '_whitelist_function_transition': attr.label(
+        default = '@bazel_tools//tools/whitelists/function_transition_whitelist',
+    )
+  }
+)
+
+CpuInfo = provider(fields = ["value"])
+
+def _impl(ctx):
+    # Get the current cpu using `ctx.var` which contains a 
+    # dict of configuration variable
+    # https://docs.bazel.build/versions/master/skylark/lib/ctx.html#var
+    return CpuInfo(value = "--cpu=" + ctx.var["TARGET_CPU"])
+
+simple = rule(_impl)