diff --git a/.gitattributes b/.gitattributes index 474baa3..315ed72 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,5 +1,2 @@ -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.lock.json linguist-generated=true \ No newline at end of file diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index de2db88..3cd7a33 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -104,15 +104,8 @@ jobs: - name: Test working-directory: ${{ matrix.folder }} - if: ${{ matrix.bazelversion >= '9.' || matrix.folder != '.' }} run: bazel test //... - # Stardoc has output changes between versions - - name: Test no doc 8 and lower - working-directory: ${{ matrix.folder }} - if: ${{ matrix.bazelversion <= '8.' && matrix.folder == '.' }} - run: bazel query 'tests(//...) except docs/...' | xargs bazel test - # Single summary gate that aggregates the dynamic test matrix. Branch # protection only needs to require this one context, so the Bazel version # matrix above can change without an infra change to the required checks. diff --git a/MODULE.bazel b/MODULE.bazel index 61aaaf4..df2651f 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -14,7 +14,6 @@ bazel_dep(name = "rules_oci", version = "2.3.0", dev_dependency = True) bazel_dep(name = "gazelle", version = "0.52.2", dev_dependency = True, repo_name = "bazel_gazelle") bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "1.9.2", dev_dependency = True) bazel_dep(name = "buildifier_prebuilt", version = "8.5.1.3", dev_dependency = True) -bazel_dep(name = "stardoc", version = "0.8.1", dev_dependency = True, repo_name = "io_bazel_stardoc") toolchain = use_extension("//apko:extensions.bzl", "apko") toolchain.toolchain(apko_version = "v1.2.40") diff --git a/README.md b/README.md index 0f209f8..f5ab1ed 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,66 @@ See the examples folder in this repository, which relies on base layers declared Also see the `e2e` folder in this repository, where we declare our end-to-end test. +## Fetching and Caching Contents + +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.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 lock` command is available. + +### Using `translate_lock` + +Having just the `apko/lock.json` file alone is insufficient; all the information needs to be converted into `apk_` 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: + +```starlark +apko_image( + name = "lock", + config = "apko.yaml", + # name of the repository is the same translate_lock! + contents = "@examples_lock//:contents", + tag = "lock:latest", +) +``` + +#### Usage with `bzlmod` + +```starlark +apk = use_extension("@rules_apko//apko:extensions.bzl", "apko") + +apk.translate_lock( + name = "examples_lock", + lock = "//path/to/lock:apko.lock.json", +) +use_repo(apk, "examples_lock") +``` + +#### Usage with Workspace + +```starlark +load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock") + +translate_apko_lock( + name = "example_lock", + lock = "//path/to/lock:apko.lock.json", +) + +load("@example_lock//:repositories.bzl", "apko_repositories") + +apko_repositories() +``` + ## Public API -- [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` +The API reference is generated from the sources and rendered on the Bazel +Central Registry: + +- `translate_lock` Repository rules for translating `apko.lock.json` +- `apko_image` Build OCI images from APK packages directly without `Dockerfile` + +See [Fetching and Caching Contents](#fetching-and-caching-contents) for how +contents are fetched and cached. diff --git a/apko/private/apko_image.bzl b/apko/private/apko_image.bzl index 8c40947..31e9645 100644 --- a/apko/private/apko_image.bzl +++ b/apko/private/apko_image.bzl @@ -6,7 +6,7 @@ load("//apko/private:apko_config.bzl", "copy_to_workdir", "prepare_apko_config_i load("//apko/private:apko_run.bzl", "apko_run") _ATTRS = { - "contents": attr.label(doc = "Label to the contents repository generated by translate_lock. See [apko-cache](./apko-cache.md) documentation.", mandatory = True, providers = [OutputGroupInfo]), + "contents": attr.label(doc = "Label to the contents repository generated by translate_lock. See the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation.", mandatory = True, providers = [OutputGroupInfo]), "config": attr.label(doc = "Label to the `apko.yaml` file.", allow_single_file = True, mandatory = True), "output": attr.string(default = "oci", values = ["oci", "docker"]), "architecture": attr.string(doc = "the CPU architecture which this image should be built to run on. See https://github.com/chainguard-dev/apko/blob/main/docs/apko_file.md#archs-top-level-element"), @@ -152,7 +152,7 @@ def apko_image( ``` 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). + For more details, refer to the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation. An example demonstrating usage with [rules_oci](https://github.com/bazel-contrib/rules_oci) @@ -174,7 +174,7 @@ def apko_image( Args: name: of the target for the generated image. - contents: Label to the contents repository generated by translate_lock. See [apko-cache](./apko-cache.md) documentation. + contents: Label to the contents repository generated by translate_lock. See the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation. config: Label to the `apko.yaml` file. For more advanced use-cases (multi-file configuration), use target providing `ApkoConfigInfo` (e.g. output of `apko_config` rule). output: "oci" of "docker", diff --git a/apko/translate_lock.bzl b/apko/translate_lock.bzl index c12e809..1bdcb82 100644 --- a/apko/translate_lock.bzl +++ b/apko/translate_lock.bzl @@ -5,7 +5,7 @@ load("//apko/private:util.bzl", "util") _DOC = """Repository rule to generate starlark code from an `apko.lock.json` file. -See [apko-cache.md](./apko-cache.md) documentation. +See the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation. """ BUILD_TMPL = """\ diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel deleted file mode 100644 index 6e43513..0000000 --- a/docs/BUILD.bazel +++ /dev/null @@ -1,15 +0,0 @@ -# This load statement must be in the docs/ package rather than anything users depend on -# so that the dependency on stardoc doesn't leak to them. -load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs") - -stardoc_with_diff_test( - name = "rules", - bzl_library_target = "//apko:defs", -) - -stardoc_with_diff_test( - name = "translate_lock", - bzl_library_target = "//apko:translate_lock", -) - -update_docs(name = "update") diff --git a/docs/apko-cache.md b/docs/apko-cache.md deleted file mode 100644 index 3daefe9..0000000 --- a/docs/apko-cache.md +++ /dev/null @@ -1,52 +0,0 @@ -# Fetching and Caching Contents - -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.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 lock` command is available. - -## Using `translate_lock` - -Having just the `apko/lock.json` file alone is insufficient; all the information needs to be converted into `apk_` 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: - -```starlark -apko_image( - name = "lock", - config = "apko.yaml", - # name of the repository is the same translate_lock! - contents = "@examples_lock//:contents", - tag = "lock:latest", -) -``` - -#### Usage with `bzlmod` - -```starlark -apk = use_extension("@rules_apko//apko:extensions.bzl", "apko") - -apk.translate_lock( - name = "examples_lock", - lock = "//path/to/lock:apko.lock.json", -) -use_repo(apk, "examples_lock") -``` - -#### Usage with Workspace - -```starlark -load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock") - -translate_apko_lock( - name = "example_lock", - 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 deleted file mode 100644 index 22ede14..0000000 --- a/docs/rules.md +++ /dev/null @@ -1,158 +0,0 @@ - - -Public API re-exports - - - -## apko_config - -
-load("@rules_apko//apko:defs.bzl", "apko_config")
-
-apko_config(name, deps, config)
-
- - - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| deps | List of all dependencies of the config. Transitive dependencies are included based on ApkoConfigInfo provider. | List of labels | optional | `[]` | -| config | Config of the image. Either in source directory or generated by Bazel.

