site/docs/tutorial/java.md - bazel - Git at Google

 ---
 layout: documentation
 title: Introduction to Bazel
 ---

 Introduction to Bazel: Build Java
 ==========

 This tutorial is an introduction for anyone getting started with Bazel. It
 focuses on the concepts, setup, and use of Bazel using a Java sample project.

 Estimated time: 30 min

 ## What you will learn

 In this tutorial you'll learn how to:

 *  Build a target from source files
 *  Produce a visual representation of the dependency graph
 *  Break a monolithic binary into smaller libraries
 *  Use multiple Bazel packages
 *  Control the visibility of a target between packages
 *  Use labels to reference a target
 *  Deploy your target

 ## Before you begin

 *  [Install Bazel](/docs/install.md)

 ## Create the sample Java project

 The first step in this tutorial is to create a small Java project. Even though
 the project is in Java, this tutorial will focus on concepts that are helpful
 for using Bazel in any language.

 1.  Create the directory `~/my-project/`

 2.  Move to this directory:

     ```
     cd ~/my-project
     ```

 3.  Create the following directories under `my-project`:

     ```
     mkdir -p src/main/java/com/example
     ```

     Note that path uses conventions specific to Java  programs. Programs written
     in other languages may have a different workspace path and directory
     structure.

 4.  In the directory you created, add a file called `Greeting.java` with the
     following contents:

     ```java
     package com.example;

     public class Greeting {
         public static void sayHi() {
             System.out.println("Hi!");
         }
     }
     ```

 5.  Add a second file `ProjectRunner.java` with the following contents:

     ```java
     package com.example;

     public class ProjectRunner {
         public static void main(String args[]) {
             Greeting.sayHi();
         }
     }
     ```

 You’ve now created a small Java project. It contains one file that will be
 compiled into a library, and another which will be an executable that uses the
 library.

 The rest of this tutorial focuses on setting up and using Bazel to build these
 source files.

 ## Build with Bazel

 ### Set up the workspace

 Workspaces are directories that contain the source files for one or more
 software projects, as well as a WORKSPACE file and BUILD files that contain
 the instructions that Bazel uses to build the software. The workspace may also
 contain symbolic links to output directories.

 To define the workspace, create an empty text file at the root of the project
 and name it `WORKSPACE`. You now have: `~/my-project/WORKSPACE`.

 This directory and its subdirectories are now part of the same workspace. When
 Bazel builds an output, all inputs and dependencies must be in the same
 workspace. Anything in different workspaces are independent of each other,
 though there are ways to link workspaces that are beyond the scope of this
 introduction tutorial.

 If you also do the [C++ tutorial](/docs/tutorial/cpp.md), you’ll notice it uses
 the same workspace. Bazel can understand multiple targets in multiple languages
 in a single workspace.

 ### Create a BUILD file

 Bazel looks for files named `BUILD` which describe how to build the project.

 1.  In the `~/my-project` directory, create a file and name it BUILD. This BUILD
     file is a sibling of the WORKSPACE file.

     In the BUILD file, you use a declarative language similar to Python to
     create instances of Bazel rules. These instances are called *rule targets*.
     In Bazel, *targets* are either files or rule targets and they are the
     elements in a workspace that you can ask Bazel to build.

     For this project, you’ll use the built-in rule `java_binary`. Bazel's
     built-in rules are all documented in the
     [Build Encyclopedia](/docs/be/overview.html). You can also create your own
     rules using the [Bazel rule extension framework](/docs/skylark/concepts.md).

 2.  Add this text to the BUILD file:

     ```
     java_binary(
         name = "my-runner",
         srcs = glob(["src/main/java/com/example/*.java"]),
         main_class = "com.example.ProjectRunner",
     )
     ```
 As you can see, the text in the BUILD file doesn’t describe what Bazel does
 when it executes this rule target. The rule’s implementation handles the
 complexity of how it works (such as the compiler used).

 You can treat the rule as a black box, focusing on what inputs it needs, and
 the outputs it produces. This rule builds a Java archive ("jar file") as well
 as a wrapper shell script with the same name as the rule target.

 When you’re writing your own BUILD file, go to the
 [Build Encyclopedia](/docs/be/overview.html) for a description of what a rule
 does and for its list of possible attributes you can define. For example,
 here’s the entry for the [java_binary](/docs/be/java.html#java_binary) rule in
 the Build Encyclopedia. The Build Encyclopedia has information about all of the
 rules that are compiled into Bazel.

 Let’s take a look at the rule target that you added to the BUILD file.

 Each rule instantiation in the BUILD file creates one rule target. Here, you’ve
 instantiated the rule `java_binary`, creating the target `my-runner`.

 Different rules will require different attributes, though all must include a
 “name” attribute. You use these attributes to explicitly list all of the
 target’s dependencies and options. In the target above:

 *  `my-runner` is the name of the rule target created

 *  `glob(["src/main/java/com/example/*.java"])` includes every file in that
    directory that ends with .java (see the Build Encyclopedia for more
    information about [globbing](/docs/be/functions.html#glob))

 *  `"com.example.ProjectRunner"` specifies the class that contains the main
    method.

 ### Build with Bazel

 Now you’re ready to build the Java binary. To do so, you’ll use the command
 `bazel build` with the target label `//:my-runner`. You reference targets by
 using their label. Label syntax is described later in this tutorial.

 1.  Build my-runner by using this command:

     ```
     bazel build //:my-runner
     ```

     You’ll see output similar to:

     ```
     INFO: Found 1 target...
     Target //:my-runner up-to-date:
       bazel-bin/my-runner.jar
       bazel-bin/my-runner
     INFO: Elapsed time: 1.021s, Critical Path: 0.83s
     ```

 2.  Now execute the file by using this command:

     ```
     bazel-bin/my-runner
     ```

 Congratulations, you've built your first Bazel target!

 Let’s take a look at what you built. In `~/my-project`, Bazel created the
 directory `bazel-bin` as well as other directories to store information about
 the build. Open this directory to look at the files created during the build
 process. These output directories keep the outputs separate from your source
 tree.

 ### Review the dependency graph

 Bazel requires build dependencies to be explicitly declared in BUILD
 files. The build will fail if dependencies are missing, so when a build works
 the declared dependencies are accurate. With this explicit information about
 dependencies, Bazel creates a build graph and uses it to accurately perform
 incremental builds. Our small Java project isn’t too exciting, but let’s check
 out its build graph.

 The command `bazel query` retrieves information about the graph and the
 relationships between targets. Let’s use it to produce a visual representation
 of the build graph.

 1.  From the root of the workspace (`my-project`), produce a text description
     of the graph by using the command:

     ```
     bazel query --noimplicit_deps 'deps(//:my-runner)' --output graph
     ```

 2.  Then, paste the output into Graphviz
     ([http://www.webgraphviz.com/](http://www.webgraphviz.com/)) to see the
     visual representation.

     The graph for the target my-runner will look like this:

     ![Dependency graph of the target 'my-runner'](/assets/tutorial_java_01.svg)

 You can see that `my-runner` depends on the two source files in your Java
 project.

 You have now set up the workspace and BUILD file, and used Bazel to build your
 project. You have also created a visual representation of the build graph to
 see the structure of your build.

 ## Refine your Bazel build

 ### Add dependencies

 Creating one rule target to build your entire project may be sufficient for
 small projects. As projects get larger it's important to break up the build
 into self-contained libraries that can be assembled into a final product.
 Self-contained libraries mean that everything doesn't need to be rebuilt after
 small changes and that Bazel can parallelize more of the build steps. These
 self-contained libraries also encourages good code hygiene.

 To break up a project, create a separate rule target for the each subcomponent
 and then add the subcomponents as dependencies. For the project in this
 tutorial, create a rule target to compile the library, and make the executable
 depend on it.

 1.  Replace the text in the BUILD file with the text below:

     ```
     java_binary(
         name = "my-runner",
         srcs = ["src/main/java/com/example/ProjectRunner.java"],
         main_class = "com.example.ProjectRunner",
         deps = [":greeter"],
     )

     java_library(
         name = "greeter",
         srcs = ["src/main/java/com/example/Greeting.java"],
     )
     ```

 The new `deps` attribute in `java_binary` tells Bazel that the `greeter` library
 will be needed to compile the binary. Rules for many languages support the
 `deps` attribute, though the exact semantics of the attribute will vary based
 on the language and the type of target. The rule
 [java_library](/docs/be/java.html#java_library) compiles sources into
 a .jar file. Remember to go to the [Build Encyclopedia](/docs/be/overview.html)
 for details about specific rules.

 This BUILD file builds the same files as before, but in a different way: now
 Bazel will first build the `greeter` library and then build `my-runner`.

 2.  Try building //:my-runner using the command:

     ```
     bazel build //:my-runner
     ```

     You’ll see output similar to:

     ```
     INFO: Found 1 target...
     Target //:my-runner up-to-date:
       bazel-bin/my-runner.jar
       bazel-bin/my-runner
     INFO: Elapsed time: 2.454s, Critical Path: 1.58s
     ```

     3. Execute the file by using this command::

     ```
     bazel-bin/my-runner
     ```

 If you now edit `ProjectRunner.java` and rebuild `my-runner`, the source file
 `Greeting.java` will not be recompiled. When the BUILD file had only the one
 target, both source files would be recompiled after any change.

 Looking at the dependency graph, you can see that `my-runner` depends on the
 same inputs as it did before, but the structure of the build is different.

 The original dependency graph for `my-runner` looked link this:

 ![Original dependency graph of the target 'my-runner'](/assets/tutorial_java_01.svg)

 The dependency graph for `my-runner` after adding a dependency looks like this:

 ![Dependency graph of the target 'my-runner' after adding a dependency](/assets/tutorial_java_02.svg)

 ### Use multiple packages

 For larger projects, you will often be dealing with several directories in your
 workspace. You can organize your build process by adding a BUILD file to the
 top directory of source files that you want to organize together. A directory
 containing a BUILD file is called a package.

 Note that Bazel and Java both have the concept of a package. These are
 unrelated to each other, though both are related to the structure of the
 directories.

 Let’s build the java project using multiple packages.

 1.  First, let’s make the Java project a bit more complex.

     1.  Add the following directory and file:

         ```
         mkdir -p src/main/java/com/example/cmdline
         ```
     2. In the directory cmdline, add the file Runner.java with the following
        contents:

         ```java
         package com.example.cmdline;

         import com.example.Greeting;

         public class Runner {
             public static void main(String args[]) {
                 Greeting.sayHi();
             }
         }
         ```

         Now you have a slightly larger Java project that you can organize with
         multiple packages.

 2.  In the directory `src/main/java/com/example/cmdline`, add an empty text
     file and name it BUILD. The structure of the Java project is now:

     ```
     ├── BUILD
     ├── src
     │   └── main
     │       └── java
     │           └── com
     │               └── example
     │                   ├── cmdline
     │                   │   ├── BUILD
     │                   │   └── Runner.java
     │                   ├── Greeting.java
     │                   └── ProjectRunner.java
     └── WORKSPACE
     ```

     Each directory in the workspace can be part of only one package. The
     workspace now has two BUILD files, and so has two packages:

     1.  The directory `my-project` and its subdirectories (but not including
     subdirectories with their own BUILD file, such as `cmdline`), and

     2.  The directory `cmdline` and any subdirectories.

 3.  In the new BUILD file, add the following text:

     ```
     java_binary(
         name = "runner",
         srcs = ["Runner.java"],
         main_class = "com.example.cmdline.Runner",
         deps = ["//:greeter"]
     )
     ```

     The file `Runner.java` depends on `com.example.Greeting`. In the BUILD file
     this dependency is shown by listing the rule target `greeter` (with the
     label `//:greeter`).

     Below is what the dependency graph for runner will look like. You can see
     how `//:greeter` gives the dependency on `Greeting.java`.

     ![Dependency graph of the target 'runner'](/assets/tutorial_java_03.svg)


 4.  However, if you try to build runner right now you'll get a permissions
     error. You can see the permission error by trying to build the target using
     the command:

     ```
     bazel build //src/main/java/com/example/cmdline:runner
     ```

     By default, rule targets are private, which means that they can only be
     depended on by targets in the same BUILD file. This privacy prevents
     libraries that are implementation details from leaking into public APIs,
     but it also means that you must explicitly allow `runner` to depend on
     `//:greeter`.


 5.  Make a rule target visible to rule targets in other BUILD files by adding
     a `visibility` attribute. To make the `greeter` rule target in
     `~/my-project/BUILD` visible to any rule target in the new package, add the
     following visibility attribute:

     ```
     java_library(
         name = "greeter",
         srcs = ["src/main/java/com/example/Greeting.java"],
         visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
     )
     ```

     The target `//:greeter` is now visible to any target in the
     `//src/main/java/com/example/cmdline` package.

     See the Build Encyclopedia for more
     [visibility options](/docs/be/common-definitions.html#common.visibility).


 6.  Now you can build the runner binary by using the command:

     ```
     bazel build //src/main/java/com/example/cmdline:runner
     ```

     You’ll see output similar to:

     ```
     INFO: Found 1 target...
     Target //src/main/java/com/example/cmdline:runner up-to-date:
       bazel-bin/src/main/java/com/example/cmdline/runner.jar
       bazel-bin/src/main/java/com/example/cmdline/runner
     INFO: Elapsed time: 1.576s, Critical Path: 0.81s
     ```


 7.  Execute the file by using this command:

     ```
     bazel-bin/src/main/java/com/example/cmdline/runner
     ```

 You’ve now refined your build so that it is broken down into smaller
 self-contained libraries, and so that the explicit dependencies are more
 granular. You’ve also built the Java project using multiple packages.

 ## Use labels to reference targets

 In the BUILD files and in the command line, you have been using target labels
 to reference targets. The label’s syntax is: `//path/to/package:target-name`,
 where “`//`” is the workspace’s root, and “`:`” separates the package name and
 the target name. If the target is a rule target and so defined in a BUILD file,
 “`path/to/package`” would be the path of the BUILD file itself. “`Target-name`”
 would be the same as the “`name`” attribute in the target in the BUILD file.

 The first BUILD file you created in this tutorial is in the same directory as
 the WORKSPACE file. When referencing rule targets defined in that file, nothing
 is needed for the path to the package because the workspace root and the package
 root are the same directory. Here are the labels of the two targets defined
 in that first BUILD file:

 ```
 //:my-runner
 //:greeter
 ```

 The second BUILD file has a longer path from the workspace root to the package
 root. The label for the target in that BUILD file is:

 ```
 //src/main/java/com/example/cmdline:runner
 ```

 Target labels can be shortened in a variety of ways. Within a BUILD file, if
 you’re referencing a target from the same package, you can write the label
 starting at “`:`”. For example, the rule target `greeter` can always be written
 as `//:greeter`, and in the BUILD file where it’s defined, it can also be
 written as `:greeter`. This shortened label in a BUILD file makes it immediately
 clear which targets are in the current package.

 A rule target’s name will always be defined by its name attribute. A target’s
 name is a bit more complex when it’s in a directory other than the root
 of the package. In that case, the target’s label is:
 `//path/to/package:path/to/file/file_name`.

 ## Package a Java target for deployment

 To understand what you’ve built and what else can be built with Bazel, you need
 to understand the capabilities of the rules used in your BUILD files. Always go
 to the [Build Encyclopedia](/docs/be/overview.html) for this information.

 Let’s look at packaging a Java target for deployment, which requires you to
 know the capabilities of the rule `java_binary`.

 You’re able to run the Java binaries you created in this tutorial, but you
 can’t simply run it on a server, because it relies on the greeting library jar
 to actually run. "Packaging an artifact so it can be run reliably outside the
 development environment involves bundling it with all of its runtime
 dependencies.  Let's see now what’s needed to package the binaries.

 The rule [java_binary](/docs/be/java.html#java_binary) produces a Java archive
 (“jar file”) and a wrapper shell script. The file `<target-name>_deploy.jar`
 is suitable for deployment, but it’s only built by this rule if explicitly
 requested. Let’s investigate.

 1.  Look at the contents of the output `runner.jar` by using this command:

     ```
     jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar
     ```

     You’ll see output similar to:

     ```
     META-INF/
     META-INF/MANIFEST.MF
     com/
     com/example/
     com/example/cmdline/
     com/example/cmdline/Runner.class
     ```

     You can see that `runner.jar` contains `Runner.class`, but not its
     dependency `Greeting.class`. The `runner` script that Bazel generates adds
     the greeter jar to the classpath, so running this program works locally. It
     will not work if you want to copy `runner.jar` to another machine and use
     it as a standalone binary.


 2.  The rule `java_binary` allows you to build a self-contained binary that can
     be deployed. To create this binary, build `runner_deploy.jar` (or, more
     generally, `<target-name>_deploy.jar`)  by using this command:

     ```
     bazel build //src/main/java/com/example/cmdline:runner_deploy.jar
     ```

     You’ll see output similar to:

     ```
     INFO: Found 1 target...
     Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
       bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
     INFO: Elapsed time: 1.700s, Critical Path: 0.23s
     ```

     The file runner_deploy.jar will contain all of its dependencies, and so can
     be used as a standalone binary.

 You’ve now created a Java target that you can distribute and deploy. To do so,
 you had to be aware of what outputs the Bazel Java rule `java_binary` is able to
 produce.

 ## Further topics

 *  Try the tutorial [Build C++](/docs/tutorial/cpp.md).
 *  Try the tutorial [Build Mobile Application](/docs/tutorial/app.md).
	---
	layout: documentation
	title: Introduction to Bazel
	---

	Introduction to Bazel: Build Java
	==========

	This tutorial is an introduction for anyone getting started with Bazel. It
	focuses on the concepts, setup, and use of Bazel using a Java sample project.

	Estimated time: 30 min

	## What you will learn

	In this tutorial you'll learn how to:

	* Build a target from source files
	* Produce a visual representation of the dependency graph
	* Break a monolithic binary into smaller libraries
	* Use multiple Bazel packages
	* Control the visibility of a target between packages
	* Use labels to reference a target
	* Deploy your target

	## Before you begin

	* [Install Bazel](/docs/install.md)

	## Create the sample Java project

	The first step in this tutorial is to create a small Java project. Even though
	the project is in Java, this tutorial will focus on concepts that are helpful
	for using Bazel in any language.

	1. Create the directory `~/my-project/`

	2. Move to this directory:

	```
	cd ~/my-project
	```

	3. Create the following directories under `my-project`:

	```
	mkdir -p src/main/java/com/example
	```

	Note that path uses conventions specific to Java programs. Programs written
	in other languages may have a different workspace path and directory
	structure.

	4. In the directory you created, add a file called `Greeting.java` with the
	following contents:

	```java
	package com.example;

	public class Greeting {
	public static void sayHi() {
	System.out.println("Hi!");
	}
	}
	```

	5. Add a second file `ProjectRunner.java` with the following contents:

	```java
	package com.example;

	public class ProjectRunner {
	public static void main(String args[]) {
	Greeting.sayHi();
	}
	}
	```

	You’ve now created a small Java project. It contains one file that will be
	compiled into a library, and another which will be an executable that uses the
	library.

	The rest of this tutorial focuses on setting up and using Bazel to build these
	source files.

	## Build with Bazel

	### Set up the workspace

	Workspaces are directories that contain the source files for one or more
	software projects, as well as a WORKSPACE file and BUILD files that contain
	the instructions that Bazel uses to build the software. The workspace may also
	contain symbolic links to output directories.

	To define the workspace, create an empty text file at the root of the project
	and name it `WORKSPACE`. You now have: `~/my-project/WORKSPACE`.

	This directory and its subdirectories are now part of the same workspace. When
	Bazel builds an output, all inputs and dependencies must be in the same
	workspace. Anything in different workspaces are independent of each other,
	though there are ways to link workspaces that are beyond the scope of this
	introduction tutorial.

	If you also do the [C++ tutorial](/docs/tutorial/cpp.md), you’ll notice it uses
	the same workspace. Bazel can understand multiple targets in multiple languages
	in a single workspace.

	### Create a BUILD file

	Bazel looks for files named `BUILD` which describe how to build the project.

	1. In the `~/my-project` directory, create a file and name it BUILD. This BUILD
	file is a sibling of the WORKSPACE file.

	In the BUILD file, you use a declarative language similar to Python to
	create instances of Bazel rules. These instances are called rule targets.
	In Bazel, targets are either files or rule targets and they are the
	elements in a workspace that you can ask Bazel to build.

	For this project, you’ll use the built-in rule `java_binary`. Bazel's
	built-in rules are all documented in the
	[Build Encyclopedia](/docs/be/overview.html). You can also create your own
	rules using the [Bazel rule extension framework](/docs/skylark/concepts.md).

	2. Add this text to the BUILD file:

	```
	java_binary(
	name = "my-runner",
	srcs = glob(["src/main/java/com/example/*.java"]),
	main_class = "com.example.ProjectRunner",
	)
	```
	As you can see, the text in the BUILD file doesn’t describe what Bazel does
	when it executes this rule target. The rule’s implementation handles the
	complexity of how it works (such as the compiler used).

	You can treat the rule as a black box, focusing on what inputs it needs, and
	the outputs it produces. This rule builds a Java archive ("jar file") as well
	as a wrapper shell script with the same name as the rule target.

	When you’re writing your own BUILD file, go to the
	[Build Encyclopedia](/docs/be/overview.html) for a description of what a rule
	does and for its list of possible attributes you can define. For example,
	here’s the entry for the [java_binary](/docs/be/java.html#java_binary) rule in
	the Build Encyclopedia. The Build Encyclopedia has information about all of the
	rules that are compiled into Bazel.

	Let’s take a look at the rule target that you added to the BUILD file.

	Each rule instantiation in the BUILD file creates one rule target. Here, you’ve
	instantiated the rule `java_binary`, creating the target `my-runner`.

	Different rules will require different attributes, though all must include a
	“name” attribute. You use these attributes to explicitly list all of the
	target’s dependencies and options. In the target above:

	* `my-runner` is the name of the rule target created

	* `glob(["src/main/java/com/example/*.java"])` includes every file in that
	directory that ends with .java (see the Build Encyclopedia for more
	information about [globbing](/docs/be/functions.html#glob))

	* `"com.example.ProjectRunner"` specifies the class that contains the main
	method.

	### Build with Bazel

	Now you’re ready to build the Java binary. To do so, you’ll use the command
	`bazel build` with the target label `//:my-runner`. You reference targets by
	using their label. Label syntax is described later in this tutorial.

	1. Build my-runner by using this command:

	```
	bazel build //:my-runner
	```

	You’ll see output similar to:

	```
	INFO: Found 1 target...
	Target //:my-runner up-to-date:
	bazel-bin/my-runner.jar
	bazel-bin/my-runner
	INFO: Elapsed time: 1.021s, Critical Path: 0.83s
	```

	2. Now execute the file by using this command:

	```
	bazel-bin/my-runner
	```

	Congratulations, you've built your first Bazel target!

	Let’s take a look at what you built. In `~/my-project`, Bazel created the
	directory `bazel-bin` as well as other directories to store information about
	the build. Open this directory to look at the files created during the build
	process. These output directories keep the outputs separate from your source
	tree.

	### Review the dependency graph

	Bazel requires build dependencies to be explicitly declared in BUILD
	files. The build will fail if dependencies are missing, so when a build works
	the declared dependencies are accurate. With this explicit information about
	dependencies, Bazel creates a build graph and uses it to accurately perform
	incremental builds. Our small Java project isn’t too exciting, but let’s check
	out its build graph.

	The command `bazel query` retrieves information about the graph and the
	relationships between targets. Let’s use it to produce a visual representation
	of the build graph.

	1. From the root of the workspace (`my-project`), produce a text description
	of the graph by using the command:

	```
	bazel query --noimplicit_deps 'deps(//:my-runner)' --output graph
	```

	2. Then, paste the output into Graphviz
	([http://www.webgraphviz.com/](http://www.webgraphviz.com/)) to see the
	visual representation.

	The graph for the target my-runner will look like this:

	![Dependency graph of the target 'my-runner'](/assets/tutorial_java_01.svg)

	You can see that `my-runner` depends on the two source files in your Java
	project.

	You have now set up the workspace and BUILD file, and used Bazel to build your
	project. You have also created a visual representation of the build graph to
	see the structure of your build.

	## Refine your Bazel build

	### Add dependencies

	Creating one rule target to build your entire project may be sufficient for
	small projects. As projects get larger it's important to break up the build
	into self-contained libraries that can be assembled into a final product.
	Self-contained libraries mean that everything doesn't need to be rebuilt after
	small changes and that Bazel can parallelize more of the build steps. These
	self-contained libraries also encourages good code hygiene.

	To break up a project, create a separate rule target for the each subcomponent
	and then add the subcomponents as dependencies. For the project in this
	tutorial, create a rule target to compile the library, and make the executable
	depend on it.

	1. Replace the text in the BUILD file with the text below:

	```
	java_binary(
	name = "my-runner",
	srcs = ["src/main/java/com/example/ProjectRunner.java"],
	main_class = "com.example.ProjectRunner",
	deps = [":greeter"],
	)

	java_library(
	name = "greeter",
	srcs = ["src/main/java/com/example/Greeting.java"],
	)
	```

	The new `deps` attribute in `java_binary` tells Bazel that the `greeter` library
	will be needed to compile the binary. Rules for many languages support the
	`deps` attribute, though the exact semantics of the attribute will vary based
	on the language and the type of target. The rule
	[java_library](/docs/be/java.html#java_library) compiles sources into
	a .jar file. Remember to go to the [Build Encyclopedia](/docs/be/overview.html)
	for details about specific rules.

	This BUILD file builds the same files as before, but in a different way: now
	Bazel will first build the `greeter` library and then build `my-runner`.

	2. Try building //:my-runner using the command:

	```
	bazel build //:my-runner
	```

	You’ll see output similar to:

	```
	INFO: Found 1 target...
	Target //:my-runner up-to-date:
	bazel-bin/my-runner.jar
	bazel-bin/my-runner
	INFO: Elapsed time: 2.454s, Critical Path: 1.58s
	```

	3. Execute the file by using this command::

	```
	bazel-bin/my-runner
	```

	If you now edit `ProjectRunner.java` and rebuild `my-runner`, the source file
	`Greeting.java` will not be recompiled. When the BUILD file had only the one
	target, both source files would be recompiled after any change.

	Looking at the dependency graph, you can see that `my-runner` depends on the
	same inputs as it did before, but the structure of the build is different.

	The original dependency graph for `my-runner` looked link this:

	![Original dependency graph of the target 'my-runner'](/assets/tutorial_java_01.svg)

	The dependency graph for `my-runner` after adding a dependency looks like this:

	![Dependency graph of the target 'my-runner' after adding a dependency](/assets/tutorial_java_02.svg)

	### Use multiple packages

	For larger projects, you will often be dealing with several directories in your
	workspace. You can organize your build process by adding a BUILD file to the
	top directory of source files that you want to organize together. A directory
	containing a BUILD file is called a package.

	Note that Bazel and Java both have the concept of a package. These are
	unrelated to each other, though both are related to the structure of the
	directories.

	Let’s build the java project using multiple packages.

	1. First, let’s make the Java project a bit more complex.

	1. Add the following directory and file:

	```
	mkdir -p src/main/java/com/example/cmdline
	```
	2. In the directory cmdline, add the file Runner.java with the following
	contents:

	```java
	package com.example.cmdline;

	import com.example.Greeting;

	public class Runner {
	public static void main(String args[]) {
	Greeting.sayHi();
	}
	}
	```

	Now you have a slightly larger Java project that you can organize with
	multiple packages.

	2. In the directory `src/main/java/com/example/cmdline`, add an empty text
	file and name it BUILD. The structure of the Java project is now:

	```
	├── BUILD
	├── src
	│ └── main
	│ └── java
	│ └── com
	│ └── example
	│ ├── cmdline
	│ │ ├── BUILD
	│ │ └── Runner.java
	│ ├── Greeting.java
	│ └── ProjectRunner.java
	└── WORKSPACE
	```

	Each directory in the workspace can be part of only one package. The
	workspace now has two BUILD files, and so has two packages:

	1. The directory `my-project` and its subdirectories (but not including
	subdirectories with their own BUILD file, such as `cmdline`), and

	2. The directory `cmdline` and any subdirectories.

	3. In the new BUILD file, add the following text:

	```
	java_binary(
	name = "runner",
	srcs = ["Runner.java"],
	main_class = "com.example.cmdline.Runner",
	deps = ["//:greeter"]
	)
	```

	The file `Runner.java` depends on `com.example.Greeting`. In the BUILD file
	this dependency is shown by listing the rule target `greeter` (with the
	label `//:greeter`).

	Below is what the dependency graph for runner will look like. You can see
	how `//:greeter` gives the dependency on `Greeting.java`.

	![Dependency graph of the target 'runner'](/assets/tutorial_java_03.svg)


	4. However, if you try to build runner right now you'll get a permissions
	error. You can see the permission error by trying to build the target using
	the command:

	```
	bazel build //src/main/java/com/example/cmdline:runner
	```

	By default, rule targets are private, which means that they can only be
	depended on by targets in the same BUILD file. This privacy prevents
	libraries that are implementation details from leaking into public APIs,
	but it also means that you must explicitly allow `runner` to depend on
	`//:greeter`.


	5. Make a rule target visible to rule targets in other BUILD files by adding
	a `visibility` attribute. To make the `greeter` rule target in
	`~/my-project/BUILD` visible to any rule target in the new package, add the
	following visibility attribute:

	```
	java_library(
	name = "greeter",
	srcs = ["src/main/java/com/example/Greeting.java"],
	visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
	)
	```

	The target `//:greeter` is now visible to any target in the
	`//src/main/java/com/example/cmdline` package.

	See the Build Encyclopedia for more
	[visibility options](/docs/be/common-definitions.html#common.visibility).


	6. Now you can build the runner binary by using the command:

	```
	bazel build //src/main/java/com/example/cmdline:runner
	```

	You’ll see output similar to:

	```
	INFO: Found 1 target...
	Target //src/main/java/com/example/cmdline:runner up-to-date:
	bazel-bin/src/main/java/com/example/cmdline/runner.jar
	bazel-bin/src/main/java/com/example/cmdline/runner
	INFO: Elapsed time: 1.576s, Critical Path: 0.81s
	```


	7. Execute the file by using this command:

	```
	bazel-bin/src/main/java/com/example/cmdline/runner
	```

	You’ve now refined your build so that it is broken down into smaller
	self-contained libraries, and so that the explicit dependencies are more
	granular. You’ve also built the Java project using multiple packages.

	## Use labels to reference targets

	In the BUILD files and in the command line, you have been using target labels
	to reference targets. The label’s syntax is: `//path/to/package:target-name`,
	where “`//`” is the workspace’s root, and “`:`” separates the package name and
	the target name. If the target is a rule target and so defined in a BUILD file,
	“`path/to/package`” would be the path of the BUILD file itself. “`Target-name`”
	would be the same as the “`name`” attribute in the target in the BUILD file.

	The first BUILD file you created in this tutorial is in the same directory as
	the WORKSPACE file. When referencing rule targets defined in that file, nothing
	is needed for the path to the package because the workspace root and the package
	root are the same directory. Here are the labels of the two targets defined
	in that first BUILD file:

	```
	//:my-runner
	//:greeter
	```

	The second BUILD file has a longer path from the workspace root to the package
	root. The label for the target in that BUILD file is:

	```
	//src/main/java/com/example/cmdline:runner
	```

	Target labels can be shortened in a variety of ways. Within a BUILD file, if
	you’re referencing a target from the same package, you can write the label
	starting at “`:`”. For example, the rule target `greeter` can always be written
	as `//:greeter`, and in the BUILD file where it’s defined, it can also be
	written as `:greeter`. This shortened label in a BUILD file makes it immediately
	clear which targets are in the current package.

	A rule target’s name will always be defined by its name attribute. A target’s
	name is a bit more complex when it’s in a directory other than the root
	of the package. In that case, the target’s label is:
	`//path/to/package:path/to/file/file_name`.

	## Package a Java target for deployment

	To understand what you’ve built and what else can be built with Bazel, you need
	to understand the capabilities of the rules used in your BUILD files. Always go
	to the [Build Encyclopedia](/docs/be/overview.html) for this information.

	Let’s look at packaging a Java target for deployment, which requires you to
	know the capabilities of the rule `java_binary`.

	You’re able to run the Java binaries you created in this tutorial, but you
	can’t simply run it on a server, because it relies on the greeting library jar
	to actually run. "Packaging an artifact so it can be run reliably outside the
	development environment involves bundling it with all of its runtime
	dependencies. Let's see now what’s needed to package the binaries.

	The rule [java_binary](/docs/be/java.html#java_binary) produces a Java archive
	(“jar file”) and a wrapper shell script. The file `<target-name>_deploy.jar`
	is suitable for deployment, but it’s only built by this rule if explicitly
	requested. Let’s investigate.

	1. Look at the contents of the output `runner.jar` by using this command:

	```
	jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar
	```

	You’ll see output similar to:

	```
	META-INF/
	META-INF/MANIFEST.MF
	com/
	com/example/
	com/example/cmdline/
	com/example/cmdline/Runner.class
	```

	You can see that `runner.jar` contains `Runner.class`, but not its
	dependency `Greeting.class`. The `runner` script that Bazel generates adds
	the greeter jar to the classpath, so running this program works locally. It
	will not work if you want to copy `runner.jar` to another machine and use
	it as a standalone binary.


	2. The rule `java_binary` allows you to build a self-contained binary that can
	be deployed. To create this binary, build `runner_deploy.jar` (or, more
	generally, `<target-name>_deploy.jar`) by using this command:

	```
	bazel build //src/main/java/com/example/cmdline:runner_deploy.jar
	```

	You’ll see output similar to:

	```
	INFO: Found 1 target...
	Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
	bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
	INFO: Elapsed time: 1.700s, Critical Path: 0.23s
	```

	The file runner_deploy.jar will contain all of its dependencies, and so can
	be used as a standalone binary.

	You’ve now created a Java target that you can distribute and deploy. To do so,
	you had to be aware of what outputs the Bazel Java rule `java_binary` is able to
	produce.

	## Further topics

	* Try the tutorial [Build C++](/docs/tutorial/cpp.md).
	* Try the tutorial [Build Mobile Application](/docs/tutorial/app.md).