Rename .resolve targets (deprecated) to .lock targets (consistency wi…

…th apko 0.13+) (#47) This PR is on top of: #41. Please review only the last commit: [Rename .resolve targets (deprecated) to .lock targets.](7ff68b2) Rename .resolve targets (deprecated) to .lock targets. This makes the naming uniform across apko (0.13+) and rules_apko. The old rules still exist, but emit a warning. From now going on, please use: `*.lock.json` file naming instead of `*.resolved.json`. Also `bazel run .../image.resolve` rule is deprecated and instead `bazel run .../image.lock` should be used.
chainguard-dev · Jan 18, 2024 · 1c20810 · 1c20810
1 parent fa607f9
commit 1c20810
Show file tree

Hide file tree

Showing 24 changed files with 247 additions and 235 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -2,4 +2,4 @@ docs/*.md linguist-generated=true
 docs/initial-setup.md linguist-generated=false
 docs/apko-cache.md linguist-generated=false
 MODULE.bazel.lock linguist-generated=true
-**/apko.resolved.json linguist-generated=true
+**/apko.lock.json linguist-generated=true
diff --git a/.prettierignore b/.prettierignore
@@ -1,2 +1,3 @@
 docs/*.md
-**/*.resolved.json
+**/*.resolved.json
+**/*.lock.json
diff --git a/MODULE.bazel b/MODULE.bazel
@@ -31,19 +31,19 @@ apk = use_extension(
 )
 apk.translate_lock(
     name = "examples_lock",
-    lock = "//examples/lock:apko.resolved.json",
+    lock = "//examples/lock:apko.lock.json",
 )
 apk.translate_lock(
     name = "examples_wolfi_base",
-    lock = "//examples/wolfi-base:apko.resolved.json",
+    lock = "//examples/wolfi-base:apko.lock.json",
 )
 apk.translate_lock(
     name = "examples_oci",
-    lock = "//examples/oci:apko.resolved.json",
+    lock = "//examples/oci:apko.lock.json",
 )
 apk.translate_lock(
     name = "examples_multi_arch_and_repo",
-    lock = "//examples/multi_arch_and_repo:apko.resolved.json",
+    lock = "//examples/multi_arch_and_repo:apko.lock.json",
 )
 use_repo(apk, "examples_multi_arch_and_repo")
 use_repo(apk, "examples_lock")

diff --git a/README.md b/README.md
@@ -20,10 +20,10 @@ using the GitHub-provided source archive like
 
 ## Usage
 
-Apko usage begins with an `apko.yaml` configuration file. The `apko resolve` tool will create a corresponding
-`apko.resolved.json` file, and this is where Bazel will read to fetch external content.
+Apko usage begins with an `apko.yaml` configuration file. The `apko lock` tool will create a corresponding
+`apko.lock.json` file, and this is where Bazel will read to fetch external content.
 Assuming `apko_rules` are already loaded in your `MODULE.bazel` or `WORKSPACE` file one can call:
-`bazel run @rules_apko//apko resolve ./apko.yaml` to lock the dependencies and generate `apko.resolved.json` file.
+`bazel run @rules_apko//apko lock ./apko.yaml` to lock the dependencies and generate `apko.lock.json` file.
 
 Than you import these base layers into Bazel:
 
@@ -32,10 +32,10 @@ Than you import these base layers into Bazel:
 
 Now you can use the `apko_image` rule to build the image, producing an OCI format output.
 As long as the apko `.yaml` file is in the same directory as the `apko_image` you can periodically refresh the
-`apko.resolved.json` file by just calling: `bazel run path/to/image.resolve`.
-Alternatively you can call `apko resolve path/to/apko.yaml` or `bazel run @rules_apko//apko resolve path/to/apko.yaml`
-to regenerate the `apko.resolved.json` file manually.
-To resolve all the files in the repository, such a [snippet](./examples/resolve.sh) can be useful.
+`apko.lock.json` file by just calling: `bazel run path/to/image.lock`.
+Alternatively you can call `apko lock path/to/apko.yaml` or `bazel run @rules_apko//apko lock path/to/apko.yaml`
+to regenerate the `apko.lock.json` file manually.
+To resolve all the files in the repository, such a [snippet](./examples/lock.sh) can be useful.
 
 Finally, we recommend using <https://github.com/bazel-contrib/rules_oci> as the next step in your Bazel build
 to add application code from your repo as the next layers of the image.
@@ -46,5 +46,5 @@ Also see the `e2e` folder in this repository, where we declare our end-to-end te
 
 ## Public API
 
-- [translate_lock](./docs/translate_lock.md) Repository rules for translating `apko.resolved.json`
+- [translate_lock](./docs/translate_lock.md) Repository rules for translating `apko.lock.json`
 - [rules](./docs/rules.md) Build OCI images from APK packages directly without `Dockerfile`
diff --git a/apko/BUILD.bazel b/apko/BUILD.bazel
@@ -68,8 +68,8 @@ bzl_library(
 )
 
 # Enables calling apko tool directly by bazel.
-# To resolve given `./apko.yaml` file into `./apko.resolved.json`, once can call:
-#   e.g. (cd ./examples/oci; bazel run @rules_apko//apko resolve ./apko.yaml)
+# To resolve given `./apko.yaml` file into `./apko.lock.json`, once can call:
+#   e.g. (cd ./examples/oci; bazel run @rules_apko//apko lock ./apko.yaml)
 apko_run(
     name = "apko",
     visibility = ["//visibility:public"],

diff --git a/apko/private/apk.bzl b/apko/private/apk.bzl
@@ -180,7 +180,7 @@ def _apk_filegroup_impl(ctx):
 apk_filegroup = rule(
     implementation = _apk_filegroup_impl,
     attrs = {
-        "lockfile": attr.label(doc = "Label to the `apko.resolved.json` file.", allow_single_file = True, mandatory = True),
+        "lockfile": attr.label(doc = "Label to the `apko.lock.json` file.", allow_single_file = True, mandatory = True),
         "keyrings": attr.label_list(doc = "Labels of the keyring (public key) files.", allow_files = True, mandatory = True),
         "apks": attr.label_list(doc = "Labels of the package (apk) files.", allow_files = True, mandatory = True),
         "indexes": attr.label_list(doc = "Labels of the APKINDEX files.", allow_files = True, mandatory = True),

diff --git a/apko/private/apko_image.bzl b/apko/private/apko_image.bzl
@@ -102,7 +102,7 @@ def apko_image(name, contents, config, tag, output = "oci", architecture = None,
     )
     ```
 
-    The label `@example_lock//:contents` is generated by the `translate_lock` extension, which consumes an 'apko.resolved.json' file.
+    The label `@example_lock//:contents` is generated by the `translate_lock` extension, which consumes an 'apko.lock.json' file.
     For more details, refer to the [documentation](./docs/apko-cache.md).
 
     An example demonstrating usage with [rules_oci](https://github.com/bazel-contrib/rules_oci)
@@ -145,8 +145,18 @@ def apko_image(name, contents, config, tag, output = "oci", architecture = None,
     )
     config_label = native.package_relative_label(config)
 
-    # We generate the `.resolve` target only if the config (apko.yaml file) is in the same package as the apko_image rule.
+    # We generate the `.lock` (or `.resolve`)s target only if the config (apko.yaml file) is in the same package as the apko_image rule.
     if config_label.workspace_name == "" and config_label.package == native.package_name() and config_label.name.endswith(".yaml"):
+        lock_json_name = config_label.name.removesuffix(".yaml") + ".lock.json"
+
+        # We generate the .lock target only if the `.apko.lock.json` file exists in the same package.
+        for _ in native.glob([lock_json_name]):
+            apko_run(
+                name = name + ".lock",
+                args = ["lock", config_label.package + "/" + config_label.name],
+                workdir = "workspace",
+            )
+
         resolved_json_name = config_label.name.removesuffix(".yaml") + ".resolved.json"
 
         # We generate the .resolve target only if the `.apko.resolved.json` file exists in the same package.
@@ -155,4 +165,5 @@ def apko_image(name, contents, config, tag, output = "oci", architecture = None,
                 name = name + ".resolve",
                 args = ["resolve", config_label.package + "/" + config_label.name],
                 workdir = "workspace",
+                deprecated = "Please use .lock target instead. Rename your .resolve.json file to .lock.json file.",
             )
diff --git a/apko/translate_lock.bzl b/apko/translate_lock.bzl
@@ -1,8 +1,8 @@
-"""Repository rules for translating apko.resolved.json"""
+"""Repository rules for translating apko.lock.json"""
 
 load("//apko/private:util.bzl", "util")
 
-_DOC = """Repository rule to generate starlark code from an `apko.resolved.json` file.
+_DOC = """Repository rule to generate starlark code from an `apko.lock.json` file.
 
 See [apko-cache.md](./apko-cache.md) documentation.
 """
@@ -64,7 +64,7 @@ APK_KEYRING_TMPL = """\
 def _translate_apko_lock_impl(rctx):
     lock_file = util.parse_lock(rctx.read(rctx.attr.lock))
 
-    # We copy the lockfile (.resolved.json) to avoid visibility problems when we reference it from another module.
+    # We copy the lockfile (.lock.json) to avoid visibility problems when we reference it from another module.
     lock_file_local = "lockfile_copy"
     rctx.symlink(rctx.attr.lock, lock_file_local)
 
@@ -124,7 +124,7 @@ def _translate_apko_lock_impl(rctx):
 translate_apko_lock = repository_rule(
     implementation = _translate_apko_lock_impl,
     attrs = {
-        "lock": attr.label(doc = "label to the `apko.resolved.json` file.", mandatory = True),
+        "lock": attr.label(doc = "label to the `apko.lock.json` file.", mandatory = True),
         "target_name": attr.string(doc = "internal. do not use!"),
     },
     doc = _DOC,

diff --git a/docs/apko-cache.md b/docs/apko-cache.md
@@ -2,15 +2,15 @@
 
 To ensure efficient operation, the `apko_image` rule must maintain a cache of remote contents that it fetches from repositories. While outside of Bazel, `apko` manages its own cache, under Bazel, the cache must be maintained by Bazel to ensure correctness and speed. Therefore, Bazel needs to know what needs to be fetched and from where to cache these HTTP requests and provide them to `apko` as required.
 
-The `apko.resolved.json` file contains all the necessary information about how to perform the HTTP fetches required by `apko` to build the container image.
+The `apko.lock.json` file contains all the necessary information about how to perform the HTTP fetches required by `apko` to build the container image.
 
 ## Generating the Lock File
 
-> **Note:** Documentation for lockfile generation will be added once the `apko resolve` command is available.
+> **Note:** Documentation for lockfile generation will be added once the `apko lock` command is available.
 
 ## Using `translate_lock`
 
-Having just the `apko.resolved.json` file alone is insufficient; all the information needs to be converted into `apk_<content_type>` repository calls to make them accessible to Bazel. The `translate_lock` tool accomplishes this by taking the `apko.resolved.json` file and dynamically generating the required Bazel repositories.
+Having just the `apko/lock.json` file alone is insufficient; all the information needs to be converted into `apk_<content_type>` repository calls to make them accessible to Bazel. The `translate_lock` tool accomplishes this by taking the `apko.lock.json` file and dynamically generating the required Bazel repositories.
 
 `translate_lock` will create a new bazel repository named after itself. this repository will also have a target named contents, which you can pass to apko_image:
 
@@ -31,7 +31,7 @@ apk = use_extension("//apko:extensions.bzl", "apko")
 
 apk.translate_lock(
     name = "examples_lock",
-    lock = "//path/to/lock:apko.resolved.json",
+    lock = "//path/to/lock:apko.lock.json",
 )
 use_repo(apk, "examples_lock")
 ```
@@ -43,10 +43,10 @@ load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock")
 
 translate_apko_lock(
     name = "example_lock",
-    lock = "//path/to/lock:apko.resolved.json",
+    lock = "//path/to/lock:apko.lock.json",
 )
 
 load("@example_lock//:repositories.bzl", "apko_repositories")
 
 apko_repositories()
-```
+```
diff --git a/docs/rules.md b/docs/rules.md
diff --git a/docs/translate_lock.md b/docs/translate_lock.md
diff --git a/e2e/smoke/MODULE.bazel b/e2e/smoke/MODULE.bazel
@@ -13,6 +13,6 @@ apko = use_extension(
 )
 apko.translate_lock(
     name = "example_lock",
-    lock = "//:apko.resolved.json",
+    lock = "//:apko.lock.json",
 )
 use_repo(apko, "example_lock")
diff --git a/e2e/smoke/WORKSPACE.bazel b/e2e/smoke/WORKSPACE.bazel
@@ -24,7 +24,7 @@ load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock")
 
 translate_apko_lock(
     name = "example_lock",
-    lock = "@//:apko.resolved.json",
+    lock = "@//:apko.lock.json",
 )
 
 load("@example_lock//:repositories.bzl", "apko_repositories")

diff --git a/e2e/smoke/apko.resolved.json → e2e/smoke/apko.lock.json b/e2e/smoke/apko.resolved.json → e2e/smoke/apko.lock.json
diff --git a/examples/resolve.sh → examples/lock.sh b/examples/resolve.sh → examples/lock.sh
@@ -4,7 +4,7 @@
 
 set -e -x
 
-TARGETS=$(bazel query 'filter(".resolve$", kind("apko_run", ...))')
+TARGETS=$(bazel query 'filter(".lock", kind("apko_run", ...))')
 for target in ${TARGETS}; do 
   bazel run "${target}"
 done

diff --git a/examples/lock/BUILD.bazel b/examples/lock/BUILD.bazel
@@ -2,7 +2,7 @@ load("@rules_apko//apko:defs.bzl", "apko_image")
 load("@bazel_skylib//rules:build_test.bzl", "build_test")
 
 # An example demonstrating how to use alpine packages with a lock file.
-# See MODULE.bazel for how apko.resolved.json is translated to @examples_lock//:contents
+# See MODULE.bazel for how apko.lock.json is translated to @examples_lock//:contents
 apko_image(
     name = "lock",
     config = "apko.yaml",

diff --git a/examples/lock/apko.resolved.json → examples/lock/apko.lock.json b/examples/lock/apko.resolved.json → examples/lock/apko.lock.json
diff --git a/examples/multi_arch_and_repo/BUILD.bazel b/examples/multi_arch_and_repo/BUILD.bazel
@@ -2,7 +2,7 @@ load("@rules_apko//apko:defs.bzl", "apko_image")
 load("@container_structure_test//:defs.bzl", "container_structure_test")
 
 # An example demonstrating how to use multi architecture alpine packages with a lock file.
-# See MODULE.bazel for how apko.resolved.json is translated to @examples_multi_arch_and_repo//:contents
+# See MODULE.bazel for how apko.lock.json is translated to @examples_multi_arch_and_repo//:contents
 apko_image(
     name = "image",
     architecture = select({