Updated the documentation

lucidsoftware · Dec 6, 2024 · 4c0ec8d · 4c0ec8d
1 parent 2868152
commit 4c0ec8d
Show file tree

Hide file tree

Showing 7 changed files with 122 additions and 126 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,27 +21,32 @@ $ ./scripts/format.sh
 
 ## Maven deps
 
-[rules_jvm_external](https://github.com/bazel-contrib/rules_jvm_external) is used to generate maven deps. If you need to change
-dependencies, modify `maven_install` in the following different `workspace.bzl` files
+[rules_jvm_external](https://github.com/bazel-contrib/rules_jvm_external) is used to resolve Maven
+dependencies. If you need to change dependencies, add your artifacts to the `annex*.install` calls
+in [`MODULE.bazel`](MODULE.bazel) or [`tests/MODULE.bazel`](tests/MODULE.bazel).
 
-```
-rules/scala/workspace.bzl
-rules/scala_proto/workspace.bzl
-rules/scalafmt/workspace.bzl
-tests/workspace.bzl
-```
-To reference the dependency, use the `name` attribute of the `maven_install` rule as the repository name and the versionless dependency as the target. E.g. `@<maven_install_name>//:<versionless_dependency>`.
+To reference the dependency, use the `name` attribute of the `annex*.install` call as the
+repository name and the versionless dependency as the target. E.g.
+`@<maven_install_name>//:<versionless_dependency>`.
 
-For example, if you'd like to add `org.scala-sbt:compiler-interface:1.2.1` as a dependency, simply add it to the `artifacts` list in `maven_install` with the attribute `name = "annex"`, and then refer to it with `@annex//:org_scala_sbt_compiler_interface`.
+For example, if you'd like to add `org.scala-sbt:compiler-interface:1.2.1` as a dependency, simply
+add it to the `artifacts` list of the `maven.install` call, and then refer to it with
+`@annex//:org_scala_sbt_compiler_interface`.
 
-```
-maven_install(
+```starlark
+annex.install(
     name = "annex",
     artifacts = [
+        ...,
         "org.scala-sbt:compiler-interface:1.2.1",
+        ...,
     ],
+    fetch_sources = True,
+    lock_file = "//:annex_install.json",
     repositories = [
         "https://repo.maven.apache.org/maven2",
+        "https://maven-central.storage-download.googleapis.com/maven2",
+        "https://mirror.bazel.build/repo1.maven.org/maven2",
     ],
 )
 ```

diff --git a/README.md b/README.md
@@ -54,81 +54,29 @@ straightforward.
 
 ## Usage
 
-WORKSPACE
+`lucidsoftware/rules_scala` isn't on the [Bazel Central Registry](https://registry.bazel.build/), so
+you'll need to pull it in via `archive_override`. Be sure to replace `<COMMIT>` with the
+latest commit on `lucid-master` and `<INTEGRITY>` with the hash suggested by Bazel after the
+dependency is first loaded.
 
-```python
-load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+MODULE.bazel
 
-# rules_java
-http_archive(
-    name = "rules_java",
-    sha256 = "a9690bc00c538246880d5c83c233e4deb83fe885f54c21bb445eb8116a180b83",
-    url = "https://github.com/bazelbuild/rules_java/releases/download/7.12.2/rules_java-7.12.2.tar.gz",
-)
+```starlark
+bazel_dep(name = "rules_scala_annex")
 
-# Load rules_scala_annex
-rules_scala_annex_version = "lucid_2024-11-18"
+rules_scala_annex_version = "<COMMIT>"
 
-http_archive(
-    name = "rules_scala_annex",
-    integrity = "sha256-WjZvojiclkiyVxQ1NqkH1lDeGaDLyzQOGiDsCfhVAec=",
+archive_override(
+    module_name = "rules_scala_annex",
+    integrity = "<INTEGRITY>",
     strip_prefix = "rules_scala-{}".format(rules_scala_annex_version),
-    type = "zip",
-    url = "https://github.com/lucidsoftware/rules_scala/archive/{}.zip".format(rules_scala_annex_version),
-)
-
-rules_jvm_external_version = "6.1"
-
-http_archive(
-    name = "rules_jvm_external",
-    sha256 = "42a6d48eb2c08089961c715a813304f30dc434df48e371ebdd868fc3636f0e82",
-    strip_prefix = "rules_jvm_external-{}".format(rules_jvm_external_version),
-    type = "zip",
-    url = "https://github.com/bazelbuild/rules_jvm_external/archive/{}.zip".format(rules_jvm_external_version),
-)
-
-load(
-    "@rules_scala_annex//rules/scala:workspace.bzl",
-    "scala_register_toolchains",
-    "scala_repositories",
-)
-
-load(
-    "@rules_scala_annex//rules/scala_proto:workspace.bzl",
-    "scala_proto_register_toolchains",
-    "scala_proto_repositories",
-)
-
-load(
-    "@rules_scala_annex//rules/scalafmt:workspace.bzl",
-    "scalafmt_default_config",
-    "scalafmt_repositories",
+    urls = ["https://github.com/lucidsoftware/rules_scala/archive/refs/heads/{}.zip".format(rules_scala_annex_version)],
 )
-
-scala_repositories()
-
-load("@annex//:defs.bzl", annex_pinned_maven_install = "pinned_maven_install")
-
-annex_pinned_maven_install()
-
-scala_register_toolchains(default_scala_toolchain_name = "annex_zinc_3")
-scalafmt_repositories()
-
-load("@annex_scalafmt//:defs.bzl", annex_scalafmt_pinned_maven_install = "pinned_maven_install")
-
-annex_scalafmt_pinned_maven_install()
-scalafmt_default_config()
-scala_proto_repositories()
-
-load("@annex_proto//:defs.bzl", annex_proto_pinned_maven_install = "pinned_maven_install")
-
-annex_proto_pinned_maven_install()
-scala_proto_register_toolchains()
 ```
 
 BUILD
 
-```python
+```starlark
 load("@rules_scala_annex//rules:scala.bzl", "scala_library")
 
 scala_library(

diff --git a/docs/newdocs/phases.md b/docs/newdocs/phases.md
@@ -3,7 +3,7 @@
 Most rules in `lucidsoftware/rules_scala` are architected using phases. Phases break down the Bazel Analysis stage into logical chunks.
 For example, the implementation of `scala_binary` is:
 
-```python
+```starlark
 def _scala_binary_implementation(ctx):
     return _run_phases(ctx, [
         ("resources", _phase_resources),

diff --git a/docs/newdocs/scala_versions.md b/docs/newdocs/scala_versions.md
@@ -19,64 +19,60 @@ unused/undeclared dependency checking and test code coverage checking) via the
 repository is mapped to `rules_scala_annex`:
 
 */BUILD.bazel*
-```python
+
+```starlark
 load(
     "@rules_scala_annex//rules/register_toolchain.bzl",
     "register_bootstrap_toolchain",
     "register_zinc_toolchain",
 )
 
+
+# You'll need to pull these in via `rules_jvm_external`. Note that `@maven` should be replaced with
+# the name of your dependency tree, as specified in the `name` attribute of `maven.install` or
+# `maven.artifact`.
 compiler_classpath_2_13 = [
-    "@scala_compiler_2_13//jar",
-    "@scala_library_2_13//jar",
-    "@scala_reflect_2_13//jar",
+    "@maven//:org_scala_lang_scala_compiler",
+    "@maven//:org_scala_lang_scala_library",
+    "@maven//:org_scala_lang_scala_reflect",
 ]
 
-runtime_classpath_2_13 = ["@scala_library_2_13//jar"]
+# You'll need to pull thus in via `rules_jvm_external`
+runtime_classpath_2_13 = ["@maven//:org_scala_lang_scala_library",]
 
 register_bootstrap_toolchain(
-    name = "annex_bootstrap_2_13",
+    name = "bootstrap_2_13",
     compiler_classpath = compiler_classpath_2_13,
     runtime_classpath = runtime_classpath_2_13,
     version = "2.13.14",
     visibility = ["//visibility:public"],
 )
 
-# compiler bridge needed to configure zinc compiler
-scala_library(
-    name = "compiler_bridge_2_13",
-    srcs = ["@compiler_bridge_2_13//:src"],
-    scala_toolchain_name = "annex_bootstrap_2_13",
-    visibility = ["//visibility:public"],
-    deps = compiler_classpath_2_13 + [
-        "@scala_annex_org_scala_sbt_compiler_interface//jar",
-        "@scala_annex_org_scala_sbt_util_interface//jar",
-    ],
-)
-
 # This augments the configuration to configure the zinc compiler
 register_zinc_toolchain(
-    name = "annex_zinc_2_13",
-    compiler_bridge = ":compiler_bridge_2_13",
+    name = "zinc_2_13",
+    # You'll need to pull this in via `rules_jvm_external`
+    compiler_bridge = "@maven//:org_scala_sbt_compiler_bridge_2_13",
     compiler_classpath = compiler_classpath_2_13,
     runtime_classpath = runtime_classpath_2_13,
     version = "2.13.14",
     visibility = ["//visibility:public"],
 )
 ```
 
-*/WORKSPACE*
-```python
-load("@rules_scala_annex//rules/scala:workspace.bzl", "scala_register_toolchains")
-
-...
+*/MODULE.bazel*
 
-scala_register_toolchains(
-    toolchains = ["//:annex_bootstrap_2_13", "//:annex_zinc_2_13"],
-    default_scala_toolchain_name = "annex_zinc_2_13",
+```starlark
+register_toolchains(
+    "//:bootstrap_2_13",
+    "//:zinc_2_13",
 )
+```
 
-...
+*/.bazelrc*
+
+```
+common --@rules_scala_annex//rules/scala:scala-toolchain=zinc_2_13
 ```
 
 Take note of the `scala_toolchain_name` attribute on `scala_library` and the other Scala rules. Each
@@ -86,22 +82,22 @@ attribute.
 
 For example:
 
-```python
+```starlark
 scala_library(
-  name = "example_compiled_with_scalac",
-  srcs = glob(["**/*.scala"])
-  scala_toolchain_name = "annex_bootstrap_2_13",
+    name = "example_compiled_with_scalac",
+    srcs = glob(["**/*.scala"])
+    scala_toolchain_name = "bootstrap_2_13",
 )
 
 scala_library(
-  name = "example_compiled_with_zinc",
-  srcs = glob(["**/*.scala"])
-  scala_toolchain_name = "annex_zinc_2_13",
+    name = "example_compiled_with_zinc",
+    srcs = glob(["**/*.scala"])
+    scala_toolchain_name = "zinc_2_13",
 )
 
 # 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"])
+    name = "example_compiled_with_default_scala",
+    srcs = glob(["**/*.scala"])
 )
 ```
diff --git a/docs/scalafmt.md b/docs/scalafmt.md
@@ -1,24 +1,68 @@
 # Scalafmt
 
-Create .scalafmt.conf at the repo root (may be empty). And add to the WORKSPACE
+`lucidsoftware/rules_scala` contains copies of the default Scala rules with formatting capabilities,
+powered by Scalafmt. See [the Stardoc on these rules](./stardoc/scala_with_scalafmt.md) for more
+information.
 
-```python
-load("@rules_scala_annex//rules/scalafmt:workspace.bzl", "scalafmt_repositories", "scalafmt_default_config")
-scalafmt_repositories()
-scalafmt_default_config()
+[Toolchains](https://bazel.build/extending/toolchains) are used to set the Scalafmt
+configuration file that's used by those targets that have formatting enabled. The default toolchain
+uses the [`.scalafmt.conf`](../.scalafmt.conf) file at the root of this repository—the same
+configuration file that's used to format this repository's code. All you need to do to use the
+formatting rules is register the default toolchain with Bazel in your `MODULE.bazel` file:
+
+```starlark
+register_toolchains("@rules_scala_annex//:annex_scalafmt")
+```
+
+That should be sufficient to get you started, but if you'd like to use your own `.scalafmt.conf`
+file, you'll need to declare your own toolchain and register it with Bazel:
+
+*/BUILD*
+
+```starlark
+load("@rules_scala_annex//rules/scalafmt:register_toolchain.bzl", "register_scalafmt_toolchain")
+
+register_scalafmt_toolchain(
+    name = "custom_scalafmt",
+    config = ".scalafmt.conf",
+)
 ```
 
-And in BUILD
+*/MODULE.bazel*
 
-```python
+```starlark
+register_toolchains(":custom_scalafmt")
+```
+
+Then, you can either:
+- Use it for every target by default by adding the
+  `--@rules_scala_annex//rules/scalafmt:scalafmt-toolchain=custom_scalafmt` flag to your `.bazelrc`
+  file
+- Use it for a specific target by setting the `scalafmt_toolchain_name` attribute:
+    ```starlark
+    load("@rules_scala_annex//rules:scala_with_scalafmt.bzl", "scala_binary")
+
+    scala_binary(
+        ...,
+        scalafmt_toolchain_name = "custom_scalafmt",
+        ...,
+    )
+    ```
+
+If you'd like to format all of the Scala files in your repository via a single target, you can use
+`scala_format_test`:
+
+*/BUILD*
+
+```starlark
 load("@rules_scala_annex//rules:scalafmt.bzl", "scala_format_test")
 scala_format_test(
     name = "format",
     srcs = glob(["**/*.scala"]),
 )
 ```
 
-Then
+Then:
 
 ```
 # check format, with diffs and non-zero exit in case of differences
@@ -27,3 +71,6 @@ $ bazel test :format
 # format files in-place
 $ bazel run :format
 ```
+
+Note that like the Scala rules, `scala_format_test` too uses toolchains and accepts a
+`scalafmt_toolchain_name` attribute.
diff --git a/docs/stardoc/scala_proto.md b/docs/stardoc/scala_proto.md
@@ -43,7 +43,7 @@ This rule should be used with an accompanying `toolchain` that binds it and spec
 
 For example:
 
-```python
+```starlark
 scala_proto_toolchain(
     name = "scalapb_toolchain_example",
     compiler = ":worker",

diff --git a/rules/scala_proto.bzl b/rules/scala_proto.bzl
@@ -54,7 +54,7 @@ This rule should be used with an accompanying `toolchain` that binds it and spec
 
 For example:
 
-```python
+```starlark
 scala_proto_toolchain(
     name = "scalapb_toolchain_example",
     compiler = ":worker",