copy hlopko@'s platforms examples to this repo

CODEOWNERS

@@ -1,2 +1,4 @@
-* @laurentlb @brandjon @c-parsons @spomorski
+* @laurentlb @brandjon @c-parsons @aiuto
 android/ @ahumesky @jin
+tutorial/android/ @ahumesky @jin
+platforms/ @hlopko @katre @agoulti

platforms/.gitignore

@@ -0,0 +1 @@
+bazel-*

platforms/BUILD

@@ -0,0 +1,37 @@
+# Platform describing a Linux machine. Depending on whether we pass it as
+# `--platform` or `--host_platform` we tell Bazel if we care about targetting or
+# execution.
+platform(
+    name = "linux_platform",
+    constraint_values = [
+        "@platforms//os:linux",
+        "//yolo:yolo_lang_1",
+    ],
+)
+
+# Similarly to the linux platform, this is a platform describing a Windows
+# machine.
+platform(
+    name = "windows_platform",
+    constraint_values = [
+        "@platforms//os:windows",
+        "//yolo:yolo_lang_1",
+    ],
+)
+
+# Similarly to the linux platform, this is a platform describing Android.
+platform(
+    name = "android_platform",
+    constraint_values = [
+        "@platforms//os:android",
+    ],
+)
+
+# Platform describing a Linux machine with yolo-lang 3.
+platform(
+    name = "linux_yolo_3_platform",
+    constraint_values = [
+        "@platforms//os:linux",
+        "//yolo:yolo_lang_3",
+    ],
+)

platforms/README.md

