Imagine that you need to run a tool as part of your build. For example, you may want to generate or preprocess a source file, or compress a binary. In this tutorial, you are going to create a macro that resizes an image.
Macros are suitable for simple tasks. If you want to do anything more complicated, for example add support for a new programming language, consider creating a rule. Rules give you more control and flexibility.
The easiest way to create a macro that resizes an image is to use a genrule:
genrule(
name = "logo_miniature",
srcs = ["logo.png"],
outs = ["small_logo.png"],
cmd = "convert $< -resize 100x100 $@",
)
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
data = [":logo_miniature"],
)
If you need to resize more images, you may want to reuse the code. To do that,
define a function in a separate .bzl file, and call the file miniature.bzl:
def miniature(name, src, size="100x100", **kwargs):
"""Create a miniature of the src image.
The generated file is prefixed with 'small_'.
"""
native.genrule(
name = name,
srcs = [src],
outs = ["small_" + src],
cmd = "convert $< -resize " + size + " $@",
**kwargs
)
A few remarks:
By convention, macros have a
nameargument, just like rules.To document the behavior of a macro, use docstring like in Python.
To call a
genrule, or any other native rule, usenative..Use
**kwargsto forward the extra arguments to the underlyinggenrule(it works just like in Python). This is useful, so that a user can use standard attributes likevisibility, ortags.
Now, use the macro from the BUILD file:
load("//path/to:miniature.bzl", "miniature")
miniature(
name = "logo_miniature",
src = "image.png",
)
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
data = [":logo_miniature"],
)