From 3b0bde2db0680bd02e6612fa92811cdae6945132 Mon Sep 17 00:00:00 2001 From: Jaden Peterson Date: Mon, 26 Aug 2024 13:59:08 -0400 Subject: [PATCH] Updated the documentation accordingly Removed an outdated comment about generating documentation, since `scripts/gen-docs.sh` no longer exists. I also removed docs/configure_zinc_scala.md`, since the rest of our autogenerated documentation has been deleted. --- CONTRIBUTING.md | 8 --- README.md | 2 +- docs/configure_zinc_scala.md | 89 ---------------------------------- docs/newdocs/scala_versions.md | 72 +++++++++++++++++---------- docs/scala.md | 2 +- 5 files changed, 49 insertions(+), 124 deletions(-) delete mode 100644 docs/configure_zinc_scala.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9a9ba409..88604dc51 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 a19717c82..4f81432aa 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 a2d907bef..000000000 --- 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 73d66a022..ecaa2cb58 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 4f320cdee..330f4cb97 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`.