From 7a0013b8e429c1121e063b264e80f64bbb4f0b19 Mon Sep 17 00:00:00 2001 From: Evgeny Khabarov Date: Sat, 9 Dec 2023 15:22:12 -0500 Subject: [PATCH] Add docs. --- BUILD.bazel | 16 ++++++ README.md | 4 +- WORKSPACE | 15 ++++- docs/BUILD.bazel | 15 +++++ docs/repositories.md | 99 +++++++++++++++++++++++++++++++++ docs/ytt.md | 24 ++++++++ ytt/BUILD.bazel | 18 ++++++ ytt/private/BUILD.bazel | 21 +++++++ ytt/private/toolchains_repo.bzl | 2 +- ytt/repositories.bzl | 32 ++++++++--- 10 files changed, 232 insertions(+), 14 deletions(-) create mode 100644 docs/BUILD.bazel create mode 100644 docs/repositories.md create mode 100644 docs/ytt.md diff --git a/BUILD.bazel b/BUILD.bazel index e69de29..a7445f0 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -0,0 +1,16 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +exports_files( + ["defs.bzl"], + visibility = ["//docs:__pkg__"], +) + +bzl_library( + name = "defs", + srcs = ["defs.bzl"], + visibility = ["//visibility:public"], + deps = [ + "//ytt/private:ytt", + "//ytt:repositories", + ], +) diff --git a/README.md b/README.md index 2dc969c..bcca4ab 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,12 @@ http_archive( load("@rules_ytt//ytt:repositories.bzl", "rules_ytt_dependencies", - "ytt_register_toolchains", + "rules_ytt_register_toolchains", ) rules_ytt_dependencies() -ytt_register_toolchains() +rules_ytt_register_toolchains() ``` ## Usage diff --git a/WORKSPACE b/WORKSPACE index 7e38145..6175f2f 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -3,11 +3,22 @@ workspace(name = "rules_ytt") load("//ytt:repositories.bzl", "rules_ytt_dependencies", "rules_ytt_internal_dependencies", - "ytt_register_toolchains", + "rules_ytt_register_toolchains", ) rules_ytt_dependencies() rules_ytt_internal_dependencies() -ytt_register_toolchains() +rules_ytt_register_toolchains() + +load("@aspect_bazel_lib//lib:repositories.bzl", "aspect_bazel_lib_dependencies", "aspect_bazel_lib_register_toolchains") + +aspect_bazel_lib_dependencies() + +aspect_bazel_lib_register_toolchains() + +load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") + +bazel_skylib_workspace() + diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel new file mode 100644 index 0000000..0d5c622 --- /dev/null +++ b/docs/BUILD.bazel @@ -0,0 +1,15 @@ +# 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 = "ytt", + bzl_library_target = "//:defs", +) + +stardoc_with_diff_test( + name = "repositories", + bzl_library_target = "//ytt:repositories", +) + +update_docs(name = "update") diff --git a/docs/repositories.md b/docs/repositories.md new file mode 100644 index 0000000..efcd7e4 --- /dev/null +++ b/docs/repositories.md @@ -0,0 +1,99 @@ + + +Declare runtime dependencies + +These are needed for local dev, and users must install them as well. +See https://docs.bazel.build/versions/main/skylark/deploying.html#dependencies + + + + +## ytt_repositories + +
+ytt_repositories(name, platform, repo_mapping, ytt_version)
+
+ +Fetch external tools needed for ytt toolchain + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| platform | - | String | required | | +| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). | Dictionary: String -> String | required | | +| ytt_version | - | String | required | | + + + + +## http_archive + +
+http_archive(name, kwargs)
+
+ + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name |

-

| none | +| kwargs |

-

| none | + + + + +## rules_ytt_dependencies + +
+rules_ytt_dependencies()
+
+ +rules_ytt runtime dependencies. + + + + + +## rules_ytt_internal_dependencies + +
+rules_ytt_internal_dependencies()
+
+ +rules_ytt dependencies for internal use only. + + + + + +## rules_ytt_register_toolchains + +
+rules_ytt_register_toolchains(name, version, kwargs)
+
+ +Convenience macro for users which does typical setup. + +- create a repository for each built-in platform like `ytt_linux_amd64` - + this repository is lazily fetched when node is needed for that platform. +- create a repository exposing toolchains for each platform like `ytt_platforms` +- register a toolchain pointing at each platform +Users can avoid this macro and do these steps themselves, if they want more control. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | base name for all created repos, like "ytt" | "ytt" | +| version | Ytt tool version. Supported versions are listed in ytt/private/versions.bzl. | "0.46.2" | +| kwargs | passed to each node_repositories call | none | + + diff --git a/docs/ytt.md b/docs/ytt.md new file mode 100644 index 0000000..26d0137 --- /dev/null +++ b/docs/ytt.md @@ -0,0 +1,24 @@ + + + + + + +## ytt + +
+ytt(name, image, srcs)
+
+ + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| image | (DEPRECATED) Target that generates a Docker image. Used for extracting image digest. | Label | optional | None | +| srcs | List of files that will be passed to ytt with -f param. | List of labels | required | | + + diff --git a/ytt/BUILD.bazel b/ytt/BUILD.bazel index e794c12..349ec71 100644 --- a/ytt/BUILD.bazel +++ b/ytt/BUILD.bazel @@ -1,4 +1,10 @@ load("//ytt/private:resolved_toolchains.bzl", "resolved_toolchain") +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +exports_files( + ["repositories.bzl"], + visibility = ["//docs:__pkg__"], +) # This is the target rule authors should put in their "toolchains" # attribute in order to get a runtime for the correct platform. @@ -15,3 +21,15 @@ resolved_toolchain( tags = ["manual"], visibility = ["//visibility:public"], ) + +bzl_library( + name = "repositories", + srcs = ["repositories.bzl"], + visibility = ["//:__subpackages__"], + deps = [ + "//ytt/private:toolchains_repo", + "//ytt/private:versions", + "@bazel_tools//tools/build_defs/repo:http.bzl", + "@bazel_tools//tools/build_defs/repo:utils.bzl", + ], +) diff --git a/ytt/private/BUILD.bazel b/ytt/private/BUILD.bazel index e69de29..600ab84 100644 --- a/ytt/private/BUILD.bazel +++ b/ytt/private/BUILD.bazel @@ -0,0 +1,21 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzl_library( + name = "ytt", + srcs = ["ytt.bzl"], + visibility = [ + "//:__subpackages__", + ], +) + +bzl_library( + name = "toolchains_repo", + srcs = ["toolchains_repo.bzl"], + visibility = ["//ytt:__subpackages__"], +) + +bzl_library( + name = "versions", + srcs = ["versions.bzl"], + visibility = ["//ytt:__subpackages__"], +) diff --git a/ytt/private/toolchains_repo.bzl b/ytt/private/toolchains_repo.bzl index d43503e..0d779c4 100644 --- a/ytt/private/toolchains_repo.bzl +++ b/ytt/private/toolchains_repo.bzl @@ -50,7 +50,7 @@ def _toolchains_repo_impl(repository_ctx): build_content = """# Generated by toolchains_repo.bzl # # These can be registered in the workspace file or passed to --extra_toolchains flag. -# By default all these toolchains are registered by the ytt_register_toolchains macro +# By default all these toolchains are registered by the rules_ytt_register_toolchains macro # so you don't normally need to interact with these targets. """ diff --git a/ytt/repositories.bzl b/ytt/repositories.bzl index 2e04d89..4fde954 100644 --- a/ytt/repositories.bzl +++ b/ytt/repositories.bzl @@ -20,10 +20,25 @@ def http_archive(name, **kwargs): # and released only in semver majors. # This is all fixed by bzlmod, so we just tolerate it for now. def rules_ytt_dependencies(): + "rules_ytt runtime dependencies." pass def rules_ytt_internal_dependencies(): - pass + "rules_ytt dependencies for internal use only." + http_archive( + name = "io_bazel_stardoc", + sha256 = "ec57139e466faae563f2fc39609da4948a479bb51b6d67aedd7d9b1b8059c433", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.4/stardoc-0.5.4.tar.gz", + "https://github.com/bazelbuild/stardoc/releases/download/0.5.4/stardoc-0.5.4.tar.gz", + ], + ) + http_archive( + name = "aspect_bazel_lib", + sha256 = "c858cc637db5370f6fd752478d1153955b4b4cbec7ffe95eb4a47a48499a79c3", + strip_prefix = "bazel-lib-2.0.3", + url = "https://github.com/aspect-build/bazel-lib/releases/download/v2.0.3/bazel-lib-v2.0.3.tar.gz", + ) ######## # Remaining content of the file is only used to support toolchains. @@ -71,18 +86,18 @@ ytt_repositories = repository_rule( ) # Wrapper macro around everything above, this is the primary API -def ytt_register_toolchains(name = "ytt", version = "0.46.2", register = True, **kwargs): +def rules_ytt_register_toolchains(name = "ytt", version = "0.46.2", **kwargs): """Convenience macro for users which does typical setup. - - create a repository for each built-in platform like "ytt_linux_amd64" - + - create a repository for each built-in platform like `ytt_linux_amd64` - this repository is lazily fetched when node is needed for that platform. - - create a repository exposing toolchains for each platform like "ytt_platforms" + - create a repository exposing toolchains for each platform like `ytt_platforms` - register a toolchain pointing at each platform Users can avoid this macro and do these steps themselves, if they want more control. + Args: - name: base name for all created repos, like "ytt1_14" - register: whether to call through to native.register_toolchains. - Should be True for WORKSPACE users, but false when used under bzlmod extension + name: base name for all created repos, like "ytt" + version: Ytt tool version. Supported versions are listed in `ytt/private/versions.bzl`. **kwargs: passed to each node_repositories call """ for platform in PLATFORMS.keys(): @@ -92,8 +107,7 @@ def ytt_register_toolchains(name = "ytt", version = "0.46.2", register = True, * ytt_version = version, **kwargs ) - if register: - native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform)) + native.register_toolchains("@%s_toolchains//:%s_toolchain" % (name, platform)) toolchains_repo( name = name + "_toolchains",