Skip to content

Contributed Bazel rules that make working with java projects more pleasant

License

Notifications You must be signed in to change notification settings

blorente/rules_jvm

 
 

Repository files navigation

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.

About

Contributed Bazel rules that make working with java projects more pleasant

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Java 48.7%
  • Starlark 48.6%
  • Python 2.6%
  • Shell 0.1%