Scala Rules for Bazel
Where to get help
Overview
Bazel is a tool for building and testing software and can handle large, multi-language projects at scale.
This project defines core build rules for Scala that can be used to build, test, and package Scala projects.
Rules
- scala_library
- scala_macro_library
- scala_binary
- scala_test
- scala_repl
- scala_library_suite
- scala_test_suite
- thrift_library
- scala_proto_library
- scala_toolchain
- scala_import
- scala_doc
Getting started
- Install Bazel, see the compatibility table.
- Add the following to your
WORKSPACE
file and update versions with their sha256s if needed:
# WORKSPACE
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
skylib_version = "1.0.3"
http_archive(
name = "bazel_skylib",
sha256 = "1c531376ac7e5a180e0237938a2536de0c54d93f5c278634818e0efc952dd56c",
type = "tar.gz",
url = "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/{}/bazel-skylib-{}.tar.gz".format(skylib_version, skylib_version),
)
rules_scala_version = "e7a948ad1948058a7a5ddfbd9d1629d6db839933"
http_archive(
name = "io_bazel_rules_scala",
sha256 = "76e1abb8a54f61ada974e6e9af689c59fd9f0518b49be6be7a631ce9fa45f236",
strip_prefix = "rules_scala-%s" % rules_scala_version,
type = "zip",
url = "https://github.com/bazelbuild/rules_scala/archive/%s.zip" % rules_scala_version,
)
# Stores Scala version and other configuration
# 2.12 is a default version, other versions can be use by passing them explicitly:
# scala_config(scala_version = "2.11.12")
load("@io_bazel_rules_scala//:scala_config.bzl", "scala_config")
scala_config()
load("@io_bazel_rules_scala//scala:scala.bzl", "scala_repositories")
scala_repositories()
load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains")
rules_proto_dependencies()
rules_proto_toolchains()
load("@io_bazel_rules_scala//scala:toolchains.bzl", "scala_register_toolchains")
scala_register_toolchains()
# optional: setup ScalaTest toolchain and dependencies
load("@io_bazel_rules_scala//testing:scalatest.bzl", "scalatest_repositories", "scalatest_toolchain")
scalatest_repositories()
scalatest_toolchain()
This will load the rules_scala
repository at the commit sha
rules_scala_version
into your Bazel project and register a Scala
toolchain at the default Scala version (2.12.11)
Then in your BUILD file just add the following so the rules will be available:
load("@io_bazel_rules_scala//scala:scala.bzl", "scala_library", "scala_binary", "scala_test")
You may wish to have these rules loaded by default using bazel's prelude. You can add the above to the file tools/build_rules/prelude_bazel
in your repo (don't forget to have a, possibly empty, BUILD file there) and then it will be automatically prepended to every BUILD file in the workspace.
To run with a persistent worker (much faster), you need to add
build --strategy=Scalac=worker
build --worker_sandboxing
to your command line, or to enable by default for building/testing add it to your .bazelrc.
Coverage support
It will produce several .dat files with results for your targets.
You can also add more options to receive a combined coverage report:
bazel coverage \
--combined_report=lcov \
--coverage_report_generator="@bazel_tools//tools/test/CoverageOutputGenerator/java/com/google/devtools/coverageoutputgenerator:Main" \
//...
This should produce a single bazel-out/_coverage/_coverage_report.dat
from all coverage files that are generated.
You can extract information from your coverage reports with lcov
:
# For a summary:
lcov --summary your-coverage-report.dat
# For details:
lcov --list your-coverage-report.dat
If you prefer an HTML report, then you can use genhtml
provided also by the lcov
package.
Coverage support has been only tested with ScalaTest.
Please check coverage.md for more details on coverage support.
Selecting Scala version
Rules scala supports the last two released minor versions for each of Scala 2.11, 2.12, 2.13. Previous minor versions may work but are supported only on a best effort basis.
To configure Scala version you must call scala_config(scala_version = "2.xx.xx")
and configure
dependencies by declaring scala_toolchain.
For a quick start you can use scala_repositories()
and scala_register_toolchains()
, which have
dependency providers configured for 2.11.12
, 2.12.11
and 2.13.3
versions.
# WORKSPACE
load("@io_bazel_rules_scala//:scala_config.bzl", "scala_config")
scala_config(scala_version = "2.13.3")
load("@io_bazel_rules_scala//scala:scala.bzl", "scala_repositories")
scala_repositories()
load("@io_bazel_rules_scala//scala:toolchains.bzl", "scala_register_toolchains")
scala_register_toolchains()
If you're using any of the rules twitter_scrooge
, scala_proto_repositories
or specs2_junit_repositories
you also need to specify scala_version
for them. See ./test_version/WORKSPACE.template
for an example workspace using another scala version.
Bazel compatible versions
minimal bazel version | rules_scala gitsha |
---|---|
4.1.0 | HEAD |
3.5.0 | 0f55e9f8cff6494bbff7cd57048d732286a520f5 / |
2.0.0 | 116709091e5e1aab3346184217b565f4cb7ba4eb |
1.1.0 | d681a952da74fc61a49fc3167b03548f42fc5dde |
0.28.1 | bd0c388125e12f4f173648fc4474f73160a5c628 |
0.23.x | ca655e5a330cbf1d66ce1d9baa63522752ec6011 |
0.22.x | f3113fb6e9e35cb8f441d2305542026d98afc0a2 |
0.16.x | f3113fb6e9e35cb8f441d2305542026d98afc0a2 |
0.15.x | 3b9ab9be31ac217d3337c709cb6bfeb89c8dcbb1 |
0.14.x | 3b9ab9be31ac217d3337c709cb6bfeb89c8dcbb1 |
0.13.x | 3c987b6ae8a453886759b132f1572c0efca2eca2 |
PRs are also built with highest supported bazel version (see Travis config for the exact highest version)
Breaking changes
If you're upgrading to a version containing one of these commits, you may encounter a breaking change where there was previously undefined behavior.
- 929b318 on 2020-01-30: Fixed a bug in the JMH benchmark build that was allowing build failures to creep through. Previously you were able to build a benchmark suite with JMH build errors. Running the benchmark suite would only run the successfully-built benchmarks.
bazel-deps
Usage withBazel-deps allows you to generate bazel dependencies transitively for maven artifacts. Generally we don't want bazel-deps to fetch
scala artifacts from maven but instead use the ones we get from calling scala_repositories
. The artifacts can be overridden in the
dependencies file used by bazel-deps:
replacements:
org.scala-lang:
scala-library:
lang: scala/unmangled
target: "@io_bazel_rules_scala_scala_library//:io_bazel_rules_scala_scala_library"
scala-reflect:
lang: scala/unmangled
target: "@io_bazel_rules_scala_scala_reflect//:io_bazel_rules_scala_scala_reflect"
scala-compiler:
lang: scala/unmangled
target: "@io_bazel_rules_scala_scala_compiler//:io_bazel_rules_scala_scala_compiler"
org.scala-lang.modules:
scala-parser-combinators:
lang: scala
target:
"@io_bazel_rules_scala_scala_parser_combinators//:io_bazel_rules_scala_scala_parser_combinators"
scala-xml:
lang: scala
target:
"@io_bazel_rules_scala_scala_xml//:io_bazel_rules_scala_scala_xml"
Publishing to Maven repository
Go here
Dependency Tracking
Rules Scala supports multiple dependency modes including strict and unused dependency tracking. See Dependency Tracking for more info.
Advanced configurable rules
To make the ruleset more flexible and configurable, we introduce a phase architecture. By using a phase architecture, where rule implementations are defined as a list of phases that are executed sequentially, functionality can easily be added (or modified) by adding (or swapping) phases.
Phases provide 3 major benefits:
- Consumers are able to configure the rules to their specific use cases by defining new phases within their workspace without impacting other consumers.
- Contributors are able to implement new functionalities by creating additional default phases.
- Phases give us more clear idea what steps are shared across rules.
See Customizable Phase for more info.
Phase extensions
Building from source
Setup bazel: We recommend using Bazelisk as your default bazel binary
Test & Build:
bash test_all.sh
You can also use:
bazel test //test/...
Note bazel test //...
will not work since we have a sub-folder on the root folder which is meant to be used in a failure scenario in the integration tests.
Similarly to only build you should use bazel build //src/...
due to that folder.
Updates
This section contains a list of updates that might require action from the user.
043ba58
: Updates default scrooge version to18.6.0
76d4ab9
: Updates naming for scala artifact replacements in bazel-deps. See Usage with bazel-deps
Contributing
See CONTRIBUTING.md for more info.
Adopters
Here's a (non-exhaustive) list of companies that use rules_scala
in production. Don't see yours? You can add it in a PR!