api.md

Basic functions

These are the basic functions to get started.

To use these functions, load them at the top of your BUILD file. For example:

load("@rules_jvm_external//:defs.bzl", "maven_install", "artifact")

javadoc

load("@rules_jvm_external//:defs.bzl", "javadoc")

javadoc(name, deps, additional_dependencies, doc_deps, doc_resources, doc_url, excluded_packages,
        excluded_workspaces, included_packages, javadocopts)

Generate a javadoc from all the deps

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	The java libraries to generate javadocs for. The source jars of each dep will be used to generate the javadocs. Currently docs for transitive dependencies are not generated.	List of labels	required
additional_dependencies	Mapping of Labels to the excluded workspace names. Note that this must match the values passed to the pom_file rule so the pom.xml correctly lists these dependencies.	Dictionary: Label -> String	optional	{}
doc_deps	javadoc targets referenced by the current target. Use this to automatically add appropriate -linkoffline javadoc options to resolve references to packages documented by the given javadoc targets that have url specified.	List of labels	optional	[]
doc_resources	Resources to include in the javadoc jar.	List of labels	optional	[]
doc_url	The URL at which this documentation will be hosted. This information is only used by javadoc targets depending on this target.	String	optional	""
excluded_packages	A list of packages to exclude from the generated javadoc. Wildcards are supported at the end of the package name. For example, com.example.* will exclude all the subpackages of com.example, while com.example will exclude only the files directly in com.example.	List of strings	optional	[]
excluded_workspaces	A list of bazel workspace names to exclude from the generated jar	List of strings	optional	["com_google_protobuf", "protobuf"]
included_packages	A list of packages to include in the generated javadoc. Wildcards are supported at the end of the package name. For example, com.example.* will include all the subpackages of com.example, while com.example will include only the files directly in com.example.	List of strings	optional	[]
javadocopts	javadoc options. Note sources and classpath are derived from the deps. Any additional options can be passed here. If nothing is passed, a default list of options is used: ["-notimestamp", "-use", "-quiet", "-Xdoclint:-missing", "-encoding", "UTF8"]	List of strings	optional	["-notimestamp", "-use", "-quiet", "-Xdoclint:-missing", "-encoding", "UTF8"]

java_export

load("@rules_jvm_external//:defs.bzl", "java_export")

java_export(name, maven_coordinates, manifest_entries, deploy_env, excluded_workspaces, exclusions,
            pom_template, allowed_duplicate_names, visibility, tags, testonly, classifier_artifacts,
            publish_maven_metadata, kwargs)

Extends java_library to allow maven artifacts to be uploaded.

This macro can be used as a drop-in replacement for java_library, but also generates an implicit name.publish target that can be run to publish maven artifacts derived from this macro to a maven repository. The publish rule understands the following variables (declared using --define when using bazel run, or as environment variables in ALL_CAPS form):

• maven_repo: A URL for the repo to use. May be "https" or "file". Can also be set with environment variable MAVEN_REPO.
• maven_user: The user name to use when uploading to the maven repository. Can also be set with environment variable MAVEN_USER.
• maven_password: The password to use when uploading to the maven repository. Can also be set with environment variable MAVEN_PASSWORD.

This macro also generates a name-pom target that creates the pom.xml file associated with the artifacts. The template used is derived from the (optional) pom_template argument, and the following substitutions are performed on the template file:

• {groupId}: Replaced with the maven coordinates group ID.
• {artifactId}: Replaced with the maven coordinates artifact ID.
• {version}: Replaced by the maven coordinates version.
• {type}: Replaced by the maven coordinates type, if present (defaults to "jar")
• {scope}: Replaced by the maven coordinates type, if present (defaults to "compile")
• {dependencies}: Replaced by a list of maven dependencies directly relied upon by java_library targets within the artifact.

The "edges" of the artifact are found by scanning targets that contribute to runtime dependencies for the following tags:

• maven_coordinates=group:artifact:type:version: Specifies a dependency of this artifact.
• maven:compile-only: Specifies that this dependency should not be listed as a dependency of the artifact being generated.

To skip generation of the javadoc jar, add the no-javadocs tag to the target.

