Adding more details to docker autoconf docs
Change-Id: Id31364756295f48a9a3df43a32bb256de46a1ba3
diff --git a/rules/docker_config.bzl b/rules/docker_config.bzl
index 7ecb45d..f4e430e 100644
--- a/rules/docker_config.bzl
+++ b/rules/docker_config.bzl
@@ -18,11 +18,14 @@
- Receive a base container as main input. Base container could have a desired
set of toolchains (i.e., a C compiler, C libraries, java, python, zip, and
other tools) installed.
-- Optionally, install more debian packages in the base container.
+- Optionally, install more debian packages in the base container (any packages
+ that might be needed by Bazel not installed in your container).
+- Optionally, install a given Bazel version on the container.
- Extend the container to install sources for a project.
-- Run a bazel command to build one or more remote repos inside the container.
-- Copy toolchain configs produced from the execution of Bazel
- inside the container to the host.
+- Run a bazel command to build one or more targets from
+ remote repositories, inside the container.
+- Copy toolchain configs (outputs of remote repo targets) produced
+ from the execution of Bazel inside the container to the host.
- Optionally copy outputs to a folder defined via build variables.
Example:
@@ -30,16 +33,19 @@
docker_toolchain_autoconfig(
name = "my-autoconfig-rule",
base = "@my_image//image:image.tar",
+ bazel_version = "0.10.0",
config_repos = ["local_config_cc", "<some_other_skylark_repo>"],
git_repo = "https://github.com/some_git_repo",
env = {
... Dictionary of env variables to configure Bazel properly
- for the container
+ for the container, see environments.bzl for examples.
},
packages = [
"package_1",
"package_2=version",
],
+ # Any additional debian repos and keys needed to install packages above,
+ # not needed if no packages are installed.
additional_repos = [
"deb http://deb.debian.org/debian jessie-backports main",
],
@@ -48,6 +54,58 @@
],
)
+Add to your WORKSPACE file the following:
+
+ http_archive(
+ name = "bazel_toolchains",
+ urls = [
+ "https://mirror.bazel.build/github.com/bazelbuild/bazel-toolchains/archive/<latest_release>.tar.gz",
+ "https://github.com/bazelbuild/bazel-toolchains/archive/<latest_release>.tar.gz",
+ ],
+ strip_prefix = "bazel-toolchains-<latest_commit>",
+ sha256 = "<sha256>",
+ )
+
+ http_archive(
+ name = "debian_docker",
+ sha256 = "<sha256>",
+ strip_prefix = "base-images-docker-<latest_release>",
+ urls = ["https://github.com/GoogleCloudPlatform/base-images-docker/archive/<latest_release>.tar.gz"],
+ )
+
+ http_archive(
+ name = "io_bazel_rules_docker",
+ sha256 = "<sha256>",
+ strip_prefix = "rules_docker-<latest_release>",
+ urls = ["https://github.com/bazelbuild/rules_docker/archive/<latest_release>.tar.gz"],
+ )
+
+ load(
+ "@io_bazel_rules_docker//container:container.bzl",
+ container_repositories = "repositories",
+ "container_pull",
+ )
+
+ container_repositories()
+
+ # Pulls the my_image used as base for example above
+ container_pull(
+ name = "my_image",
+ digest = "sha256:<sha256>",
+ registry = "<registry>",
+ repository = "<repo>",
+ )
+
+ # GPG file used by example above
+ http_file(
+ name = "some_gpg",
+ sha256 = "<sha256>",
+ url = "<URL>",
+ )
+
+For values of <latest_release> and other placeholders above, please see
+the WORKSPACE file in this repo.
+
To use the rule run:
bazel run --define=DOCKER_AUTOCONF_OUTPUT=<some_output_dir> //<location_of_rule>:my-autoconfig-rule
@@ -55,7 +113,12 @@
Once rule finishes running the file <some_output_dir>/my-autoconfig-rule.tar
will be created with all toolchain configs generated by
"local_config_cc" and "<some_other_skylark_repo>". If no value for
-DOCKER_AUTOCONF_OUTPUT is passed, the resulting tar file is left in /tmp
+DOCKER_AUTOCONF_OUTPUT is passed, the resulting tar file is left in /tmp.
+
+Known issues:
+
+ - 'name' of rule must conform to docker image naming standards
+ - Rule cannot be placed in the BUILD file at the root of a project
"""
load(
