Scala Rules for Bazel

Rules

• scala_library/scala_macro_library
• scala_binary
• scala_test

Overview

This rule is used for building Scala projects with Bazel. There are currently four rules, scala_library, scala_macro_library, scala_binary and scala_test.

Getting started

In order to use scala_library, scala_macro_library, and scala_binary, you must have bazel 0.5.3 or later and add the following to your WORKSPACE file:

rules_scala_version="031e73c02e0d8bfcd06c6e4086cdfc7f3a3061a8" # update this as needed

http_archive(
             name = "io_bazel_rules_scala",
             url = "https://github.com/bazelbuild/rules_scala/archive/%s.zip"%rules_scala_version,
             type = "zip",
             strip_prefix= "rules_scala-%s" % rules_scala_version
             )

load("@io_bazel_rules_scala//scala:scala.bzl", "scala_repositories")
scala_repositories()

To use a particular tag, use the tagged number in tag = and omit the commit attribute. Note that these plugins are still evolving quickly, as is bazel, so you may need to select the version most appropriate for you.

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
test --strategy=Scalac=worker

to your command line, or to enable by default for building/testing add it to your .bazelrc.

scala_library / scala_macro_library

scala_library(name, srcs, deps, runtime_deps, exports, data, main_class, resources, resource_strip_prefix, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags)
scala_macro_library(name, srcs, deps, runtime_deps, exports, data, main_class, resources, resource_strip_prefix, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags)

scala_library generates a .jar file from .scala source files. This rule also creates an interface jar to avoid recompiling downstream targets unless their interface changes.

scala_macro_library generates a .jar file from .scala source files when they contain macros. For macros, there are no interface jars because the macro code is executed at compile time. For best performance, you want very granular targets until such time as the zinc incremental compiler can be supported.

In order to make a java rule use this jar file, use the java_import rule.

Attributes
name	Name, required A unique name for this target
srcs	List of labels, required List of Scala .scala source files used to build the library
deps	List of labels, optional List of other libraries to linked to this library target
runtime_deps	List of labels, optional List of other libraries to put on the classpath only at runtime. This is rarely needed in Scala.
exports	List of labels, optional List of targets to add to the dependencies of those that depend on this target. Similar to the `java_library` parameter of the same name. Use this sparingly as it weakens the precision of the build graph.
data	List of labels, optional List of files needed by this rule at runtime.
main_class	String, optional Name of class with main() method to use as an entry point The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from srcs) or provided by direct or transitive dependencies (through deps). If the class is unavailable, the binary will fail at runtime; there is no build-time check.
resources	List of labels; optional A list of data files to be included in the JAR.
resource_strip_prefix	String; optional The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory.
scalacopts	List of strings; optional Extra compiler options for this library to be passed to scalac. Subject to Make variable substitution and Bourne shell tokenization.
jvm_flags	List of strings; optional; deprecated Deprecated, superseded by scalac_jvm_flags and javac_jvm_flags. Is not used and is kept as backwards compatibility for the near future. Effectively jvm_flags is now an executable target attribute only.
scalac_jvm_flags	List of strings; optional List of JVM flags to be passed to scalac after the scalacopts. Subject to Make variable substitution and Bourne shell tokenization.
javac_jvm_flags	List of strings; optional List of JVM flags to be passed to javac after the javacopts. Subject to Make variable substitution and Bourne shell tokenization.

scala_binary

scala_binary(name, srcs, deps, runtime_deps, data, main_class, resources, resource_strip_prefix, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags)

scala_binary generates a Scala executable. It may depend on scala_library, scala_macro_library and java_library rules.

A scala_binary requires a main_class attribute.

