contrib_rules_jvm

Handy rules for working with JVM-based projects in Bazel.

In order to use these in your own projects, in your WORKSPACE once you've used an http_archive, you can load all the necessary dependencies by:

load("@contrib_rules_jvm//:repositories.bzl", "contrib_rules_jvm_deps")

contrib_rules_jvm_deps()

load("@contrib_rules_jvm//:setup.bzl", "contrib_rules_jvm_setup")

contrib_rules_jvm_setup()

If you're looking to get started quickly, then take a look at java_test_suite (a macro for generating a test suite from a glob of java test sources) and java_junit5_test (a drop-in replacement for java_test that can run JUnit5 tests)

Linting

Many of the features in this repo are designed to be exposed via apple_rules_lint, which provides a framework for integrating linting checks into your builds. To take advantage of this perform the following steps:

# In your WORKSPACE, after loading `apple_rules_lint`

load("@apple_rules_lint//lint:setup.bzl", "lint_setup")

lint_setup({
  # Note: this is an example config!
  "java-checkstyle": "@contrib_rules_jvm//java:checkstyle-default-config",
  "java-pmd": "//:pmd-config",
  "java-spotbugs": "@contrib_rules_jvm//java:spotbugs-default-config",
})

You are welcome to include all (or none!) of these rules, and linting is "opt-in": if there's no lint_setup call in your repo's WORKSPACE then everything will continue working just fine and no additional lint tests will be generated.

The linters are configured using specific rules. The mappings are:

Well known name	Lint config rule
java-checkstyle	checkstyle_config
java-pmd	pmd_ruleset
java-spotbugs	spotbugs_config

Requirements

These rules require Java 11 or above.

Java Rules

checkstyle_config

checkstyle_config(name, config_file, output_format)

Rule allowing checkstyle to be configured. This is typically used with the linting rules from @apple_rules_lint to configure how checkstyle should run.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
config_file	The config file to use for all checkstyle tests	Label	required
output_format	Output format to use. Defaults to plain	String	optional	"plain"

checkstyle_test

checkstyle_test(name, config, configuration_file, output_format, srcs)

Use checkstyle to lint the srcs.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
config	-	Label	optional	None
configuration_file	Configuration file. If not specified a default file is used	Label	optional	None
output_format	Output Format can be plain or xml. Defaults to plain	String	optional	"plain"
srcs	-	List of labels	required

pmd_ruleset

pmd_ruleset(name, format, rulesets, shallow)

Select a rule set for PMD tests.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
format	Generate report in the given format. One of html, text, or xml (default is xml)	String	optional	"xml"
rulesets	Use these rulesets.	List of labels	optional	[]
shallow	Use the targetted output to increase PMD's depth of processing	Boolean	optional	True

pmd_test

pmd_test(name, ruleset, srcs, target)

Use PMD to lint the srcs.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
ruleset	-	Label	required
srcs	-	List of labels	optional	[]
target	-	Label	optional	None

spotbugs_config

spotbugs_config(name, effort, exclude_filter, fail_on_warning)

Configuration used for spotbugs, typically by the //lint rules.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
effort	Effort can be min, less, default, more or max. Defaults to default	String	optional	"default"
exclude_filter	Report all bug instances except those matching the filter specified by this filter file	Label	optional	None
fail_on_warning	Whether to fail on warning, or just create a report. Defaults to True	Boolean	optional	True

spotbugs_test

spotbugs_test(name, config, deps, effort, fail_on_warning, only_output_jars)

Use spotbugs to lint the srcs.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
config	-	Label	optional	None
deps	-	List of labels	required
effort	Effort can be min, less, default, more or max. Defaults to default	String	optional	"default"
fail_on_warning	If set to true the test will fail on a warning, otherwise it will succeed but create a report. Defaults to True	Boolean	optional	True
only_output_jars	If set to true, only the output jar of the target will be analyzed. Otherwise all transitive runtime dependencies will be analyzed	Boolean	optional	True

java_binary

java_binary(name, kwargs)

Adds linting tests to Bazel's own java_binary

PARAMETERS

Name	Description	Default Value
name	-	none
kwargs	-	none

java_export

java_export(name, maven_coordinates, pom_template, deploy_env, visibility, kwargs)

Adds linting tests to rules_jvm_external's java_export

PARAMETERS

Name	Description	Default Value
name	-	none
maven_coordinates	-	none
pom_template	-	None
deploy_env	-	None
visibility	-	None
kwargs	-	none

java_junit5_test

java_junit5_test(name, test_class, runtime_deps, kwargs)

Run junit5 tests using Bazel.

This is designed to be a drop-in replacement for java_test, but rather than using a JUnit4 runner it provides support for using JUnit5 directly. The arguments are the same as used by java_test.

The generated target does not include any JUnit5 dependencies. If you are using the standard @maven namespace for your maven_install you can add these to your deps using JUNIT5_DEPS or JUNIT5_VINTAGE_DEPS loaded from //java:defs.bzl

PARAMETERS

Name	Description	Default Value
name	The name of the test.	none
test_class	The Java class to be loaded by the test runner. If not specified, the class name will be inferred from a combination of the current bazel package and the name attribute.	None
runtime_deps	-	[]
kwargs	-	none

java_library

java_library(name, kwargs)

Adds linting tests to Bazel's own java_library

PARAMETERS

Name	Description	Default Value
name	-	none
kwargs	-	none

java_test

java_test(name, kwargs)

Adds linting tests to Bazel's own java_test

PARAMETERS

Name	Description	Default Value
name	-	none
kwargs	-	none

java_test_suite

java_test_suite(name, srcs, runner, test_suffixes, deps, runtime_deps, tags, visibility, size,
                kwargs)

Create a suite of java tests from *Test.java files.

This rule will create a java_test for each file which matches any of the test_suffixes that are passed to this rule as srcs. If any non-test sources are added these will first of all be compiled into a java_library which will be added as a dependency for each test target, allowing common utility functions to be shared between tests.

The generated java_test targets will be named after the test file: FooTest.java will create a :FooTest target.

In addition, a test_suite will be created, named using the name attribute to allow all the tests to be run in one go.

PARAMETERS

Name	Description	Default Value
name	A unique name for this rule. Will be used to generate a test_suite	none
srcs	Source files to create test rules for.	none
runner	One of junit4 or junit5.	"junit4"
test_suffixes	The file name suffix used to identify if a file contains a test class.	["Test.java"]
deps	A list of java_* dependencies.	None
runtime_deps	A list of java_* dependencies needed at runtime.	[]
tags	-	[]
visibility	-	None
size	The size of the test, passed to java_test	None
kwargs	-	none

Freezing Dependencies

At runtime, a handful of dependencies are required by helper classes in this project. Rather than pollute the default @maven workspace, these are loaded into a @contrib_rules_jvm_deps workspace. These dependencies are loaded using a call to maven_install, but we don't want to force users to remember to load our own dependencies for us. Instead, to add a new dependency to the project:

1. Update frozen_deps in the WORKSPACE file
2. Run ./bin/freeze-deps.py
3. Commit the updated files.