Yun Peng | 1f63afa | 2016-06-24 18:01:03 +0000 | [diff] [blame] | 1 | --- |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 2 | layout: documentation |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 3 | title: Build Tutorial - Java |
Yun Peng | 1f63afa | 2016-06-24 18:01:03 +0000 | [diff] [blame] | 4 | --- |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 5 | |
laurentlb | 27bb948 | 2018-11-12 12:50:34 -0800 | [diff] [blame] | 6 | # Introduction to Bazel: Building a Java Project |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 7 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 8 | In this tutorial, you'll learn the basics of building Java applications with |
| 9 | Bazel. You will set up your workspace and build a simple Java project that |
| 10 | illustrates key Bazel concepts, such as targets and `BUILD` files. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 11 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 12 | Estimated completion time: 30 minutes. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 13 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 14 | ## What you'll learn |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 15 | |
| 16 | In this tutorial you'll learn how to: |
| 17 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 18 | * Build a target |
| 19 | * Visualize the project's dependencies |
| 20 | * Split the project into multiple targets and packages |
| 21 | * Control target visibility across packages |
| 22 | * Reference targets through labels |
| 23 | * Deploy a target |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 24 | |
Googler | 1c6a982 | 2017-08-04 19:31:14 +0200 | [diff] [blame] | 25 | ## Contents |
laurentlb | 27bb948 | 2018-11-12 12:50:34 -0800 | [diff] [blame] | 26 | {:.no_toc} |
Googler | 1c6a982 | 2017-08-04 19:31:14 +0200 | [diff] [blame] | 27 | |
laurentlb | 27bb948 | 2018-11-12 12:50:34 -0800 | [diff] [blame] | 28 | * ToC |
| 29 | {:toc} |
| 30 | |
Googler | 1c6a982 | 2017-08-04 19:31:14 +0200 | [diff] [blame] | 31 | |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 32 | ## Before you begin |
| 33 | |
Googler | 1c6a982 | 2017-08-04 19:31:14 +0200 | [diff] [blame] | 34 | ### Install Bazel |
| 35 | |
dzc | 205125b | 2017-06-26 11:01:47 +0200 | [diff] [blame] | 36 | To prepare for the tutorial, first [Install Bazel](../install.md) if |
Googler | 1c6a982 | 2017-08-04 19:31:14 +0200 | [diff] [blame] | 37 | you don't have it installed already. |
| 38 | |
Laszlo Csomor | 7574865 | 2018-07-26 07:38:14 -0700 | [diff] [blame] | 39 | ### Install the JDK |
| 40 | |
| 41 | 1. Install Java 8 JDK. |
| 42 | |
| 43 | 2. Set the JAVA\_HOME environment variable to point to the JDK. |
| 44 | * On Linux/macOS: |
| 45 | |
| 46 | export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))" |
| 47 | * On Windows: |
| 48 | 1. Open Control Panel. |
| 49 | 2. Go to "System and Security" > "System" > "Advanced System Settings" > "Advanced" tab > "Environment Variables..." . |
| 50 | 3. Under the "User variables" list (the one on the top), click "New...". |
| 51 | 4. In the "Variable name" field, enter `JAVA_HOME`. |
| 52 | 5. Click "Browse Directory...". |
Salty Egg | 5f17a76 | 2018-10-11 07:21:51 -0700 | [diff] [blame] | 53 | 6. Navigate to the JDK directory (for example `C:\Program Files\Java\jdk1.8.0_152`). |
Laszlo Csomor | 7574865 | 2018-07-26 07:38:14 -0700 | [diff] [blame] | 54 | 7. Click "OK" on all dialog windows. |
| 55 | |
Googler | 1c6a982 | 2017-08-04 19:31:14 +0200 | [diff] [blame] | 56 | ### Get the sample project |
| 57 | |
| 58 | Retrieve the sample project from Bazel's GitHub repository: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 59 | |
dzc | 51dcd28 | 2017-06-14 22:52:27 +0200 | [diff] [blame] | 60 | ```sh |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 61 | git clone https://github.com/bazelbuild/examples/ |
| 62 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 63 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 64 | The sample project for this tutorial is in the `examples/java-tutorial` |
| 65 | directory and is structured as follows: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 66 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 67 | ``` |
| 68 | java-tutorial |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 69 | ├── BUILD |
| 70 | ├── src |
| 71 | │ └── main |
| 72 | │ └── java |
| 73 | │ └── com |
| 74 | │ └── example |
| 75 | │ ├── cmdline |
| 76 | │ │ ├── BUILD |
| 77 | │ │ └── Runner.java |
| 78 | │ ├── Greeting.java |
| 79 | │ └── ProjectRunner.java |
| 80 | └── WORKSPACE |
| 81 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 82 | |
| 83 | ## Build with Bazel |
| 84 | |
| 85 | ### Set up the workspace |
| 86 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 87 | Before you can build a project, you need to set up its workspace. A workspace is |
| 88 | a directory that holds your project's source files and Bazel's build outputs. It |
| 89 | also contains files that Bazel recognizes as special: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 90 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 91 | * The `WORKSPACE` file, which identifies the directory and its contents as a |
| 92 | Bazel workspace and lives at the root of the project's directory structure, |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 93 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 94 | * One or more `BUILD` files, which tell Bazel how to build different parts of |
| 95 | the project. (A directory within the workspace that contains a `BUILD` file |
| 96 | is a *package*. You will learn about packages later in this tutorial.) |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 97 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 98 | To designate a directory as a Bazel workspace, create an empty file named |
| 99 | `WORKSPACE` in that directory. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 100 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 101 | When Bazel builds the project, all inputs and dependencies must be in the same |
| 102 | workspace. Files residing in different workspaces are independent of one |
| 103 | another unless linked, which is beyond the scope of this tutorial. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 104 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 105 | ### Understand the BUILD file |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 106 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 107 | A `BUILD` file contains several different types of instructions for Bazel. |
| 108 | The most important type is the *build rule*, which tells Bazel how to build the |
| 109 | desired outputs, such as executable binaries or libraries. Each instance |
| 110 | of a build rule in the `BUILD` file is called a *target* and points to a |
| 111 | specific set of source files and dependencies. A target can also point to other |
| 112 | targets. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 113 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 114 | Take a look at the `java-tutorial/BUILD` file: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 115 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 116 | ``` |
| 117 | java_binary( |
Googler | 006659e | 2017-07-20 19:48:05 +0200 | [diff] [blame] | 118 | name = "ProjectRunner", |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 119 | srcs = glob(["src/main/java/com/example/*.java"]), |
| 120 | ) |
| 121 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 122 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 123 | In our example, the `ProjectRunner` target instantiates Bazel's built-in |
dzc | 205125b | 2017-06-26 11:01:47 +0200 | [diff] [blame] | 124 | [`java_binary` rule](../be/java.html#java_binary). The rule tells Bazel to |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 125 | build a `.jar` file and a wrapper shell script (both named after the target). |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 126 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 127 | The attributes in the target explicitly state its dependencies and options. |
| 128 | While the `name` attribute is mandatory, many are optional. For example, in the |
| 129 | `ProjectRunner` rule target, `name` is the name of the target, `srcs` specifies |
| 130 | the source files that Bazel uses to build the target, and `main_class` specifies |
| 131 | the class that contains the main method. (You may have noticed that our example |
dzc | 205125b | 2017-06-26 11:01:47 +0200 | [diff] [blame] | 132 | uses [glob](../be/functions.html#glob) to pass a set of source files to Bazel |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 133 | instead of listing them one by one.) |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 134 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 135 | ### Build the project |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 136 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 137 | Let's build your sample project. Change into the `java-tutorial` directory |
| 138 | and run the following command: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 139 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 140 | ``` |
Googler | 006659e | 2017-07-20 19:48:05 +0200 | [diff] [blame] | 141 | bazel build //:ProjectRunner |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 142 | ``` |
| 143 | Notice the target label - the `//` part is the location of our `BUILD` file |
| 144 | relative to the root of the workspace (in this case, the root itself), and |
| 145 | `ProjectRunner` is what we named that target in the `BUILD` file. (You will |
| 146 | learn about target labels in more detail at the end of this tutorial.) |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 147 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 148 | Bazel produces output similar to the following: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 149 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 150 | ```bash |
Googler | 006659e | 2017-07-20 19:48:05 +0200 | [diff] [blame] | 151 | INFO: Found 1 target... |
| 152 | Target //:ProjectRunner up-to-date: |
| 153 | bazel-bin/ProjectRunner.jar |
| 154 | bazel-bin/ProjectRunner |
| 155 | INFO: Elapsed time: 1.021s, Critical Path: 0.83s |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 156 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 157 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 158 | Congratulations, you just built your first Bazel target! Bazel places build |
| 159 | outputs in the `bazel-bin` directory at the root of the workspace. Browse |
| 160 | through its contents to get an idea for Bazel's output structure. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 161 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 162 | Now test your freshly built binary: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 163 | |
dzc | 51dcd28 | 2017-06-14 22:52:27 +0200 | [diff] [blame] | 164 | ```sh |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 165 | bazel-bin/ProjectRunner |
| 166 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 167 | |
| 168 | ### Review the dependency graph |
| 169 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 170 | Bazel requires build dependencies to be explicitly declared in BUILD files. |
| 171 | Bazel uses those statements to create the project's dependency graph, which |
| 172 | enables accurate incremental builds. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 173 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 174 | Let's visualize our sample project's dependencies. First, generate a text |
| 175 | representation of the dependency graph (run the command at the workspace root): |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 176 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 177 | ``` |
pcloudy | 22f16e4 | 2018-08-31 08:11:48 -0700 | [diff] [blame] | 178 | bazel query --nohost_deps --noimplicit_deps "deps(//:ProjectRunner)" --output graph |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 179 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 180 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 181 | The above command tells Bazel to look for all dependencies for the target |
| 182 | `//:ProjectRunner` (excluding host and implicit dependencies) and format the |
| 183 | output as a graph. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 184 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 185 | Then, paste the text into [GraphViz](http://www.webgraphviz.com/). |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 186 | |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 187 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 188 | As you can see, the project has a single target that build two source files with |
| 189 | no additional dependencies: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 190 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 191 |  |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 192 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 193 | Now that you have set up your workspace, built your project, and examined its |
| 194 | dependencies, let's add some complexity. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 195 | |
| 196 | ## Refine your Bazel build |
| 197 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 198 | While a single target is sufficient for small projects, you may want to split |
| 199 | larger projects into multiple targets and packages to allow for fast incremental |
| 200 | builds (that is, only rebuild what's changed) and to speed up your builds by |
| 201 | building multiple parts of a project at once. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 202 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 203 | ### Specify multiple build targets |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 204 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 205 | Let's split our sample project build into two targets. Replace the contents of |
| 206 | the `java-tutorial/BUILD` file with the following: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 207 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 208 | ``` |
| 209 | java_binary( |
| 210 | name = "ProjectRunner", |
| 211 | srcs = ["src/main/java/com/example/ProjectRunner.java"], |
| 212 | main_class = "com.example.ProjectRunner", |
| 213 | deps = [":greeter"], |
| 214 | ) |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 215 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 216 | java_library( |
| 217 | name = "greeter", |
| 218 | srcs = ["src/main/java/com/example/Greeting.java"], |
| 219 | ) |
| 220 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 221 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 222 | With this configuration, Bazel first builds the `greeter` library, then the |
Passw | 473a916 | 2017-12-22 14:13:12 -0800 | [diff] [blame] | 223 | `ProjectRunner` binary. The `deps` attribute in `java_binary` tells Bazel that |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 224 | the `greeter` library is required to build the `ProjectRunner` binary. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 225 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 226 | Let's build this new version of our project. Run the following command: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 227 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 228 | ``` |
| 229 | bazel build //:ProjectRunner |
| 230 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 231 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 232 | Bazel produces output similar to the following: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 233 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 234 | ``` |
| 235 | INFO: Found 1 target... |
| 236 | Target //:ProjectRunner up-to-date: |
| 237 | bazel-bin/ProjectRunner.jar |
| 238 | bazel-bin/ProjectRunner |
| 239 | INFO: Elapsed time: 2.454s, Critical Path: 1.58s |
| 240 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 241 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 242 | Now test your freshly built binary: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 243 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 244 | ``` |
| 245 | bazel-bin/ProjectRunner |
| 246 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 247 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 248 | If you now modify `ProjectRunner.java` and rebuild the project, Bazel only |
| 249 | recompiles that file. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 250 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 251 | Looking at the dependency graph, you can see that `ProjectRunner` depends on the |
| 252 | same inputs as it did before, but the structure of the build is different: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 253 | |
laurentlb | 79b9431 | 2018-11-07 05:18:59 -0800 | [diff] [blame] | 254 |  |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 256 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 257 | You've now built the project with two targets. The `ProjectRunner` target builds |
| 258 | two source files and depends on one other target (`:greeter`), which builds |
| 259 | one additional source file. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 260 | |
| 261 | ### Use multiple packages |
| 262 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 263 | Let’s now split the project into multiple packages. If you take a look at the |
| 264 | `src/main/java/com/example/cmdline` directory, you can see that it also contains |
| 265 | a `BUILD` file, plus some source files. Therefore, to Bazel, the workspace now |
| 266 | contains two packages, `//src/main/java/com/example/cmdline` and `//` (since |
| 267 | there is a `BUILD` file at the root of the workspace). |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 268 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 269 | Take a look at the `src/main/java/com/example/cmdline/BUILD` file: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 270 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 271 | ``` |
| 272 | java_binary( |
| 273 | name = "runner", |
| 274 | srcs = ["Runner.java"], |
| 275 | main_class = "com.example.cmdline.Runner", |
| 276 | deps = ["//:greeter"] |
| 277 | ) |
| 278 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 279 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 280 | The `runner` target depends on the `greeter` target in the `//` package (hence |
| 281 | the target label `//:greeter`) - Bazel knows this through the `deps` attribute. |
| 282 | Take a look at the dependency graph: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 283 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 284 |  |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 285 | |
Peter Laird | 4b16e02 | 2017-10-12 16:44:19 +0200 | [diff] [blame] | 286 | However, for the build to succeed, you must explicitly give the `runner` target in |
| 287 | `//src/main/java/com/example/cmdline/BUILD` visibility to targets in |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 288 | `//BUILD` using the `visibility` attribute. This is because by default targets |
| 289 | are only visible to other targets in the same `BUILD` file. (Bazel uses target |
| 290 | visibility to prevent issues such as libraries containing implementation details |
| 291 | leaking into public APIs.) |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 292 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 293 | To do this, add the `visibility` attribute to the `greeter` target in |
| 294 | `java-tutorial/BUILD` as shown below: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 295 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 296 | ``` |
| 297 | java_library( |
| 298 | name = "greeter", |
| 299 | srcs = ["src/main/java/com/example/Greeting.java"], |
| 300 | visibility = ["//src/main/java/com/example/cmdline:__pkg__"], |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 301 | ) |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 302 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 303 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 304 | Let's now build the new package. Run the following command at the root of the |
| 305 | workspace: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 306 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 307 | ``` |
| 308 | bazel build //src/main/java/com/example/cmdline:runner |
| 309 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 310 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 311 | Bazel produces output similar to the following: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 312 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 313 | ``` |
| 314 | INFO: Found 1 target... |
| 315 | Target //src/main/java/com/example/cmdline:runner up-to-date: |
| 316 | bazel-bin/src/main/java/com/example/cmdline/runner.jar |
| 317 | bazel-bin/src/main/java/com/example/cmdline/runner |
| 318 | INFO: Elapsed time: 1.576s, Critical Path: 0.81s |
| 319 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 320 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 321 | Now test your freshly built binary: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 322 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 323 | ``` |
| 324 | ./bazel-bin/src/main/java/com/example/cmdline/runner |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 325 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 326 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 327 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 328 | You've now modified the project to build as two packages, each containing one |
| 329 | target, and understand the dependencies between them. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 330 | |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 331 | |
| 332 | ## Use labels to reference targets |
| 333 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 334 | In `BUILD` files and at the command line, Bazel uses target labels to reference |
| 335 | targets - for example, `//:ProjectRunner` or |
| 336 | `//src/main/java/com/example/cmdline:runner`. Their syntax is as follows: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 337 | |
| 338 | ``` |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 339 | //path/to/package:target-name |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 340 | ``` |
| 341 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 342 | If the target is a rule target, then `path/to/package` is the path to the |
| 343 | directory containing the `BUILD` file, and `target-name` is what you named the |
| 344 | target in the `BUILD` file (the `name` attribute). If the target is a file |
| 345 | target, then `path/to/package` is the path to the root of the package, and |
| 346 | `target-name` is the name of the target file, including its full path. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 347 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 348 | When referencing targets within the same package, you can skip the package path |
| 349 | and just use `//:target-name`. When referencing targets within the same `BUILD` |
| 350 | file, you can even skip the `//` workspace root identifier and just use |
| 351 | `:target-name`. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 352 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 353 | For example, for targets in the `java-tutorial/BUILD` file, you did not have to |
| 354 | specify a package path, since the workspace root is itself a package (`//`), and |
| 355 | your two target labels were simply `//:ProjectRunner` and `//:greeter`. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 356 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 357 | However, for targets in the `//src/main/java/com/example/cmdline/BUILD` file you |
| 358 | had to specify the full package path of `//src/main/java/com/example/cmdline` |
| 359 | and your target label was `//src/main/java/com/example/cmdline:runner`. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 360 | |
| 361 | ## Package a Java target for deployment |
| 362 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 363 | Let’s now package a Java target for deployment by building the binary with all |
| 364 | of its runtime dependencies. This lets you run the binary outside of your |
| 365 | development environment. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 366 | |
dzc | 205125b | 2017-06-26 11:01:47 +0200 | [diff] [blame] | 367 | As you remember, the [java_binary](../be/java.html#java_binary) build rule |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 368 | produces a `.jar` and a wrapper shell script. Take a look at the contents of |
| 369 | `runner.jar` using this command: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 370 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 371 | ``` |
| 372 | jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar |
| 373 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 374 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 375 | The contents are: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 376 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 377 | ``` |
| 378 | META-INF/ |
| 379 | META-INF/MANIFEST.MF |
| 380 | com/ |
| 381 | com/example/ |
| 382 | com/example/cmdline/ |
| 383 | com/example/cmdline/Runner.class |
| 384 | ``` |
| 385 | As you can see, `runner.jar` contains `Runner.class`, but not its dependency, |
| 386 | `Greeting.class`. The `runner` script that Bazel generates adds `greeter.jar` |
| 387 | to the classpath, so if you leave it like this, it will run locally, but it |
| 388 | won't run standalone on another machine. Fortunately, the `java_binary` rule |
| 389 | allows you to build a self-contained, deployable binary. To build it, add the |
| 390 | `_deploy.jar` suffix to the file name when building `runner.jar` |
| 391 | (<target-name>_deploy.jar): |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 392 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 393 | ``` |
| 394 | bazel build //src/main/java/com/example/cmdline:runner_deploy.jar |
| 395 | ``` |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 396 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 397 | Bazel produces output similar to the following: |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 398 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 399 | ``` |
| 400 | INFO: Found 1 target... |
| 401 | Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date: |
| 402 | bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar |
| 403 | INFO: Elapsed time: 1.700s, Critical Path: 0.23s |
| 404 | ``` |
| 405 | You have just built `runner_deploy.jar`, which you can run standalone away from |
| 406 | your development environment since it contains the required runtime |
| 407 | dependencies. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 408 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 409 | ## Further reading |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 410 | |
dzc | 205125b | 2017-06-26 11:01:47 +0200 | [diff] [blame] | 411 | * [External Dependencies](../external.html) to learn more about working with |
| 412 | local and remote repositories. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 413 | |
dzc | 205125b | 2017-06-26 11:01:47 +0200 | [diff] [blame] | 414 | * The [Build Encyclopedia](../be/overview.html) to learn more about Bazel. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 415 | |
dzc | 205125b | 2017-06-26 11:01:47 +0200 | [diff] [blame] | 416 | * The [C++ build tutorial](../tutorial/cpp.md) to get started with building |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 417 | C++ projects with Bazel. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 418 | |
Laszlo Csomor | 5d35794 | 2018-06-12 01:56:45 -0700 | [diff] [blame] | 419 | * The [Android application tutorial](../tutorial/android-app.md) and |
| 420 | [iOS application tutorial](../tutorial/ios-app.md) to get started with |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 421 | building mobile applications for Android and iOS with Bazel. |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 422 | |
Googler | 8af9dc5 | 2017-06-07 13:49:48 -0400 | [diff] [blame] | 423 | Happy building! |
dzc | 22b85a2 | 2017-05-31 20:37:50 +0200 | [diff] [blame] | 424 | |