{"id":13450713,"url":"https://github.com/bazelbuild/bazel-skylib","last_synced_at":"2025-03-01T11:44:10.479Z","repository":{"id":25764114,"uuid":"106432039","full_name":"bazelbuild/bazel-skylib","owner":"bazelbuild","description":"Common useful functions and rules for Bazel","archived":false,"fork":false,"pushed_at":"2025-02-24T11:29:32.000Z","size":685,"stargazers_count":399,"open_issues_count":108,"forks_count":182,"subscribers_count":32,"default_branch":"main","last_synced_at":"2025-02-24T12:34:18.191Z","etag":null,"topics":["bazel","bazel-rules","starlark"],"latest_commit_sha":null,"homepage":"https://bazel.build/","language":"Starlark","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bazelbuild.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-10T14:57:57.000Z","updated_at":"2025-02-24T11:29:36.000Z","dependencies_parsed_at":"2024-03-20T22:47:19.818Z","dependency_job_id":"a8dfdfff-48df-411e-a1e2-f0b90ae1fa3e","html_url":"https://github.com/bazelbuild/bazel-skylib","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazelbuild%2Fbazel-skylib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazelbuild%2Fbazel-skylib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazelbuild%2Fbazel-skylib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazelbuild%2Fbazel-skylib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bazelbuild","download_url":"https://codeload.github.com/bazelbuild/bazel-skylib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241361398,"owners_count":19950379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bazel","bazel-rules","starlark"],"created_at":"2024-07-31T07:00:37.563Z","updated_at":"2025-03-01T11:44:10.452Z","avatar_url":"https://github.com/bazelbuild.png","language":"Starlark","readme":"# Skylib\n\n[![Build status](https://badge.buildkite.com/921dc61e2d3a350ec40efb291914360c0bfa9b6196fa357420.svg?branch=main)](https://buildkite.com/bazel/bazel-skylib)\n\nSkylib is a library of Starlark functions for manipulating collections, file paths,\nand various other data types in the domain of Bazel build rules.\n\nEach of the `.bzl` files in the `lib` directory defines a \"module\"\u0026mdash;a\n`struct` that contains a set of related functions and/or other symbols that can\nbe loaded as a single unit, for convenience.\n\nSkylib also provides build rules under the `rules` directory.\n\n## Getting Started\n\n### `WORKSPACE` file\n\nSee the **WORKSPACE setup** section [for the current release](https://github.com/bazelbuild/bazel-skylib/releases).\n\nIf you want to use `lib/unittest.bzl` from Skylib versions released in or after\nDecember 2018, then you also should add to the `WORKSPACE` file:\n\n```python\nload(\"@bazel_skylib//:workspace.bzl\", \"bazel_skylib_workspace\")\n\nbazel_skylib_workspace()\n```\n\n### `BUILD` and `*.bzl` files\n\nThen, in the `BUILD` and/or `*.bzl` files in your own workspace, you can load\nthe modules (listed [below](#list-of-modules)) and access the symbols by\ndotting into those structs:\n\n```python\nload(\"@bazel_skylib//lib:paths.bzl\", \"paths\")\nload(\"@bazel_skylib//lib:shell.bzl\", \"shell\")\n\np = paths.basename(\"foo.bar\")\ns = shell.quote(p)\n```\n\n## List of modules (in lib/)\n\n* [collections](docs/collections_doc.md)\n* [dicts](docs/dicts_doc.md)\n* [partial](docs/partial_doc.md)\n* [paths](docs/paths_doc.md)\n* [selects](docs/selects_doc.md)\n* [sets](docs/new_sets_doc.md)\n* [modules](docs/modules_doc.md)\n* [shell](docs/shell_doc.md)\n* [structs](docs/structs_doc.md)\n* [subpackages](docs/subpackages_doc.md)\n* [types](docs/types_doc.md)\n* [unittest](docs/unittest_doc.md)\n* [versions](docs/versions_doc.md)\n\n## List of rules (in rules/)\n\n* [analysis_test](docs/analysis_test_doc.md)\n* [build_test](docs/build_test_doc.md)\n* [common_settings](docs/common_settings_doc.md)\n* directories\n    * [directory](docs/directory_doc.md)\n    * [directory_glob](docs/directory_glob_doc.md)\n    * [subdirectory](docs/directory_subdirectory_doc.md)\n* [copy_directory](docs/copy_directory_doc.md)\n* [copy_file](docs/copy_file_doc.md)\n* [diff_test](docs/diff_test_doc.md)\n* [expand_template](docs/expand_template_doc.md)\n* [native_binary and native_test](docs/native_binary_doc.md)\n* [run_binary](docs/run_binary_doc.md)\n* [select_file](docs/select_file_doc.md)\n* [write_file](docs/write_file_doc.md)\n\n## Writing a new module\n\nThe criteria for adding a new function or module to this repository are:\n\n1. Is it widely needed? The new code must solve a problem that occurs often during the development of Bazel build rules. It is not sufficient that the new code is merely useful. Candidate code should generally have been proven to be necessary across several projects, either because it provides indispensable common functionality, or because it requires a single standardized implementation.\n\n1. Is its interface simpler than its implementation? A good abstraction provides a simple interface to a complex implementation, relieving the user from the burden of understanding. By contrast, a shallow abstraction provides little that the user could not easily have written out for themselves. If a function's doc comment is longer than its body, it's a good sign that the abstraction is too shallow.\n\n1. Is its interface unimpeachable? Given the problem it tries to solve, does it have sufficient parameters or generality to address all reasonable cases, or does it make arbitrary policy choices that limit its usefulness? If the function is not general, it likely does not belong here. Conversely, if it is general thanks only to a bewildering number of parameters, it also does not belong here.\n\n1. Is it efficient? Does it solve the problem using the asymptotically optimal algorithm, without using excessive looping, allocation, or other high constant factors? Starlark is an interpreted language with relatively expensive basic operations, and an approach that might make sense in C++ may not in Starlark.\n\nIf your new module meets all these criteria, then you should consider sending us a pull request. It is always better to discuss your plans before executing them.\n\nMany of the declarations already in this repository do not meet this bar.\n\n\nSteps to add a module to Skylib:\n\n1. Create a new `.bzl` file in the `lib` directory.\n\n1. Write the functions or other symbols (such as constants) in that file,\n   defining them privately (prefixed by an underscore).\n\n1. Create the exported module struct, mapping the public names of the symbols\n   to their implementations. For example, if your module was named `things` and\n   had a function named `manipulate`, your `things.bzl` file would look like\n   this:\n\n   ```python\n   def _manipulate():\n     ...\n\n   things = struct(\n       manipulate=_manipulate,\n   )\n   ```\n\n1. Add unit tests for your module in the `tests` directory.\n\n## `bzl_library`\n\nThe `bzl_library.bzl` rule can be used to aggregate a set of\nStarlark files and its dependencies for use in test targets and\ndocumentation generation.\n\n## Troubleshooting\n\nIf you try to use `unittest` and you get the following error:\n\n```\nERROR: While resolving toolchains for target //foo:bar: no matching toolchains found for types @bazel_skylib//toolchains:toolchain_type\nERROR: Analysis of target '//foo:bar' failed; build aborted: no matching toolchains found for types @bazel_skylib//toolchains:toolchain_type\n```\n\nthen you probably forgot to load and call `bazel_skylib_workspace()` in your\n`WORKSPACE` file.\n\n### Maintainer's guide\n\nSee the [maintaner's guide](docs/maintainers_guide.md) for instructions for\ncutting a new release.\n\n## Gazelle Plugin\n\n`bazel_skylib` ships with a [gazelle](https://github.com/bazelbuild/bazel-gazelle)\nplugin to generate `bzl_library` entries in build files. To use this, in your\n`WORKSPACE`:\n\n```starlark\nload(\"@bazel_skylib_gazelle_plugin//:workspace.bzl\", \"bazel_skylib_gazelle_plugin_workspace\")\n\nbazel_skylib_gazelle_plugin_workspace()\n\nload(\"@bazel_skylib_gazelle_plugin//:setup.bzl\", \"bazel_skylib_gazelle_plugin_setup\")\n\nbazel_skylib_gazelle_plugin_setup()\n```\n\nYou may then include the plugin using code similar to this in your `BUILD.bazel`\nfile:\n\n```starlark\nload(\"@bazel_gazelle//:def.bzl\", \"DEFAULT_LANGUAGES\", \"gazelle\", \"gazelle_binary\")\n\ngazelle(\n    name = \"gazelle\",\n    gazelle = \":gazelle_bin\",\n)\n\ngazelle_binary(\n    name = \"gazelle_bin\",\n    languages = DEFAULT_LANGUAGES + [\n        \"@bazel_skylib_gazelle_plugin//bzl\",\n    ],\n)\n```\n","funding_links":[],"categories":["Starlark","Tooling","Python"],"sub_categories":["Starlark"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazelbuild%2Fbazel-skylib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbazelbuild%2Fbazel-skylib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazelbuild%2Fbazel-skylib/lists"}