1# Skylib 2 3[](https://buildkite.com/bazel/bazel-skylib) 4 5Skylib is a standard library that provides functions useful for manipulating 6collections, file paths, and other features that are useful when writing custom 7build rules in Bazel. 8 9> This library is currently under early development. Be aware that the APIs 10> in these modules may change during this time. 11 12Each of the `.bzl` files in the `lib` directory defines a "module"—a 13`struct` that contains a set of related functions and/or other symbols that can 14be loaded as a single unit, for convenience. 15 16Skylib also provides build rules under the `rules` directory. 17 18## Getting Started 19 20### `WORKSPACE` file 21 22See the **WORKSPACE setup** section [for the current release](https://github.com/bazelbuild/bazel-skylib/releases). 23 24If you want to use `lib/unittest.bzl` from Skylib versions released in or after 25December 2018, then you also should add to the `WORKSPACE` file: 26 27```python 28load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") 29 30bazel_skylib_workspace() 31``` 32 33### `BUILD` and `*.bzl` files 34 35Then, in the `BUILD` and/or `*.bzl` files in your own workspace, you can load 36the modules (listed [below](#list-of-modules)) and access the symbols by 37dotting into those structs: 38 39```python 40load("@bazel_skylib//lib:paths.bzl", "paths") 41load("@bazel_skylib//lib:shell.bzl", "shell") 42 43p = paths.basename("foo.bar") 44s = shell.quote(p) 45``` 46 47## List of modules (in lib/) 48 49* [collections](docs/collections_doc.md) 50* [dicts](docs/dicts_doc.md) 51* [partial](docs/partial_doc.md) 52* [paths](docs/paths_doc.md) 53* [selects](docs/selects_doc.md) 54* [sets](lib/sets.bzl) - _deprecated_, use `new_sets` 55* [new_sets](docs/new_sets_doc.md) 56* [shell](docs/shell_doc.md) 57* [structs](docs/structs_doc.md) 58* [types](docs/types_doc.md) 59* [unittest](docs/unittest_doc.md) 60* [versions](docs/versions_doc.md) 61 62## List of rules (in rules/) 63 64* [analysis_test](docs/analysis_test_doc.md) 65* [build_test](docs/build_test_doc.md) 66 67## Writing a new module 68 69Steps to add a module to Skylib: 70 711. Create a new `.bzl` file in the `lib` directory. 72 731. Write the functions or other symbols (such as constants) in that file, 74 defining them privately (prefixed by an underscore). 75 761. Create the exported module struct, mapping the public names of the symbols 77 to their implementations. For example, if your module was named `things` and 78 had a function named `manipulate`, your `things.bzl` file would look like 79 this: 80 81 ```python 82 def _manipulate(): 83 ... 84 85 things = struct( 86 manipulate=_manipulate, 87 ) 88 ``` 89 901. Add unit tests for your module in the `tests` directory. 91 92## `bzl_library` 93 94The `bzl_library.bzl` rule can be used to aggregate a set of 95Starlark files and its dependencies for use in test targets and 96documentation generation. 97 98## Troubleshooting 99 100If you try to use `unittest` and you get the following error: 101 102``` 103ERROR: While resolving toolchains for target //foo:bar: no matching toolchains found for types @bazel_skylib//toolchains:toolchain_type 104ERROR: Analysis of target '//foo:bar' failed; build aborted: no matching toolchains found for types @bazel_skylib//toolchains:toolchain_type 105``` 106 107then you probably forgot to load and call `bazel_skylib_workspace()` in your 108`WORKSPACE` file. 109
){kind=link}