diff --git a/docs/BUILD b/docs/BUILD index 1a25e518c..84a80f021 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -1,5 +1,5 @@ +load("@bazel_skylib//rules:diff_test.bzl", "diff_test") load("@bazel_skylib//rules:write_file.bzl", "write_file") -load("@build_bazel_rules_nodejs//:index.bzl", "generated_file_test") load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") # Workaround https://github.com/bazelbuild/stardoc/issues/25 @@ -17,8 +17,24 @@ stardoc( deps = ["//container:image"], ) -generated_file_test( - name = "copy_image", - src = "image.md", - generated = ":image.md_", +diff_test( + name = "check_image_doc", + file1 = ":image_doc", + file2 = "image.md", +) + +write_file( + name = "gen_update", + out = "update.sh", + content = [ + "#!/usr/bin/env bash", + "cd $BUILD_WORKSPACE_DIRECTORY", + "cp -fv bazel-bin/docs/image.md_ docs/image.md", + ], +) + +sh_binary( + name = "update", + srcs = ["update.sh"], + data = [":image_doc"], ) diff --git a/docs/image.md b/docs/image.md index 6a8f06989..429944a8c 100644 --- a/docs/image.md +++ b/docs/image.md @@ -9,14 +9,14 @@ more specialized build leveraging the same implementation. ## container_image_ 
-container_image_(name, architecture, base, build_layer, cmd, compression, compression_options,
-                 create_image_config, creation_time, data_path, debs, directory, docker_run_flags,
-                 empty_dirs, empty_files, enable_mtime_preservation, entrypoint, env,
-                 experimental_tarball_format, extract_config, files, incremental_load_template,
+container_image_(name, architecture, base, build_context_data, build_layer, cmd, compression,
+                 compression_options, create_image_config, creation_time, data_path, debs, directory,
+                 docker_run_flags, empty_dirs, empty_files, enable_mtime_preservation, entrypoint,
+                 env, experimental_tarball_format, extract_config, files, incremental_load_template,
                  label_file_strings, label_files, labels, launcher, launcher_args, layers,
                  legacy_repository_naming, legacy_run_behavior, mode, mtime, null_cmd,
                  null_entrypoint, operating_system, os_version, portable_mtime, ports, repository,
-                 sha256, stamp, symlinks, tars, user, volumes, workdir)
+                 sha256, symlinks, tars, user, volumes, workdir)
Called by the `container_image` macro with **kwargs, see below @@ -29,6 +29,7 @@ Called by the `container_image` macro with **kwargs, see below | name | A unique name for this target. | Name | required | | | architecture | The desired CPU architecture to be used as label in the container image. | String | optional | "amd64" | | base | The base layers on top of which to overlay this layer, equivalent to FROM. | Label | optional | None | +| build_context_data | Provides info about the build context, such as stamping.

By default it reads from the bazel command line, such as the --stamp argument. Use this to override values for this target, such as enabling or disabling stamping. You can use the build_context_data rule from @io_bazel_rules_docker//docker:context.bzl to create a BuildContextInfo and override the --stamp config setting. | Label | optional | @io_bazel_rules_docker//docker:build_context_data | | build_layer | - | Label | optional | //container:build_tar | | cmd | List of commands to execute in the image.

See https://docs.docker.com/engine/reference/builder/#cmd

The behavior between using "" and [] may differ. Please see [#1448](https://github.com/bazelbuild/rules_docker/issues/1448) for more details.

Set cmd to None, [] or "" will set the Cmd of the image to be null.

This field supports stamp variables. | List of strings | optional | [] | | compression | Compression method for image layer. Currently only gzip is supported.

This affects the compressed layer, which is by the container_push rule. It doesn't affect the layers specified by the layers attribute. | String | optional | "gzip" | @@ -66,7 +67,6 @@ Called by the `container_image` macro with **kwargs, see below | ports | List of ports to expose.

See https://docs.docker.com/engine/reference/builder/#expose | List of strings | optional | [] | | repository | The repository for the default tag for the image.

Images generated by container_image are tagged by default to bazel/package_name:target for a container_image target at //package/name:target.

Setting this attribute to gcr.io/dummy would set the default tag to gcr.io/dummy/package_name:target. | String | optional | "bazel" | | sha256 | - | Label | optional | //tools/build_defs/hash:sha256 | -| stamp | If true, enable use of workspace status variables (e.g. BUILD_USER, BUILD_EMBED_LABEL, and custom values set using --workspace_status_command) in tags.

These fields are specified in attributes using Python format syntax, e.g. foo{BUILD_USER}bar. | Boolean | optional | False | | symlinks | Symlinks to create in the Docker image.

For example,

symlinks = { "/path/to/link": "/path/to/target", ... }, | Dictionary: String -> String | optional | {} | | tars | Tar file to extract in the layer.

A list of tar files whose content should be in the Docker image. | List of labels | optional | [] | | user | The user that the image should run as.

See https://docs.docker.com/engine/reference/builder/#user

Because building the image never happens inside a Docker container, this user does not affect the other actions (e.g., adding files).

This field supports stamp variables. | String | optional | "" |