diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index 24f42da6..1dc19d99 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -18,7 +18,11 @@ stardoc_with_diff_test( stardoc_with_diff_test( name = "image_index", - bzl_library_target = "//oci/private:image_index", + bzl_library_target = "//oci:defs", + symbol_names = [ + "oci_image_index_rule", + "oci_image_index", + ], ) stardoc_with_diff_test( diff --git a/docs/image_index.md b/docs/image_index.md index df5c9c41..483ad4ca 100644 --- a/docs/image_index.md +++ b/docs/image_index.md @@ -1,13 +1,17 @@ -Implementation details for oci_image_index rule +To load these rules, add this to the top of your `BUILD` file: - +```starlark +load("@rules_oci//oci:defs.bzl", ...) +``` -## oci_image_index + + +## oci_image_index_rule
-oci_image_index(name, images)
+oci_image_index_rule(name, images)
 
Build a multi-architecture OCI compatible container image. @@ -39,7 +43,30 @@ oci_image_index( | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| images | List of labels to oci_image targets. | List of labels | required | | +| name | A unique name for this target. | Name | required | | +| images | List of labels to oci_image targets. | List of labels | required | | + + + + +## oci_image_index + +
+oci_image_index(name, kwargs)
+
+ +Macro wrapper around [oci_image_index_rule](#oci_image_index_rule). + +Produces a target `[name].digest`, whose default output is a file containing the sha256 digest of the resulting image. +This is the same output as for the `oci_image` macro. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | name of resulting oci_image_index_rule | none | +| kwargs | other named arguments to [oci_image_index_rule](#oci_image_index_rule) and [common rule attributes](https://bazel.build/reference/be/common-definitions#common-attributes). | none | diff --git a/examples/multi_architecture_image/BUILD.bazel b/examples/multi_architecture_image/BUILD.bazel index b63b0240..be5ea278 100644 --- a/examples/multi_architecture_image/BUILD.bazel +++ b/examples/multi_architecture_image/BUILD.bazel @@ -32,16 +32,8 @@ oci_image_index( ], ) -genrule( - name = "hash", - srcs = [":index"], - outs = ["sha256.sum"], - cmd = "$(JQ_BIN) -r '.manifests[0].digest' $(location :index)/index.json > $@", - toolchains = ["@jq_toolchains//:resolved_toolchain"], -) - assert_contains( name = "check_digest", - actual = ":hash", + actual = ":index.digest", expected = "sha256:a2b8ae94672721788b67874f27cf3574fada3ccccc69f483bcb43de653573fe0", ) diff --git a/oci/defs.bzl b/oci/defs.bzl index 845e9804..b44e0f8d 100644 --- a/oci/defs.bzl +++ b/oci/defs.bzl @@ -19,7 +19,7 @@ load("//oci/private:push.bzl", _oci_push = "oci_push") oci_tarball_rule = _oci_tarball oci_image_rule = _oci_image -oci_image_index = _oci_image_index +oci_image_index_rule = _oci_image_index oci_push_rule = _oci_push def _write_nl_seperated_file(name, kind, elems, forwarded_kwargs): @@ -33,6 +33,56 @@ def _write_nl_seperated_file(name, kind, elems, forwarded_kwargs): ) return label +def _digest(name, **kwargs): + # `oci_image_rule` and `oci_image_index_rule` produce a directory as default output. + # Label for the [name]/index.json file + directory_path( + name = "_{}_index_json".format(name), + directory = name, + path = "index.json", + **kwargs + ) + + copy_file( + name = "_{}_index_json_cp".format(name), + src = "_{}_index_json".format(name), + out = "_{}_index.json".format(name), + **kwargs + ) + + # Matches the [name].digest target produced by rules_docker container_image + jq( + name = name + ".digest", + args = ["--raw-output"], + srcs = ["_{}_index.json".format(name)], + filter = """.manifests[0].digest""", + out = name + ".json.sha256", # path chosen to match rules_docker for easy migration + **kwargs + ) + +def oci_image_index(name, **kwargs): + """Macro wrapper around [oci_image_index_rule](#oci_image_index_rule). + + Produces a target `[name].digest`, whose default output is a file containing the sha256 digest of the resulting image. + This is the same output as for the `oci_image` macro. + + Args: + name: name of resulting oci_image_index_rule + **kwargs: other named arguments to [oci_image_index_rule](#oci_image_index_rule) and + [common rule attributes](https://bazel.build/reference/be/common-definitions#common-attributes). + """ + forwarded_kwargs = propagate_common_rule_attributes(kwargs) + + oci_image_index_rule( + name = name, + **kwargs + ) + + _digest( + name = name, + **forwarded_kwargs + ) + def oci_image( name, created = None, @@ -159,29 +209,8 @@ def oci_image( **kwargs ) - # `oci_image_rule` produces a directory as default output. - # Label for the [name]/index.json file - directory_path( - name = "_{}_index_json".format(name), - directory = name, - path = "index.json", - **forwarded_kwargs - ) - - copy_file( - name = "_{}_index_json_cp".format(name), - src = "_{}_index_json".format(name), - out = "_{}_index.json".format(name), - **forwarded_kwargs - ) - - # Matches the [name].digest target produced by rules_docker container_image - jq( - name = name + ".digest", - args = ["--raw-output"], - srcs = ["_{}_index.json".format(name)], - filter = """.manifests[0].digest""", - out = name + ".json.sha256", # path chosen to match rules_docker for easy migration + _digest( + name = name, **forwarded_kwargs )