Buck comes with a number of built-in build rules, as there are many common procedures when building software. For example, compiling Java code against the Android SDK is a common operation, so the build rule
android_library exists to facilitate that. Similarly, the primary objective of most Android developers is to create an APK, so the build rule
android_binary can be used to do that.
Build rules are defined using built-in Python functions in a build file. (Both the Python function to define the rule and the corresponding Java object that is ultimately created to carry out the procedure are commonly referred to as "the build rule," even though they are technically different things.) Every build rule takes at least the following three arguments:
nameThe name of the build rule, which must be unique within a build file.
depsThe build rule's dependencies, expressed as a list of build targets.
visibilityThe set of build rules that are allowed to claim this rule as a dependency, expressed as a list of build target patterns.
In Buck, every build rule can produce zero or one output files. These output files can be used by other rules that declare the rule responsible for the output file as a dependency. For example, the output of an
android_library is a JAR file, so an
android_binary that declares the
android_library as a dependency can include the
.class files from the
android_library's JAR file in its resulting APK. Or when one
android_library depends on another, the JAR of dependent rule will be included on the classpath when the rule that depends on it compiles its Java code. Check the documentation for each build rule to see how it uses its
deps. Note that no matter how a rule uses its
deps, every rule in a rule's
deps is guaranteed to be built before the rule attempts to build itself.
Build rules and their dependencies define a directed graph. Buck requires that this graph be acyclic. This helps Buck build efficiently, as it makes it easier to build independent subgraphs in parallel.
Although Buck tries to provide a rich set of built-in build rules for developers, it is not able to address all possible needs. As an "escape hatch," Buck also provides a vanilla build rule called a
genrule, which you can use to build an arbitrary rule using a Bash script.
Finally, note that build files are evaluated as Python files. This means that you can define your own functions within build files that generate build rules. This should not be something that you need to do often, but taking advantage of this may help you add something to Buck's build process without editing its source code. For more details on this topic, see the article on macros.