Generated rules:

• name: A java_library that other rules can depend upon.
• name-docs: A javadoc jar file.
• name-pom: The pom.xml file.
• name.publish: To be executed by bazel run to publish to a maven repo.

PARAMETERS

Name	Description	Default Value
name	A unique name for this target	none
maven_coordinates	The maven coordinates for this target.	none
manifest_entries	A dict of String: String containing additional manifest entry attributes and values.	{}
deploy_env	A list of labels of Java targets to exclude from the generated jar. java_binary targets are not supported.	[]
excluded_workspaces	A dict of strings representing the workspace names of artifacts that should not be included in the maven jar to a Label pointing to the dependency that workspace should be replaced by, or None if the exclusion shouldn't be replaced with an extra dependency.	{"com_google_protobuf": None, "protobuf": None}
exclusions	Mapping of target labels to a list of exclusions to be added to the POM file. Each label must correspond to a direct maven dependency of this target. Each exclusion is represented as a group:artifact string.	{}
pom_template	The template to be used for the pom.xml file.	None
allowed_duplicate_names	A list of String containing patterns for files that can be included more than once in the jar file. Examples include ["log4j.properties"]	None
visibility	The visibility of the target	None
tags	-	[]
testonly	-	None
classifier_artifacts	A dict of classifier -> artifact of additional artifacts to publish to Maven.	{}
publish_maven_metadata	Whether to publish a maven-metadata.xml to remote repository. Some repositories (like AWS CodeArtifact) require the client to publish this file. It is disabled by default.	False
kwargs	-	none

maven_bom

load("@rules_jvm_external//:defs.bzl", "maven_bom")

maven_bom(name, maven_coordinates, java_exports, bom_pom_template, dependencies_maven_coordinates,
          dependencies_pom_template, tags, testonly, visibility, toolchains)

Generates a Maven BOM pom.xml file and an optional "dependencies" pom.xml.

The generated BOM will contain a list of all the coordinates of the java_export targets in the java_exports parameters. An optional dependencies artifact will be created if the parameter dependencies_maven_coordinates is set.

Both the BOM and dependencies artifact can be templatised to support customisation, but a sensible default template will be used if none is provided. The template used is derived from the (optional) pom_template argument, and the following substitutions are performed on the template file:

• {groupId}: Replaced with the maven coordinates group ID.
• {artifactId}: Replaced with the maven coordinates artifact ID.
• {version}: Replaced by the maven coordinates version.
• {dependencies}: Replaced by a list of maven dependencies directly relied upon by java_library targets within the artifact.

To publish, call the implicit *.publish target(s).

The maven repository may accessed locally using a file:// URL, or remotely using an https:// URL. The following flags may be set using --define:

• gpg_sign: Whether to sign artifacts using GPG
• maven_repo: A URL for the repo to use. May be "https" or "file".
• maven_user: The user name to use when uploading to the maven repository.
• maven_password: The password to use when uploading to the maven repository.

When signing with GPG, the current default key is used.

Generated rules:

• name: The BOM file itself.
• name.publish: To be executed by bazel run to publish the BOM to a maven repo
• name-dependencies: The BOM file for the dependencies pom.xml. Only generated if dependencies_maven_coordinates is set.
• name-dependencies.publish: To be executed by bazel run to publish the dependencies pom.xml to a maven rpo. Only generated if dependencies_maven_coordinates is set.

PARAMETERS

Name	Description	Default Value
name	A unique name for this rule.	none
maven_coordinates	The maven coordinates of this BOM in groupId:artifactId:version form.	none
java_exports	A list of java_export targets that are used to generate the BOM.	none
bom_pom_template	A template used for generating the pom.xml of the BOM at maven_coordinates (optional)	None
dependencies_maven_coordinates	The maven coordinates of a dependencies artifact to generate in GAV format. If empty, none will be generated. (optional)	None
dependencies_pom_template	A template used for generating the pom.xml of the dependencies artifact at dependencies_maven_coordinates (optional)	None
tags	-	None
testonly	-	None
visibility	-	None
toolchains	-	[]

maven_install

load("@rules_jvm_external//:defs.bzl", "maven_install")

