Kristina Chodorow | 974b208 | 2015-03-31 14:49:30 +0000 | [diff] [blame] | 1 | --- |
Googler | a0d555f | 2015-04-22 08:32:33 +0000 | [diff] [blame] | 2 | layout: documentation |
David Chen | c4af828 | 2016-01-20 11:06:35 +0000 | [diff] [blame] | 3 | title: Getting Started |
Kristina Chodorow | 974b208 | 2015-03-31 14:49:30 +0000 | [diff] [blame] | 4 | --- |
| 5 | |
Googler | bed6245 | 2015-04-14 18:44:55 +0000 | [diff] [blame] | 6 | # Getting Started with Bazel |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 7 | |
Googler | bed6245 | 2015-04-14 18:44:55 +0000 | [diff] [blame] | 8 | ## Setup |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 9 | |
Kristina Chodorow | 2e68d68 | 2015-08-31 18:27:36 +0000 | [diff] [blame] | 10 | Use the [installation instructions](/docs/install.html) to install a copy of |
| 11 | Bazel on your machine. |
Googler | 08050a3 | 2015-03-31 20:50:16 +0000 | [diff] [blame] | 12 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 13 | ## Using a Workspace |
Googler | 08050a3 | 2015-03-31 20:50:16 +0000 | [diff] [blame] | 14 | |
Kristina Chodorow | 2e68d68 | 2015-08-31 18:27:36 +0000 | [diff] [blame] | 15 | All Bazel builds take place in a [_workspace_](/docs/build-ref.html#workspaces), |
| 16 | a directory on your filesystem that contains source code for the software you |
| 17 | want to build, as well symbolic links to directories that contain the build |
| 18 | outputs (for example, `bazel-bin` and `bazel-out`). The location of the |
| 19 | workspace directory is not significant, but it must contain a file called |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 20 | `WORKSPACE` in the top-level directory; an empty file is a valid workspace. |
| 21 | The `WORKSPACE` file can be used to reference |
Googler | c061bed | 2015-08-30 17:17:57 +0000 | [diff] [blame] | 22 | [external dependencies](/docs/external.html) required to build the outputs. |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 23 | One workspace can be shared among multiple projects if desired. |
Googler | 08050a3 | 2015-03-31 20:50:16 +0000 | [diff] [blame] | 24 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 25 | ```bash |
| 26 | $ touch WORKSPACE |
| 27 | ``` |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 28 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 29 | ## Creating a Build File |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 30 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 31 | To know which target can be build in your project, Bazel inspects `BUILD` files. |
| 32 | They are written in a Bazel's build language which is syntactically similar to |
| 33 | Python. Usually they are just a sequence of declarations of rules. Each rule |
| 34 | specifies its inputs, outputs, and a way to compute the outputs from the inputs. |
| 35 | The rule probably most familiar to people how have used `Makefile`s before (as |
| 36 | it is the only rule available there) is |
| 37 | the [genrule](/docs/be/general.html#genrule), which specifies how the output |
| 38 | can be gerated by invoking a shell command. |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 39 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 40 | ``` |
| 41 | genrule( |
| 42 | name = "hello", |
| 43 | outs = ["hello_world.txt"], |
| 44 | cmd = "echo Hello World > $@", |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 45 | ) |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 46 | ``` |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 47 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 48 | The shell command may contain the familiar |
| 49 | [Make variables](/docs/be/make-variables.html). With the quoted `BUILD` file, |
| 50 | you then ask Bazel to generate the target. |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 51 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 52 | ``` |
| 53 | $ bazel build :hello |
| 54 | . |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 55 | INFO: Found 1 target... |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 56 | Target //:hello up-to-date: |
| 57 | bazel-genfiles/hello_world.txt |
| 58 | INFO: Elapsed time: 2.255s, Critical Path: 0.07s |
| 59 | ``` |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 60 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 61 | We 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 |
| 65 | the preferred way.) |
| 66 | Secondly, Bazel puts the generated |
| 67 | files to a separate directory (the `bazel-genfiles` directory actually |
| 68 | is a symbolic link) to not pollute your source tree. |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 69 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 70 | Rules may use the output of other rules as input, as in the following |
| 71 | example. Again, the generated sources are referred to by their label. |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 72 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 73 | ``` |
| 74 | genrule( |
| 75 | name = "hello", |
| 76 | outs = ["hello_world.txt"], |
| 77 | cmd = "echo Hello World > $@", |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 78 | ) |
| 79 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 80 | genrule( |
| 81 | name = "double", |
| 82 | srcs = [":hello"], |
| 83 | outs = ["double_hello.txt"], |
| 84 | cmd = "cat $< $< > $@", |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 85 | ) |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 86 | ``` |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 87 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 88 | Finally note that, while the [genrule](/docs/be/general.html#genrule) might |
| 89 | seem familiar, it usually is _not_ the best rule to use. It is preferrable |
| 90 | to use one of the specialized [rules](/docs/be/overview.html#rules) for |
| 91 | various languages. |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 92 | |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 93 | # Next Steps |
Han-Wen Nienhuys | d08b27f | 2015-02-25 16:45:20 +0100 | [diff] [blame] | 94 | |
Klaus Aehlig | 3b0ca6a | 2016-06-27 13:57:59 +0000 | [diff] [blame] | 95 | Next, check out the tutorial on building [java](/docs/tutorial/java.html) |
Klaus Aehlig | dd548b0 | 2016-06-24 18:01:37 +0000 | [diff] [blame] | 96 | or [C++](/docs/tutorial/cpp.html) programs. |