api.md

API Reference

• Basic functions
  • javadoc
  • java_export
  • maven_install
• Maven specification functions
  • maven.repository
  • maven.artifact
  • maven.exclusion

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

javadoc(name, deps, 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
javadocopts	javadoc options. Note sources and classpath are derived from the deps. Any additional options can be passed here.	List of strings	optional	[]

java_export

java_export(name, maven_coordinates, deploy_env, pom_template, visibility, tags, 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):

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

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 coordintes type, if present (defaults to "jar")
• {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
deploy_env	A list of labels of java targets to exclude from the generated jar	[]
pom_template	The template to be used for the pom.xml file.	None
visibility	The visibility of the target	None
tags	-	[]
kwargs	These are passed to java_library, and so may contain any valid parameter for that rule.	none

maven_install

maven_install(name, repositories, artifacts, fail_on_missing_checksum, fetch_sources, fetch_javadoc,
              use_unsafe_shared_cache, excluded_artifacts, generate_compat_repositories,
              version_conflict_policy, maven_install_json, override_targets, strict_visibility,
              resolve_timeout, jetify, jetify_include_list, additional_netrc_lines,
              fail_if_repin_required, use_starlark_android_rules, aar_import_bzl_label,
              duplicate_version_warning)

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.	[]
fail_on_missing_checksum	-	True
fetch_sources	Additionally fetch source JARs.	False
fetch_javadoc	Additionally fetch javadoc JARs.	False
use_unsafe_shared_cache	Download artifacts into a persistent shared cache on disk. Unsafe as Bazel is currently unable to detect modifications to the cache.	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
resolve_timeout	The execution timeout of resolving and fetching artifacts.	600
jetify	Runs the AndroidX Jetifier tool on artifacts specified in jetify_include_list. If jetify_include_list is not specified, run Jetifier on all artifacts.	False
jetify_include_list	List of artifacts that need to be jetified in groupId:artifactId format. By default all artifacts are jetified if jetify is set to True.	["*"]
additional_netrc_lines	Additional lines prepended to the netrc file used by http_file (with maven_install_json only).	[]
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.	False
use_starlark_android_rules	Whether to use the native or Starlark version of the Android rules. Default is False.	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 "@build_bazel_rules_android//rules:rules.bzl".	"@build_bazel_rules_android//android: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"

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")

maven.repository

maven.repository(url, user, password)

Generates the data map for a Maven repository specifier given the available information.

If both a user and password are given as arguments, it will include the access credentials in the repository spec. If one or both are missing, it will just generate the repository url.

PARAMETERS

Name	Description	Default Value
url	A string containing the repository url (ex: "https://maven.google.com/").	none
user	A username for this Maven repository, if it requires authentication (ex: "johndoe").	None
password	A password for this Maven repository, if it requires authentication (ex: "example-password").	None

maven.artifact

maven.artifact(group, artifact, version, packaging, classifier, override_license_types, exclusions,
               neverlink, testonly)

Generates the data map for a Maven artifact given the available information about its coordinates.

PARAMETERS

Name	Description	Default Value
group	The Maven artifact coordinate group name (ex: "com.google.guava").	none
artifact	The Maven artifact coordinate artifact name (ex: "guava").	none
version	The Maven artifact coordinate version name (ex: "27.0-jre").	none
packaging	The Maven packaging specifier (ex: "jar").	None
classifier	The Maven artifact classifier (ex: "javadoc").	None
override_license_types	An array of Bazel license type strings to use for this artifact's rules (overrides autodetection) (ex: ["notify"]).	None
exclusions	An array of exclusion objects to create exclusion specifiers for this artifact (ex: maven.exclusion("junit", "junit")).	None
neverlink	Determines if this artifact should be part of the runtime classpath.	None
testonly	Determines whether this artifact is available for targets not marked as testonly = True.	None

maven.exclusion

maven.exclusion(group, artifact)

Generates the data map for a Maven artifact exclusion.

PARAMETERS

Name	Description	Default Value
group	The Maven group name of the dependency to exclude, e.g. "com.google.guava".	none
artifact	The Maven artifact name of the dependency to exclude, e.g. "guava".	none