From cb6ba6f43ab49a1c29ae0f933b9f60c105709201 Mon Sep 17 00:00:00 2001 From: Long Cao <48221800+long-stripe@users.noreply.github.com> Date: Wed, 8 May 2019 13:47:34 -0700 Subject: [PATCH] Docs reorganization (#742) * split out rule docs into separate files in docs/, minor doc fixups along the way * make Rules section in README.md a regular Markdown list with links to docs * move Overview first and freshen it up a bit * inline scala-lang.org link, (https) --- README.md | 599 +--------------------------------- docs/scala_binary.md | 167 ++++++++++ docs/scala_library.md | 176 ++++++++++ docs/scala_library_suite.md | 9 + docs/scala_macro_library.md | 177 ++++++++++ docs/scala_repl.md | 25 ++ docs/scala_test.md | 28 ++ docs/scala_test_suite.md | 7 + docs/scala_toolchain.md | 48 +++ docs/scalapb_proto_library.md | 88 +++++ docs/thrift_library.md | 73 +++++ 11 files changed, 815 insertions(+), 582 deletions(-) create mode 100644 docs/scala_binary.md create mode 100644 docs/scala_library.md create mode 100644 docs/scala_library_suite.md create mode 100644 docs/scala_macro_library.md create mode 100644 docs/scala_repl.md create mode 100644 docs/scala_test.md create mode 100644 docs/scala_test_suite.md create mode 100644 docs/scala_toolchain.md create mode 100644 docs/scalapb_proto_library.md create mode 100644 docs/thrift_library.md diff --git a/README.md b/README.md index cfb5cf954..bee7206b2 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,25 @@ # Scala Rules for Bazel [![Build Status](https://travis-ci.org/bazelbuild/rules_scala.svg?branch=master)](https://travis-ci.org/bazelbuild/rules_scala) [![Build status](https://badge.buildkite.com/90ce5244556df74db805a3c24a703fb87458396f9e1ddd687e.svg)](https://buildkite.com/bazel/scala-rules-scala-postsubmit) [![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/bazelbuild_rules_scala/Lobby) -
-

Rules

- -
- ## Overview -These rules are used for building [Scala][scala] projects with Bazel. There are -currently rules for building binaries (and repl apps), libraries, tests, and -protobuf and thrift libraries. +[Bazel](https://bazel.build/) is software for building and testing software, and can handle large, +multi-language projects at scale. + +This project defines core build rules for [Scala](https://www.scala-lang.org/) that can be used to build, test, and package Scala projects. + +## Rules + +* [scala_library](docs/scala_library.md) +* [scala_macro_library](docs/scala_macro_library.md) +* [scala_binary](docs/scala_binary.md) +* [scala_test](docs/scala_test.md) +* [scala_repl](docs/scala_repl.md) +* [scala_library_suite](docs/scala_library_suite.md) +* [scala_test_suite](docs/scala_test_suite.md) +* [thrift_library](docs/thrift_library.md) +* [scalapb_proto_library](docs/scalapb_proto_library.md) +* [scala_toolchain](docs/scala_toolchain.md) ## Getting started @@ -104,570 +103,6 @@ for an example workspace using another scala version. | 0.14.x | 3b9ab9be31ac217d3337c709cb6bfeb89c8dcbb1 | | 0.13.x | 3c987b6ae8a453886759b132f1572c0efca2eca2 | -[scala]: http://www.scala-lang.org/ - - -## scala\_library / scala\_macro_library - -```python -scala_library(name, srcs, deps, runtime_deps, exports, data, main_class, resources, resource_strip_prefix, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags, unused_dependency_checker_mode) -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, unused_dependency_checker_mode) -``` - -`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. These may be .srcjar jar files that contain source code.

-
deps -

List of labels, optional

-

List of other libraries to linked to this library target. - These must be jvm targets (scala_library, java_library, java_import, etc...)

-
runtime_deps -

List of labels, optional

-

List of other libraries to put on the classpath only at runtime. This is rarely needed in Scala. - These must be jvm targets (scala_library, java_library, java_import, etc...)

-
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. - These must be jvm targets (scala_library, java_library, java_import, etc...)

-
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. -

-
unused_dependency_checker_mode -

String; optional

-

- Enable unused dependency checking (see Unused dependency checking). - Possible values are: off, warn and error. -

-
- - -## scala_binary - -```python -scala_binary(name, srcs, deps, runtime_deps, data, main_class, resources, resource_strip_prefix, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags, unused_dependency_checker_mode) -``` - -`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. - These must be jvm targets (scala_library, java_library, java_import, etc...)

-
runtime_deps -

List of labels, optional

-

List of other libraries to put on the classpath only at runtime. This is rarely needed in Scala. - These must be jvm targets (scala_library, java_library, java_import, etc...)

-
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. -

-
unused_dependency_checker_mode -

String; optional

-

- Enable unused dependency checking (see Unused dependency checking). - Possible values are: off, warn and error. -

-
- - -## scala_test - -```python -scala_test(name, srcs, suites, deps, data, main_class, resources, resource_strip_prefix, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags, unused_dependency_checker_mode) -``` - -`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 compatibility 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 -```python -scala_repl(name, deps, scalacopts, jvm_flags, scalac_jvm_flags, javac_jvm_flags, unused_dependency_checker_mode) -``` -A scala repl allows you to add library dependencies (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 individual 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 individual targets in parallel. - - -## thrift_library - -```python -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` (in its `deps`). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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. Also can include `scroogle_scala_import` - targets, containing additional `thrift_jars` (which will be compiled) and/or `scala_jars` needed at compile time (such as Finagle).

-
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. -

-
- - -## scalapb\_proto_library - -You first need to add the following to your WORKSPACE file: - -```python -load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scala_proto_repositories") -scala_proto_repositories(scala_version = "2.12.8") -``` - -Then you can import `scalapb_proto_library` in any BUILD file like this: - -```python -load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scalapb_proto_library") -scalapb_proto_library(name, deps, with_grpc, with_java, with_flat_package, with_single_line_to_string, scalac_jvm_flags) -``` - -`scalapb_proto_library` generates a scala library of scala proto bindings -generated by the [ScalaPB compiler](https://github.com/scalapb/ScalaPB). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Attributes
name -

Name, required

-

A unique name for this target

-
deps -

List of labels, required

-

List of dependencies for this target. Must either be of type proto_library or java_proto_library (allowed only if with_java is enabled)

-
with_grpc -

boolean; optional (default False)

-

Enables generation of grpc service bindings for services defined in deps

-
with_java -

boolean; optional (default False)

-

Enables generation of converters to and from java protobuf bindings. If you set this to True make sure that you pass the corresponding java_proto_library target in deps

-
with_flat_package -

boolean; optional (default False)

-

When true, ScalaPB will not append the protofile base name to the package name

-
with_single_line_to_string -

boolean; optional (default False)

-

Enables generation of toString() methods that use the single line format

-
scalac_jvm_flags -

List of strings; optional

-

List of JVM flags to pass to the underlying scala_library attribute

-
- -## scala_toolchain -Scala toolchain allows you to define global configuration to all scala targets. -Currently the only option that can be set is `scalacopts` but the plan is to expand it to other options as well. - -**some scala_toolchain must be registered!** -### Several options to configure scala_toolchain: -#### A) Use default scala_toolchain: -In your workspace file add the following lines: - ```python - # WORKSPACE - # register default scala toolchain - load("@io_bazel_rules_scala//scala:toolchains.bzl", "scala_register_toolchains") - scala_register_toolchains() - ``` -#### B) Defining your own scala_toolchain requires 2 steps: -1. Add your own definition to scala_toolchain to a `BUILD` file: - ```python - # //toolchains/BUILD - load("@io_bazel_rules_scala//scala:scala_toolchain.bzl", "scala_toolchain") - - scala_toolchain( - name = "my_toolchain_impl", - scalacopts = ["-Ywarn-unused"], - unused_dependency_checker_mode = "off", - visibility = ["//visibility:public"] - ) - - toolchain( - name = "my_scala_toolchain", - toolchain_type = "@io_bazel_rules_scala//scala:toolchain_type", - toolchain = "my_toolchain_impl", - visibility = ["//visibility:public"] - ) - ``` -2. register your custom toolchain from `WORKSPACE`: - ```python - # WORKSPACE - # ... - register_toolchains("//toolchains:my_scala_toolchain") - ``` - ## Usage with [bazel-deps](https://github.com/johnynek/bazel-deps) Bazel-deps allows you to generate bazel dependencies transitively for maven artifacts. Generally we don't want bazel-deps to fetch diff --git a/docs/scala_binary.md b/docs/scala_binary.md new file mode 100644 index 000000000..b1016606c --- /dev/null +++ b/docs/scala_binary.md @@ -0,0 +1,167 @@ +# scala_binary + +```python +scala_binary( + name, + srcs, + deps, + runtime_deps, + data, + main_class, + resources, + resource_strip_prefix, + scalacopts, + jvm_flags, + scalac_jvm_flags, + javac_jvm_flags, + unused_dependency_checker_mode +) +``` + +`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. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
runtime_deps +

List of labels, optional

+

List of other libraries to put on the classpath only at runtime. This is rarely needed in Scala. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
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. +

+
unused_dependency_checker_mode +

String; optional

+

+ Enable unused dependency checking (see Unused dependency checking). + Possible values are: off, warn and error. +

+
\ No newline at end of file diff --git a/docs/scala_library.md b/docs/scala_library.md new file mode 100644 index 000000000..56c4e5248 --- /dev/null +++ b/docs/scala_library.md @@ -0,0 +1,176 @@ +# scala_library + +```python +scala_library( + name, + srcs, + deps, + runtime_deps, + exports, + data, + main_class, + resources, + resource_strip_prefix, + scalacopts, + jvm_flags, + scalac_jvm_flags, + javac_jvm_flags, + unused_dependency_checker_mode +) +``` + +`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. + +In order to have 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. These may be .srcjar jar files that contain source code.

+
deps +

List of labels, optional

+

List of other libraries to linked to this library target. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
runtime_deps +

List of labels, optional

+

List of other libraries to put on the classpath only at runtime. This is rarely needed in Scala. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
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. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
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. +

+
unused_dependency_checker_mode +

String; optional

+

+ Enable unused dependency checking (see Unused dependency checking). + Possible values are: off, warn and error. +

+
\ No newline at end of file diff --git a/docs/scala_library_suite.md b/docs/scala_library_suite.md new file mode 100644 index 000000000..33fb2531c --- /dev/null +++ b/docs/scala_library_suite.md @@ -0,0 +1,9 @@ +# scala_library_suite + +`scala_library_suite` allows you to define a glob or series of targets for which to generate sub +scala libraries. The outer target will export all of the inner targets. + +This rule is useful for splitting up a larger target into smaller targets (typically a series of independent files), +thereby enabling better cache outputs and parallelization of building individual targets. +Generally speaking, downstream targets should not be aware of a suite's presence - it should be strictly +a parent-children relationship. \ No newline at end of file diff --git a/docs/scala_macro_library.md b/docs/scala_macro_library.md new file mode 100644 index 000000000..c61e6c093 --- /dev/null +++ b/docs/scala_macro_library.md @@ -0,0 +1,177 @@ +# scala_macro_library + +```python +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, + unused_dependency_checker_mode +) +``` + +`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, aim for granular (smaller) +targets to take advantage of Bazel caching as much as possible. + +In order to have 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. These may be .srcjar jar files that contain source code.

+
deps +

List of labels, optional

+

List of other libraries to linked to this library target. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
runtime_deps +

List of labels, optional

+

List of other libraries to put on the classpath only at runtime. This is rarely needed in Scala. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
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. + These must be jvm targets (scala_library, java_library, java_import, etc...)

+
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. +

+
unused_dependency_checker_mode +

String; optional

+

+ Enable unused dependency checking (see Unused dependency checking). + Possible values are: off, warn and error. +

+
\ No newline at end of file diff --git a/docs/scala_repl.md b/docs/scala_repl.md new file mode 100644 index 000000000..af210fbcd --- /dev/null +++ b/docs/scala_repl.md @@ -0,0 +1,25 @@ +# scala_repl + +```python +scala_repl( + name, + deps, + scalacopts, + jvm_flags, + scalac_jvm_flags, + javac_jvm_flags, + unused_dependency_checker_mode +) +``` + +`scala_repl` allows you to add library dependencies (but not currently `scala_binary` targets) +and then generate a _script_ which starts a REPL. + +Since `bazel run` closes stdin, it cannot be used to start a REPL. +Instead, 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 +``` \ No newline at end of file diff --git a/docs/scala_test.md b/docs/scala_test.md new file mode 100644 index 000000000..a651d348b --- /dev/null +++ b/docs/scala_test.md @@ -0,0 +1,28 @@ +# scala_test + +```python +scala_test( + name, + srcs, + suites, + deps, + data, + main_class, + resources, + resource_strip_prefix, + scalacopts, + jvm_flags, + scalac_jvm_flags, + javac_jvm_flags, + unused_dependency_checker_mode +) +``` + +`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. + +By default, `scala_test` runs _all_ tests in a given target. +For backwards compatibility, 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. \ No newline at end of file diff --git a/docs/scala_test_suite.md b/docs/scala_test_suite.md new file mode 100644 index 000000000..183bd09ad --- /dev/null +++ b/docs/scala_test_suite.md @@ -0,0 +1,7 @@ +# scala_test_suite + +`scala_test_suite` allows you to define a glob or series of targets for which to generate sub scala tests. + +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 finer grained targets, enabling better caching +and parallelization of building & testing individual targets. \ No newline at end of file diff --git a/docs/scala_toolchain.md b/docs/scala_toolchain.md new file mode 100644 index 000000000..bb9796d43 --- /dev/null +++ b/docs/scala_toolchain.md @@ -0,0 +1,48 @@ +# scala_toolchain + +`scala_toolchain` allows you to define global configuration to all Scala targets. + +Currently, the only option that can be set is `scalacopts` but the plan is to expand it to other options as well. + +**Some scala_toolchain must be registered!** + +### Several options to configure `scala_toolchain`: + +#### A) Use the default `scala_toolchain`: + +In your workspace file add the following lines: + +```python +# WORKSPACE +# register default scala toolchain +load("@io_bazel_rules_scala//scala:toolchains.bzl", "scala_register_toolchains") +scala_register_toolchains() +``` + +#### B) Defining your own `scala_toolchain` requires 2 steps: + +1. Add your own definition of `scala_toolchain` to a `BUILD` file: + ```python + # //toolchains/BUILD + load("@io_bazel_rules_scala//scala:scala_toolchain.bzl", "scala_toolchain") + + scala_toolchain( + name = "my_toolchain_impl", + scalacopts = ["-Ywarn-unused"], + unused_dependency_checker_mode = "off", + visibility = ["//visibility:public"] + ) + + toolchain( + name = "my_scala_toolchain", + toolchain_type = "@io_bazel_rules_scala//scala:toolchain_type", + toolchain = "my_toolchain_impl", + visibility = ["//visibility:public"] + ) + ``` + +2. Register your custom toolchain from `WORKSPACE`: + ```python + # WORKSPACE + register_toolchains("//toolchains:my_scala_toolchain") + ``` diff --git a/docs/scalapb_proto_library.md b/docs/scalapb_proto_library.md new file mode 100644 index 000000000..92081ca62 --- /dev/null +++ b/docs/scalapb_proto_library.md @@ -0,0 +1,88 @@ +# scalapb_proto_library + +To use this rule, you'll first need to add the following to your `WORKSPACE` file: + +```python +load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scala_proto_repositories") +scala_proto_repositories(scala_version = "2.12.8") # or whatever scala_version you're on +``` + +Then you can import `scalapb_proto_library` in any `BUILD` file like this: + +```python +load("@io_bazel_rules_scala//scala_proto:scala_proto.bzl", "scalapb_proto_library") +scalapb_proto_library( + name, + deps, + with_grpc, + with_java, + with_flat_package, + with_single_line_to_string, + scalac_jvm_flags +) +``` + +`scalapb_proto_library` generates a Scala library of Scala proto bindings +generated by the [ScalaPB compiler](https://github.com/scalapb/ScalaPB). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Attributes
name +

Name, required

+

A unique name for this target

+
deps +

List of labels, required

+

List of dependencies for this target. Must either be of type proto_library or java_proto_library (allowed only if with_java is enabled)

+
with_grpc +

boolean; optional (default False)

+

Enables generation of grpc service bindings for services defined in deps

+
with_java +

boolean; optional (default False)

+

Enables generation of converters to and from java protobuf bindings. If you set this to True make sure that you pass the corresponding java_proto_library target in deps

+
with_flat_package +

boolean; optional (default False)

+

When true, ScalaPB will not append the protofile base name to the package name

+
with_single_line_to_string +

boolean; optional (default False)

+

Enables generation of toString() methods that use the single line format

+
scalac_jvm_flags +

List of strings; optional

+

List of JVM flags to pass to the underlying scala_library attribute

+
\ No newline at end of file diff --git a/docs/thrift_library.md b/docs/thrift_library.md new file mode 100644 index 000000000..94a3acb7e --- /dev/null +++ b/docs/thrift_library.md @@ -0,0 +1,73 @@ +# thrift_library + +```python +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` in its `deps`. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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. Also can include `scroogle_scala_import` + targets, containing additional `thrift_jars` (which will be compiled) and/or `scala_jars` needed at compile time (such as Finagle).

+
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. +

+
\ No newline at end of file