maven_install(name, repositories, artifacts, boms, resolver, fail_on_missing_checksum,
              fetch_sources, fetch_javadoc, excluded_artifacts, generate_compat_repositories,
              version_conflict_policy, maven_install_json, override_targets, strict_visibility,
              strict_visibility_value, resolve_timeout, additional_netrc_lines,
              use_credentials_from_home_netrc_file, fail_if_repin_required,
              use_starlark_android_rules, aar_import_bzl_label, duplicate_version_warning,
              repin_instructions, ignore_empty_files, additional_coursier_options)

Resolves and fetches artifacts transitively from Maven repositories.

This macro runs a repository rule that invokes the Coursier CLI to resolve and fetch Maven artifacts transitively.

PARAMETERS

Name	Description	Default Value
name	A unique name for this Bazel external repository.	"maven"
repositories	A list of Maven repository URLs, specified in lookup order. Supports URLs with HTTP Basic Authentication, e.g. "https://username:password@example.com".	[]
artifacts	A list of Maven artifact coordinates in the form of group:artifact:version.	[]
boms	A list of Maven artifact coordinates in the form of group:artifact:version which refer to Maven BOMs.	[]
resolver	Which resolver to use. One of coursier, gradle or maven.	"coursier"
fail_on_missing_checksum	fail the fetch if checksum attributes are not present.	True
fetch_sources	Additionally fetch source JARs.	False
fetch_javadoc	Additionally fetch javadoc JARs.	False
excluded_artifacts	A list of Maven artifact coordinates in the form of group:artifact to be excluded from the transitive dependencies.	[]
generate_compat_repositories	Additionally generate repository aliases in a .bzl file for all JAR artifacts. For example, @maven//:com_google_guava_guava can also be referenced as @com_google_guava_guava//jar.	False
version_conflict_policy	Policy for user-defined vs. transitive dependency version conflicts. If "pinned", choose the user's version unconditionally. If "default", follow Coursier's default policy.	"default"
maven_install_json	A label to a maven_install.json file to use pinned artifacts for generating build targets. e.g //:maven_install.json.	None
override_targets	A mapping of group:artifact to Bazel target labels. All occurrences of the target label for group:artifact will be an alias to the specified label, therefore overriding the original generated jvm_import or aar_import target.	{}
strict_visibility	Controls visibility of transitive dependencies. If True, transitive dependencies are private and invisible to user's rules. If False, transitive dependencies are public and visible to user's rules.	False
strict_visibility_value	Allows changing transitive dependencies strict visibility scope from private to specified scopes list.	["//visibility:private"]
resolve_timeout	The execution timeout of resolving and fetching artifacts.	600
additional_netrc_lines	Additional lines prepended to the netrc file used by http_file (with maven_install_json only).	[]
use_credentials_from_home_netrc_file	Whether to pass machine login credentials from the ~/.netrc file to coursier.	False
fail_if_repin_required	Whether to fail the build if the required maven artifacts have been changed but not repinned. Requires the maven_install_json to have been set.	True
use_starlark_android_rules	Whether to use the native or Starlark version of the Android rules. Default is False if the running version of Bazel supports native aar_import. If the running version of Bazel does not support native aar_import, this parameter is ignored and the Starlark Android rules is used.	False
aar_import_bzl_label	The label (as a string) to use to import aar_import from. This is usually needed only if the top-level workspace file does not use the typical default repository name to import the Android Starlark rules. Default is "@rules_android//rules:rules.bzl".	"@rules_android//rules:rules.bzl"
duplicate_version_warning	What to do if an artifact is specified multiple times. If "error" then fail the build, if "warn" then print a message and continue, if "none" then do nothing. The default is "warn".	"warn"
repin_instructions	Instructions to re-pin dependencies in your repository. Will be shown when re-pinning is required.	None
ignore_empty_files	Treat jars that are empty as if they were not found.	False
additional_coursier_options	Additional options that will be passed to coursier.	[]

Maven specification functions

These are helper functions to specify more information about Maven artifacts and repositories in maven_install.

To use these functions, load the maven struct at the top of your BUILD file:

load("@rules_jvm_external//:specs.bzl", "maven")