Attributes
name	Name, required A unique name for this target
srcs	List of labels, required List of Scala .scala source files used to build the binary
deps	List of labels, optional List of other libraries to linked to this binary target
runtime_deps	List of labels, optional List of other libraries to put on the classpath only at runtime. This is rarely needed in Scala.
data	List of labels, optional List of files needed by this rule at runtime.
main_class	String, required Name of class with main() method to use as an entry point The value of this attribute is a class name, not a source file. The class must be available at runtime: it may be compiled by this rule (from srcs) or provided by direct or transitive dependencies (through deps). If the class is unavailable, the binary will fail at runtime; there is no build-time check.
resources	List of labels; optional A list of data files to be included in the JAR.
resource_strip_prefix	String; optional The path prefix to strip from Java resources. If specified, this path prefix is stripped from every file in the `resources` attribute. It is an error for a resource file not to be under this directory.
scalacopts	List of strings; optional Extra compiler options for this binary to be passed to scalac. Subject to Make variable substitution and Bourne shell tokenization.
jvm_flags	List of strings; optional List of JVM flags to be passed to the executing JVM. Subject to Make variable substitution and Bourne shell tokenization.
scalac_jvm_flags	List of strings; optional List of JVM flags to be passed to scalac after the scalacopts. Subject to Make variable substitution and Bourne shell tokenization.
javac_jvm_flags	List of strings; optional List of JVM flags to be passed to javac after the javacopts. Subject to Make variable substitution and Bourne shell tokenization.

scala_test

scala_test(name, srcs, suites, deps, data, main_class, resources, resource_strip_prefix, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags)

scala_test generates a Scala executable which runs unit test suites written using the scalatest library. It may depend on scala_library, scala_macro_library and java_library rules.

A scala_test by default runs all tests in a given target. For backwards compatiblity it accepts a suites attribute which is ignored due to the ease with which that field is not correctly populated and tests are not run.

scala_repl

scala_repl(name, deps, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags)

A scala repl allows you to add library dependendencies (not currently scala_binary targets) to generate a script to run which starts a REPL. Since bazel run closes stdin, it cannot be used to start the REPL. Instead, you use bazel build to build the script, then run that script as normal to start a REPL session. An example in this repo:

bazel build test:HelloLibRepl
bazel-bin/test/HelloLibRepl

scala_library_suite

The scala library suite allows you to define a glob or series of targets to generate sub scala libraries for. The outer target will export all of the inner targets. This allows splitting up of a series of independent files in a larger target into smaller ones. This lets us cache outputs better and also build the indvidual targets in parallel. Downstream targets should not be aware of its presence.

scala_test_suite

The scala test suite allows you to define a glob or series of targets to generate sub scala tests for. The outer target defines a native test suite to run all the inner tests. This allows splitting up of a series of independent tests from one target into several. This lets us cache outputs better and also build and test the indvidual targets in parallel.

thrift_library

load("@io_bazel_rules_scala//thrift:thrift.bzl", "thrift_library")
thrift_library(name, srcs, deps, absolute_prefix, absolute_prefixes)

thrift_library generates a thrift source zip file. It should be consumed by a thrift compiler like scrooge_scala_library.

Attributes
name	Name, required A unique name for this target
srcs	List of labels, required List of Thrift .thrift source files used to build the target
deps	List of labels, optional List of other thrift dependencies that this thrift depends on.
absolute_prefix	string; optional (deprecated in favor of absolute_prefixes) This string acts as a wildcard expression of the form *`string_value` that is removed from the start of the path. Example: thrift is at `a/b/c/d/e/A.thrift` , prefix of `b/c/d`. Will mean other thrift targets can refer to this thrift at `e/A.thrift`.
absolute_prefixes	List of strings; optional Each of these strings acts as a wildcard expression of the form *string_value that is removed from the start of the path. Example: thrift is at a/b/c/d/e/A.thrift , prefix of b/c/d. Will mean other thrift targets can refer to this thrift at e/A.thrift. Exactly one of these must match all thrift paths within the target, more than one or zero will fail the build. The main use case to have several here is to make a macro target you can share across several indvidual thrift_library, if source path is /src/thrift or /src/main/thrift it can strip off the prefix without users needing to configure it per target.

Building from source

Test & Build:

bash test_run.sh

This doesn't currently pass on OS X (see #136 for details) and so 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.