README.md
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}