From cf3d56729e7b1b218a1437a38c39ea3644a05261 Mon Sep 17 00:00:00 2001 From: Jin Date: Fri, 19 Jul 2019 06:42:20 -0400 Subject: [PATCH] Expand artifact pinning documentation (#205) * Expand on the documentation for artifact pinning and reorder it to make it more prominent. * Update README.md --- README.md | 91 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 08c6688a7..225c6d354 100644 --- a/README.md +++ b/README.md @@ -76,65 +76,36 @@ android_library( ) ``` -### Generated targets - -For the `junit:junit` example, using `bazel query @maven//:all --output=build`, we can see that the rule generated these targets: - -```python -alias( - name = "junit_junit_4_12", - actual = "@maven//:junit_junit", -) - -jvm_import( - name = "junit_junit", - jars = ["@maven//:https/repo1.maven.org/maven2/junit/junit/4.12/junit-4.12.jar"], - srcjar = "@maven//:https/repo1.maven.org/maven2/junit/junit/4.12/junit-4.12-sources.jar", - deps = ["@maven//:org_hamcrest_hamcrest_core"], - tags = ["maven_coordinates=junit:junit:4.12"], -) - -jvm_import( - name = "org_hamcrest_hamcrest_core", - jars = ["@maven//:https/repo1.maven.org/maven2/org/hamcrest/hamcrest-core/1.3/hamcrest-core-1.3.jar"], - srcjar = "@maven//:https/repo1.maven.org/maven2/org/hamcrest/hamcrest-core/1.3/hamcrest-core-1.3-sources.jar", - deps = [], - tags = ["maven_coordinates=org.hamcrest:hamcrest.library:1.3"], -) -``` - -The generated `tags` attribute value also contains the original coordinates of -the artifact, which integrates with rules like [bazel-common's -`pom_file`](https://github.com/google/bazel-common/blob/f1115e0f777f08c3cdb115526c4e663005bec69b/tools/maven/pom_file.bzl#L177) -for generating POM files. See the [`pom_file_generation` -example](examples/pom_file_generation/) for more information. - ## API Reference You can find the complete API reference at [docs/api.md](docs/api.md). -## Pinning artifacts +## Pinning artifacts and integration with Bazel's downloader `rules_jvm_external` supports pinning artifacts and their SHA-256 checksums into -a `maven_install.json` file that can be checked into your repository. +a `maven_install.json` file that can be checked into your repository. + +Without artifact pinning, in a clean checkout of your project, `rules_jvm_external` +executes the full artifact resolution and fetching steps (which can take a bit of time) +and does not verify the integrity of the artifacts against their checksums. The +downloaded artifacts also cannot be shared across Bazel workspaces. -By pinning artifact versions, you can get improved artifact resolution and fetch -speed, since `rules_jvm_external` will use Bazel's download mechanism that -caches files on their sha256 checksums. It also improves resiliency and +By pinning artifact versions, you can get improved artifact resolution and build times, +since using `maven_install.json` enables `rules_jvm_external` to integrate with Bazel's +downloader that caches files on their sha256 checksums. It also improves resiliency and integrity by tracking the sha256 checksums and original artifact urls in the JSON file. Since all artifacts are persisted locally in Bazel's cache, it means that **fully offline builds are possible** after the initial `bazel fetch @maven//...`. -To get started with pinning artifacts, run the following command: +To get started with pinning artifacts, run the following command to generate the +initial `maven_install.json` at the root of your Bazel workspace: ``` $ bazel run @maven//:pin ``` -This generates a `maven_install.json` in the root of your Bazel workspace. - Then, specify `maven_install_json` in `maven_install` and load `pinned_maven_install` from `@maven//:defs.bzl`: @@ -156,14 +127,16 @@ repository: $ bazel run @unpinned_maven//:pin ``` +Note that the repository is `@unpinned_maven` instead of `@maven`. + When using artifact pinning, each `maven_install` repository (e.g. `@maven`) will be accompanied by an unpinned repository. This repository name has the `@unpinned_` prefix (e.g.`@unpinned_maven` or `@unpinned_`). For example, if your `maven_install` is named `@foo`, `@unpinned_foo` will be created. -If you have multiple `maven_install` declarations, you will have to alias `pinned_maven_install` to -another name to prevent redefinitions: +If you have multiple `maven_install` declarations, you have to alias +`pinned_maven_install` to another name to prevent redefinitions: ```python maven_install( @@ -185,6 +158,38 @@ load("@bar//:defs.bzl", bar_pinned_maven_install = "pinned_maven_install") bar_pinned_maven_install() ``` +## Generated targets + +For the `junit:junit` example, using `bazel query @maven//:all --output=build`, we can see that the rule generated these targets: + +```python +alias( + name = "junit_junit_4_12", + actual = "@maven//:junit_junit", +) + +jvm_import( + name = "junit_junit", + jars = ["@maven//:https/repo1.maven.org/maven2/junit/junit/4.12/junit-4.12.jar"], + srcjar = "@maven//:https/repo1.maven.org/maven2/junit/junit/4.12/junit-4.12-sources.jar", + deps = ["@maven//:org_hamcrest_hamcrest_core"], + tags = ["maven_coordinates=junit:junit:4.12"], +) + +jvm_import( + name = "org_hamcrest_hamcrest_core", + jars = ["@maven//:https/repo1.maven.org/maven2/org/hamcrest/hamcrest-core/1.3/hamcrest-core-1.3.jar"], + srcjar = "@maven//:https/repo1.maven.org/maven2/org/hamcrest/hamcrest-core/1.3/hamcrest-core-1.3-sources.jar", + deps = [], + tags = ["maven_coordinates=org.hamcrest:hamcrest.library:1.3"], +) +``` + +The generated `tags` attribute value also contains the original coordinates of +the artifact, which integrates with rules like [bazel-common's +`pom_file`](https://github.com/google/bazel-common/blob/f1115e0f777f08c3cdb115526c4e663005bec69b/tools/maven/pom_file.bzl#L177) +for generating POM files. See the [`pom_file_generation` +example](examples/pom_file_generation/) for more information. ## Advanced usage