When referencing other files in the config yaml file use paths relative to your Bazel workspace root. For example, if you want to reference source file foo/bar/baz use foo/bar/baz. If you want to reference output file of foo/bar:rule and rule's output file is rule.out, reference it as foo/bar/rule.out. | Label | optional | `None` | - - - - -## apko_show_config - -
-load("@rules_apko//apko:defs.bzl", "apko_show_config")
-
-apko_show_config(name, config)
-
- -Wrapper around `apko show-config` command to generate expanded config as bazel build action. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| config | Label to the `apko.yaml` file. For more advanced use-cases (multi-file configuration), use target providing `ApkoConfigInfo` (e.g. output of `apko_config` rule). | Label | required | | - - - - -## ApkoConfigInfo - -
-load("@rules_apko//apko:defs.bzl", "ApkoConfigInfo")
-
-ApkoConfigInfo(files)
-
- -Information about apko config. May be used when generating apko config file instead of using hardcoded ones. - -When referencing other files in the config yaml file use paths relative to your Bazel workspace root. - For example, if you want to reference source file foo/bar/baz use foo/bar/baz. If you want to reference output file of foo/bar:rule and rule's - output file is rule.out, reference it as foo/bar/rule.out. - -**FIELDS** - -| Name | Description | -| :------------- | :------------- | -| files | depset of files that will be needed for building. All of them will be added to the execution of apko commands when built with Bazel. | - - - - -## apko_image - -
-load("@rules_apko//apko:defs.bzl", "apko_image")
-
-apko_image(name, contents, config, tag, output, architecture, args, **kwargs)
-
- -Build OCI images from APK packages directly without Dockerfile - -This rule creates images using the 'apko.yaml' configuration file and relies on cache contents generated by [translate_lock](./translate_lock.md) to be fast. - -```starlark -apko_image( - name = "example", - config = "apko.yaml", - contents = "@example_lock//:contents", - tag = "example:latest", -) -``` - -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) - -```starlark -apko_image( - name = "alpine_base", - config = "apko.yaml", - contents = "@alpine_base_lock//:contents", - tag = "alpine_base:latest", -) - -oci_image( - name = "app", - base = ":alpine_base" -) -``` - -For more examples checkout the [examples](/examples) directory. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | of the target for the generated image. | none | -| contents | Label to the contents repository generated by translate_lock. See [apko-cache](./apko-cache.md) documentation. | none | -| config | Label to the `apko.yaml` file. For more advanced use-cases (multi-file configuration), use target providing `ApkoConfigInfo` (e.g. output of `apko_config` rule). | none | -| tag | tag to apply to the resulting docker tarball. only applicable when `output` is `docker` | none | -| output | "oci" of "docker", | `"oci"` | -| architecture | the CPU architecture which this image should be built to run on. See https://github.com/chainguard-dev/apko/blob/main/docs/apko_file.md#archs-top-level-element"), | `None` | -| args | additional arguments to provide when running the `apko build` command. | `[]` | -| kwargs | other common arguments like: tags, visibility. | none | - - - - -## apko_lock - -
-load("@rules_apko//apko:defs.bzl", "apko_lock")
-
-apko_lock(name, config, lockfile_name, **kwargs)
-
- -Generates executable rule for producing apko lock files. - -When run, the rule will output the lockfile to the lockfile_name in the directory of the package where the rule is defined. -That is, if you define `apko_lock` in `foo/bar/BUILD.bazel` with `lockfile_name="baz.lock.json` the rule will output the lock into -`foo/bar/baz.lock.json`. - - -**PARAMETERS** - - -| Name | Description | Default Value | -| :------------- | :------------- | :------------- | -| name | name of the rule, | none | -| config | label of the apko config. It can be either a source file or generated target. Additionally, if the target provides ApkoConfigInfo provider, the transitive dependencies listed in ApkoConfigInfo.files will be added to runfiles as well. | none | -| lockfile_name | name of the lockfile | none | -| kwargs | the rule inherits standard attributes, like: tags, visibility, and args. | none | - - diff --git a/docs/translate_lock.md b/docs/translate_lock.md deleted file mode 100644 index d18ab8f..0000000 --- a/docs/translate_lock.md +++ /dev/null @@ -1,28 +0,0 @@ - - -Repository rules for translating apko.lock.json - - - -## translate_apko_lock - -
-load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock")
-
-translate_apko_lock(name, lock, target_name)
-
- -Repository rule to generate starlark code from an `apko.lock.json` file. - -See [apko-cache.md](./apko-cache.md) documentation. - -**ATTRIBUTES** - - -| Name | Description | Type | Mandatory | Default | -| :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this repository. | Name | required | | -| lock | label to the `apko.lock.json` file. | Label | required | | -| target_name | internal. do not use! | String | optional | `""` | - -