blob: d76b4ab9c7f464cbbfe412f91570b121c1cd199b [file] [log] [blame] [view]
Kristina Chodorow974b2082015-03-31 14:49:30 +00001---
Googlera0d555f2015-04-22 08:32:33 +00002layout: documentation
David Chenc4af8282016-01-20 11:06:35 +00003title: Getting Started
Kristina Chodorow974b2082015-03-31 14:49:30 +00004---
5
Googlerbed62452015-04-14 18:44:55 +00006# Getting Started with Bazel
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +01007
Googlerbed62452015-04-14 18:44:55 +00008## Setup
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +01009
Kristina Chodorow2e68d682015-08-31 18:27:36 +000010Use the [installation instructions](/docs/install.html) to install a copy of
11Bazel on your machine.
Googler08050a32015-03-31 20:50:16 +000012
Klaus Aehligdd548b02016-06-24 18:01:37 +000013## Using a Workspace
Googler08050a32015-03-31 20:50:16 +000014
Kristina Chodorow2e68d682015-08-31 18:27:36 +000015All Bazel builds take place in a [_workspace_](/docs/build-ref.html#workspaces),
16a directory on your filesystem that contains source code for the software you
17want to build, as well symbolic links to directories that contain the build
18outputs (for example, `bazel-bin` and `bazel-out`). The location of the
19workspace directory is not significant, but it must contain a file called
Klaus Aehligdd548b02016-06-24 18:01:37 +000020`WORKSPACE` in the top-level directory; an empty file is a valid workspace.
21The `WORKSPACE` file can be used to reference
Googlerc061bed2015-08-30 17:17:57 +000022[external dependencies](/docs/external.html) required to build the outputs.
Klaus Aehligdd548b02016-06-24 18:01:37 +000023One workspace can be shared among multiple projects if desired.
Googler08050a32015-03-31 20:50:16 +000024
Klaus Aehligdd548b02016-06-24 18:01:37 +000025```bash
26$ touch WORKSPACE
27```
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010028
Klaus Aehligdd548b02016-06-24 18:01:37 +000029## Creating a Build File
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010030
Klaus Aehligdd548b02016-06-24 18:01:37 +000031To know which target can be build in your project, Bazel inspects `BUILD` files.
32They are written in a Bazel's build language which is syntactically similar to
33Python. Usually they are just a sequence of declarations of rules. Each rule
34specifies its inputs, outputs, and a way to compute the outputs from the inputs.
35The rule probably most familiar to people how have used `Makefile`s before (as
36it is the only rule available there) is
37the [genrule](/docs/be/general.html#genrule), which specifies how the output
38can be gerated by invoking a shell command.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010039
Klaus Aehligdd548b02016-06-24 18:01:37 +000040```
41genrule(
42 name = "hello",
43 outs = ["hello_world.txt"],
44 cmd = "echo Hello World > $@",
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010045)
Klaus Aehligdd548b02016-06-24 18:01:37 +000046```
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010047
Klaus Aehligdd548b02016-06-24 18:01:37 +000048The shell command may contain the familiar
49[Make variables](/docs/be/make-variables.html). With the quoted `BUILD` file,
50you then ask Bazel to generate the target.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010051
Klaus Aehligdd548b02016-06-24 18:01:37 +000052```
53$ bazel build :hello
54.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010055INFO: Found 1 target...
Klaus Aehligdd548b02016-06-24 18:01:37 +000056Target //:hello up-to-date:
57 bazel-genfiles/hello_world.txt
58INFO: Elapsed time: 2.255s, Critical Path: 0.07s
59```
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010060
Klaus Aehligdd548b02016-06-24 18:01:37 +000061We note two things. First, targets are normally referred to by their
62[label](/docs/build-ref.html#labels), which is specified by the
63[name](/docs/be/general.html#genrule.name) attribute of the rule.
64(Referencing them by the output file name is also possible, but not
65the preferred way.)
66Secondly, Bazel puts the generated
67files to a separate directory (the `bazel-genfiles` directory actually
68is a symbolic link) to not pollute your source tree.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010069
Klaus Aehligdd548b02016-06-24 18:01:37 +000070Rules may use the output of other rules as input, as in the following
71example. Again, the generated sources are referred to by their label.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010072
Klaus Aehligdd548b02016-06-24 18:01:37 +000073```
74genrule(
75 name = "hello",
76 outs = ["hello_world.txt"],
77 cmd = "echo Hello World > $@",
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010078)
79
Klaus Aehligdd548b02016-06-24 18:01:37 +000080genrule(
81 name = "double",
82 srcs = [":hello"],
83 outs = ["double_hello.txt"],
84 cmd = "cat $< $< > $@",
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010085)
Klaus Aehligdd548b02016-06-24 18:01:37 +000086```
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010087
Klaus Aehligdd548b02016-06-24 18:01:37 +000088Finally note that, while the [genrule](/docs/be/general.html#genrule) might
89seem familiar, it usually is _not_ the best rule to use. It is preferrable
90to use one of the specialized [rules](/docs/be/overview.html#rules) for
91various languages.
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010092
Klaus Aehligdd548b02016-06-24 18:01:37 +000093# Next Steps
Han-Wen Nienhuysd08b27f2015-02-25 16:45:20 +010094
Klaus Aehlig3b0ca6a2016-06-27 13:57:59 +000095Next, check out the tutorial on building [java](/docs/tutorial/java.html)
Klaus Aehligdd548b02016-06-24 18:01:37 +000096or [C++](/docs/tutorial/cpp.html) programs.