@@ -0,0 +1,44 @@
+# Bazel Platforms Examples
+
+*This repo requires Bazel 0.28 or later (or built from HEAD).*
+
+This repo contains a collection of examples demonstrating how to use various
+Bazel concepts related to
+[platforms](https://docs.bazel.build/versions/master/platforms.html),
+[toolchains](https://docs.bazel.build/versions/master/toolchains.html),
+[configurations](https://docs.bazel.build/versions/master/skylark/config.html),
+and [configurable
+attributes](https://docs.bazel.build/versions/master/configurable-attributes.html).
+
+It also tries to give guidance when each of these concepts is used and should
+accompany documentation on [bazel.build](https://bazel.build). Be sure to use
+[`--toolchain_resolution_debug`](https://docs.bazel.build/versions/master/command-line-reference.html#flag--toolchain_resolution_debug)
+where the resolution isn't obvious.
+
+## Structure
+
+```
+├── .bazelrc      # Setting defaults until https://github.com/bazelbuild/bazel/issues/7081 is fixed.
+│
+├── WORKSPACE     # Here we define @platforms repo with constraints. We use common
+│                 # constraints repository from
+│                 # https://github.com/bazelbuild/platforms. We also register
+│                 # toolchains and we register execution platforms there.
+│
+├── BUILD         # Here we define all needed 'platform' targets that we then use
+│                 # in examples.
+│
+├── examples      # Actual examples, one per subpackage.
+│
+└── yolo          # Yolo-lang rules definition.
+    │
+    ├── BUILD     # Here we define all 'toolchain' targets that we then use in
+    │             # in examples.
+    │
+    └── defs.bzl
+```
+
+`Yolo-lang` here is obviously not a real programming language, it's just a
+simple implementation of Bazel Starlark rules that is meant to demonstrate
+examples without confusing us with technical details.
+

platforms/WORKSPACE

@@ -0,0 +1,27 @@
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "platforms",
+    sha256 = "a07fe5e75964361885db725039c2ba673f0ee0313d971ae4f50c9b18cd28b0b5",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/platforms/archive/441afe1bfdadd6236988e9cac159df6b5a9f5a98.zip",
+        "https://github.com/bazelbuild/platforms/archive/441afe1bfdadd6236988e9cac159df6b5a9f5a98.zip",
+    ],
+    strip_prefix = "platforms-441afe1bfdadd6236988e9cac159df6b5a9f5a98"
+)
+http_archive(
+    name = "bazel_skylib",
+    url = "https://github.com/bazelbuild/bazel-skylib/archive/b113ed5d05ccddee3093bb157b9b02ab963c1c32.zip",
+    sha256 = "cea47b31962206b7ebf2088f749243868d5d9305273205bdd8651567d3e027fc",
+    strip_prefix = "bazel-skylib-b113ed5d05ccddee3093bb157b9b02ab963c1c32",
+)
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+bazel_skylib_workspace()
+
+# Tell Bazel about our toolchains so it can resolve them based on values passed
+# in --platform, --host_platform, and --execution_platforms options.
+register_toolchains("//yolo:all")
+
+# Tell Bazel that //:linux_platform is allowed execution platform - that our
+# host system or remote execution service can handle that platform.
+register_execution_platforms("//:linux_platform")

platforms/examples/01_hello_world/BUILD

@@ -0,0 +1,5 @@
+load("//yolo:defs.bzl", "yolo_library")
+
+yolo_library(
+    name = "a",
+)

platforms/examples/01_hello_world/README.md

@@ -0,0 +1,31 @@
+# Example 01: Hello World
+
+Example demonstrating a workspace with toolchains and platforms setup.
+
+## Commands
+
+```
+bazel build //examples/01_hello_world:a
+
+>   yolo_library(
+>     name = 'a',
+>     toolchain = {
+>       'targetting_cpu': 'host',
+>       'targetting_os': 'host',
+>       'executing_on_cpu': 'host',
+>       'executing_on_os': 'host',
+>     },
+>   )
+```
+
+## Description
+
+There are a few relevant pieces that have to click in for this example to work.
+Be sure to look into top-level `WORKSPACE`, `BUILD`, `yolo/BUILD`, and
+`.bazelrc` files.
+
+We don't tell Bazel which `--platforms` to use, so Bazel takes its defaults, which is
+the autodetected host platform at `@local_config_platform//:host`. Bazel selects
+the first toolchain that matches that platform. Our toolchain
+`//yolo:host_toolchain` has exactly the same constraints, and it indeed matches
+and Bazel selected it.

platforms/examples/02_using_different_platforms/BUILD

@@ -0,0 +1,5 @@
+load("//yolo:defs.bzl", "yolo_library")
+
+yolo_library(
+    name = "a",
+)

platforms/examples/02_using_different_platforms/README.md

@@ -0,0 +1,42 @@
+# Example 02: Using different platforms
+
+Example demonstrating how different toolchains are selected for different
+platforms.
+
+## Commands
+
+```
+bazel build //examples/02_using_different_platforms:a --platforms=//:linux_platform
+
+>   yolo_library(
+>     name = 'a',
+>     toolchain = {
+>       'targetting_cpu': '-',
+>       'targetting_os': 'linux',
+>       'executing_on_cpu': '-',
+>       'executing_on_os': 'linux',
+>     },
+>   )
+
+bazel build //examples/02_using_different_platforms:a --platforms=//:windows_platform
+
+>   yolo_library(
+>     name = 'a',
+>     toolchain = {
+>       'targetting_cpu': '-',
+>       'targetting_os': 'windows',
+>       'executing_on_cpu': '-',
+>       'executing_on_os': 'linux',
+>     },
+>   )
+```
+
+## Description
+
+Here we tell Bazel that we want to build
+`//examples/02_using_different_platforms:a` first for Linux, then for Windows.
+Both of these times we want to execute the build on Linux (note the call to
+`register_execution_platforms` in the `WORKSPACE` file).
+
+We see that toolchains used to build the library changed between Bazel
+invocations.

platforms/examples/03_target_not_compatible_with_constraint/BUILD

@@ -0,0 +1,11 @@
+load("//yolo:defs.bzl", "yolo_library")
+
+yolo_library(
+    name = "a",
+    exec_compatible_with = [ "@platforms//os:linux" ],
+)
+
+yolo_library(
+    name = "b",
+    exec_compatible_with = [ "@platforms//os:windows" ],
+)

platforms/examples/03_target_not_compatible_with_constraint/README.md

@@ -0,0 +1,32 @@
+# Example 03: Execution of target not compatible with constraint
+
+Example demonstrating how to express that a target can only be built on a
+platform that has a specific constraint.
+
+## Commands
+
+```
+bazel build //examples/03_target_not_compatible_with_constraint:a --platforms=//:linux_platform
+
+>   yolo_library(
+>     name = 'a',
+>     toolchain = {
+>       'targetting_cpu': '-',
+>       'targetting_os': 'linux',
+>       'executing_on_cpu': '-',
+>       'executing_on_os': 'linux',
+>     },
+>   )
+
+bazel build //examples/03_target_not_compatible_with_constraint:b --platforms=//:linux_platform
+
+>   ERROR: While resolving toolchains for target //examples/03_target_not_compatible_with_constraint:b:
+>       no matching toolchains found for types //yolo:toolchain_type
+>   ERROR: Analysis of target '//examples/03_target_not_compatible_with_constraint:b' failed;
+>       build aborted: no matching toolchains found for types //yolo:toolchain_type
+```
+
+## Description
+
+In this example we show how to prevent people from building a target on an
+unsupported platform (in this case `:b` can only be built on Windows).

platforms/examples/04_select_on_constraint/BUILD

@@ -0,0 +1,30 @@
+load("//yolo:defs.bzl", "yolo_library")
+
+package(default_visibility = ["//visibility:private"])
+
+alias(
+    name = "a",
+    actual = select({
+        ":is_windows": ":a_windows",
+        ":is_linux": ":a_linux",
+    }),
+    visibility = ["//visibility:public"],
+)
+
+config_setting(
+    name = "is_windows",
+    constraint_values = ["@platforms//os:windows"],
+)
+
+config_setting(
+    name = "is_linux",
+    constraint_values = ["@platforms//os:linux"],
+)
+
+yolo_library(
+    name = "a_windows",
+)
+
+yolo_library(
+    name = "a_linux",
+)

platforms/examples/04_select_on_constraint/README.md

@@ -0,0 +1,55 @@
+# Example 04: Select on constraint
+
+This example demonstrates how to build a target (or set it's attribute)
+differently under different configurations.
+
+## Commands
+
+```
+bazel build //examples/04_select_on_constraint:a --platforms=//:linux_platform
+
+>   yolo_library(
+>     name = 'a_linux',
+>     toolchain = {
+>       'targetting_cpu': '-',
+>       'targetting_os': 'linux',
+>       'executing_on_cpu': '-',
+>       'executing_on_os': 'linux',
+>     },
+>   )
+
+bazel build //examples/04_select_on_constraint:a --platforms=//:windows_platform
+
+>   yolo_library(
+>     name = 'a_windows',
+>     toolchain = {
+>       'targetting_cpu': '-',
+>       'targetting_os': 'windows',
+>       'executing_on_cpu': '-',
+>       'executing_on_os': 'linux',
+>     },
+>   )
+
+bazel build //examples/04_select_on_constraint:a --platforms=//:android_platform
+
+>   .../examples/04_select_on_constraint/BUILD:6:14:
+>     Configurable attribute "actual" doesn't match this configuration (would a default condition help?).
+>   Conditions checked:
+>    //examples/04_select_on_constraint:is_windows
+>    //examples/04_select_on_constraint:is_linux
+```
+
+# Description
+
+In this example we wanted select a specialized target depending on the operating
+system. We used
+[`alias`](https://docs.bazel.build/versions/master/be/general.html#alias) to
+create the entry-point target and made only that target visible to the outside.
+We used
+[`config_setting.constraint_values`](https://docs.bazel.build/versions/master/be/general.html#config_setting.constraint_values)
+attribute to select on constraint values of the currently used platform. And we
+used 
+[`select`](https://docs.bazel.build/versions/master/be/functions.html#select) to
+conditionally take the right target. Note we didn't include
+`//conditions:default` in the select. As a result, the third Bazel invocation
+fails on missing condition.

platforms/examples/05_select_on_platform/BUILD

@@ -0,0 +1,34 @@
+load("//yolo:defs.bzl", "fail_with_msg", "yolo_library")
+
+package(default_visibility = ["//visibility:private"])
+
+alias(
+    name = "a",
+    actual = select({
+        ":is_windows": ":a_windows",
+        ":is_linux": ":a_linux",
+    }),
+    visibility = ["//visibility:public"],
+)
+
+config_setting(
+    name = "is_windows",
+    values = {
+        "platforms": "//:windows_platform",
+    },
+)
+
+config_setting(
+    name = "is_linux",
+    values = {
+        "platforms": "//:linux_platform",
+    },
+)
+
+yolo_library(
+    name = "a_windows",
+)
+
+yolo_library(
+    name = "a_linux",
+)