diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e9a9ba40..88604dc5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,14 +2,6 @@
Contributions should follow the [principals](../README.md#principals) of rules_scala_annex.
-## Documentation
-
-To generate the [Stardoc](https://github.com/bazelbuild/skydoc),
-
-```
-$ ./scripts/gen-docs.sh
-```
-
## Formatting
[Buildifier](https://github.com/bazelbuild/buildtools/blob/master/buildifier) is used to format Skylark files,
diff --git a/README.md b/README.md
index a19717c8..4f81432a 100644
--- a/README.md
+++ b/README.md
@@ -74,7 +74,7 @@ load("@rules_scala_annex//rules/scala:workspace.bzl", "scala_register_toolchains
scala_repositories()
load("@annex//:defs.bzl", annex_pinned_maven_install = "pinned_maven_install")
annex_pinned_maven_install()
-scala_register_toolchains()
+scala_register_toolchains(default_scala_toolchain_name = "zinc_3")
load("@rules_scala_annex//rules/scalafmt:workspace.bzl", "scalafmt_default_config", "scalafmt_repositories")
scalafmt_repositories()
diff --git a/docs/configure_zinc_scala.md b/docs/configure_zinc_scala.md
deleted file mode 100644
index a2d907be..00000000
--- a/docs/configure_zinc_scala.md
+++ /dev/null
@@ -1,89 +0,0 @@
-
-
-## configure_zinc_scala
-
-
-configure_zinc_scala(name, compiler_bridge, compiler_classpath, deps_direct, deps_used, global_plugins, global_scalacopts, runtime_classpath, version)
-
-
-
-
-### Attributes
-
-
-
-
-
-
-
-
- name |
-
- Name; required
-
- A unique name for this target.
-
- |
-
-
- compiler_bridge |
-
- Label; required
- |
-
-
- compiler_classpath |
-
- List of labels; required
- |
-
-
- deps_direct |
-
- String; optional
-
- Options are error and off.
-
- |
-
-
- deps_used |
-
- String; optional
-
- Options are error and off.
-
- |
-
-
- global_plugins |
-
- List of labels; optional
-
- Scalac plugins that will always be enabled.
-
- |
-
-
- global_scalacopts |
-
- List of strings; optional
-
- Scalac options that will always be enabled.
-
- |
-
-
- runtime_classpath |
-
- List of labels; required
- |
-
-
- version |
-
- String; required
- |
-
-
-
diff --git a/docs/newdocs/scala_versions.md b/docs/newdocs/scala_versions.md
index 73d66a02..ecaa2cb5 100644
--- a/docs/newdocs/scala_versions.md
+++ b/docs/newdocs/scala_versions.md
@@ -1,33 +1,40 @@
## Specifying the Scala version to use
-The scala version used by a buildable target is specified via the `ScalaConfiguration` passed in to the rule's `scala` attribute.
+We use a [toolchain](https://bazel.build/extending/toolchains) to store compiler configuration,
+which includes:
+- Which compiler to use
+- What compile-time and runtime dependencies to add
+- What compiler plugins and options to use
+- Which Zinc compiler bridge to use
+- etc.
-This attribute defaults to using the `default_scala` specified via `bind` in the `WORKSPACE` file of the repo. For example, suppose the `ScalaConfiguration` you wish to default to is defined by `//scala:2_13`. In your `WORKSPACE`, you would include:
+We provide two macros for defining Scala toolchains: `register_bootstrap_toolchain` and
+`register_zinc_toolchain`, both of which are in `@rules_scala_annex//rules/register_toolchain.bzl`.
+The latter requires the former.
+Once you've registered both types of toolchains, you'll need to tell Bazel about them and set the
+default one (which we recommend is a Zinc toolchain so you can get things like
+unused/undeclared dependency checking and test code coverage checking) via the
+`scala_register_toolchains` repository rule. Something like this should work, assuming this
+repository is mapped to `rules_scala_annex`:
+
+*/BUILD.bazel*
```python
-bind(
- name = "default_scala",
- actual = "//scala:2_13",
+load(
+ "@rules_scala_annex//rules/register_toolchain.bzl",
+ "register_bootstrap_toolchain",
+ "register_zinc_toolchain",
)
-```
-
-We provide two means of creating the `ScalaConfiguration`: `configure_bootstrap_scala` and `configure_zinc_scala`. The former is required by the latter.
-
-Example:
-```python
compiler_classpath_2_13 = [
"@scala_compiler_2_13//jar",
"@scala_library_2_13//jar",
"@scala_reflect_2_13//jar",
]
-runtime_classpath_2_13 = [
- "@scala_library_2_13//jar",
-]
+runtime_classpath_2_13 = ["@scala_library_2_13//jar"]
-# This creates a basic ScalaConfiguration that relies on the scalac compiler
-configure_bootstrap_scala(
+register_bootstrap_toolchain(
name = "bootstrap_2_13",
compiler_classpath = compiler_classpath_2_13,
runtime_classpath = runtime_classpath_2_13,
@@ -38,10 +45,8 @@ configure_bootstrap_scala(
# compiler bridge needed to configure zinc compiler
scala_library(
name = "compiler_bridge_2_13",
- srcs = [
- "@compiler_bridge_2_13//:src",
- ],
- scala = ":bootstrap_2_13",
+ srcs = ["@compiler_bridge_2_13//:src"],
+ scala_toolchain_name = "bootstrap_2_13",
visibility = ["//visibility:public"],
deps = compiler_classpath_2_13 + [
"@scala_annex_org_scala_sbt_compiler_interface//jar",
@@ -50,7 +55,7 @@ scala_library(
)
# This augments the configuration to configure the zinc compiler
-configure_zinc_scala(
+register_zinc_toolchain(
name = "zinc_2_13",
compiler_bridge = ":compiler_bridge_2_13",
compiler_classpath = compiler_classpath_2_13,
@@ -60,7 +65,24 @@ configure_zinc_scala(
)
```
-It is possible to use a different `ScalaConfiguration` on different build targets. All you need to do is specify a different one in the `scala` attribute. If no `scala` attribute is specified, the `default_scala` bound to in your `WORKSPACE` is used.
+*/WORKSPACE*
+```python
+load("@rules_scala_annex//rules/scala:workspace.bzl", "scala_register_toolchains")
+
+...
+
+scala_register_toolchains(
+ toolchains = ["//:bootstrap_2_13", "//:zinc_2_13"],
+ default_scala_toolchain_name = "zinc_2_13",
+)
+
+...
+```
+
+Take note of the `scala_toolchain_name` attribute on `scala_library` and the other Scala rules. Each
+toolchain that's registered via `scala_register_toolchains` is identified by its `name`. Individual
+Scala targets can be made to use a particular toolchain by setting their `scala_toolchain_name`
+attribute.
For example:
@@ -68,16 +90,16 @@ For example:
scala_library(
name = "example_compiled_with_scalac",
srcs = glob(["**/*.scala"])
- scala = ":bootstrap_2_13
+ scala_toolchain_name = "bootstrap_2_13",
)
scala_library(
name = "example_compiled_with_zinc",
srcs = glob(["**/*.scala"])
- scala = ":zinc_2_13
+ scala_toolchain_name = "zinc_2_13",
)
-# This would use whatever //external:default_scala points to (i.e. what you bind default_scala to in your WORKSPACE)
+# This would use the default toolchain, which we configured via `scala_register_toolchains` above
scala_library(
name = "example_compiled_with_default_scala",
srcs = glob(["**/*.scala"])
diff --git a/docs/scala.md b/docs/scala.md
index 4f320cde..330f4cb9 100644
--- a/docs/scala.md
+++ b/docs/scala.md
@@ -42,7 +42,7 @@ Each define may have a value of:
Failed checks emit suggested [buildozer](https://github.com/bazelbuild/buildtools/tree/master/buildozer) commands.
-You may also toggle deps check via [configure_zinc_scala](configure_zinc_scala.md):
+You may also toggle deps check via `register_zinc_toolchain`:
* `deps_direct` - Work the same as `scala_deps_direct`.
* `deps_used` - Work the same as `scala_deps_used`.