diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99e97e95..8be9f7a0 100644 --- 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. `@//:`. +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. +`@//:`. -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 index 03eb148c..201624be 100644 --- 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 `` with the +latest commit on `lucid-master` and `` 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 = "" -http_archive( - name = "rules_scala_annex", - integrity = "sha256-WjZvojiclkiyVxQ1NqkH1lDeGaDLyzQOGiDsCfhVAec=", +archive_override( + module_name = "rules_scala_annex", + 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 index 7e815253..33f9e206 100644 --- 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 index 90fafd63..0d61748f 100644 --- a/docs/newdocs/scala_versions.md +++ b/docs/newdocs/scala_versions.md @@ -19,45 +19,40 @@ 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", @@ -65,18 +60,19 @@ register_zinc_toolchain( ) ``` -*/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 index b41cc23c..a3170729 100644 --- a/docs/scalafmt.md +++ b/docs/scalafmt.md @@ -1,16 +1,60 @@ # 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", @@ -18,7 +62,7 @@ scala_format_test( ) ``` -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 index ab6f8e8f..0112a005 100644 --- 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 index bc396cad..1befb129 100644 --- 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",