{namespace java_library}

/***/
{template .soyweb}
  {call buck.page}
    {param title: 'java_library()' /}
    {param prettify: true /}
    {param description}
      A rule that is used to define a set of Java files that can be compiled
      together.
    {/param}
    {param content}

{call buck.rule}
{param status: 'FROZEN' /}
{param overview}
A <code>java_library()</code> rule is used to define a set of Java
files that can be compiled together. The main output of a
{sp}<code>java_library()</code> rule is a single JAR file containing all
of the compiled class files and resources.
{/param}

{param args}

{call buck.arg}
  {param name: 'name' /}
  {param desc}
  The name of the rule.
  {/param}
{/call}

{call buck.arg}
  {param name: 'srcs' /}
  {param default : '[]' /}
  {param desc}
  The set of <code>.java</code> files to compile for this rule.
  If any of the files in this list end in <code>.src.zip</code>,
  then the entries in the ZIP file that end in <code>.java</code> will be
  included as ordinary inputs to compilation. This is common when using
  a {call buck.genrule /} to auto-generate some Java source code that
  needs to be compiled with some hand-written Java code.
  {/param}
{/call}

{call buck.arg}
  {param name: 'resources' /}
  {param default : '[]' /}
  {param desc}
  Static files to include among the compiled <code>.class</code>
  {sp}files. These files can be loaded via <a
  href="http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html#getResource(java.lang.String)"
  target="_blank">Class.getResource()</a>.
  <p>
  <strong>Note:</strong> If <code>resources_root</code> isn't set, Buck uses
  the <code>src_roots</code> property in <a
  href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a> to help
  determine where resources should be placed within the generated JAR file.
  <p>
  {/param}
{/call}

{call buck.arg}
  {param name: 'resources_root' /}
  {param default : 'None' /}
  {param desc}
  The path that resources are resolved against. For example, if{sp}
  <code>resources_root</code> is <code>"res"</code> and
  {sp}<code>resources</code>{sp} contains the file{sp}
  <code>"res/com/example/foo.txt"</code>, that file will end up as{sp}
  <code>"com/example/foo.txt"</code> in the output JAR. This parameter
  overrides the <code>src_roots</code> property in <a
  href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'deps' /}
  {param default : '[]' /}
  {param desc}
  Rules (usually other <code>java_library</code> rules) that are used to
  generate the classpath required to compile this <code>java_library</code>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'source' /}
  {param default : '<global value>' /}
  {param desc}
  Specifies the version of Java (as a string) to interpret source
  files as.
  Overrides the value in "source_level" in the "java" section
  of <a
  href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'target' /}
  {param default : '<global value>' /}
  {param desc}
  Specifies the version of Java (as a string) for which to
  generate code.
  Overrides the value in "target_level" in the "java" section
  of <a
  href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'javac' /}
  {param default : '<global value>' /}
  {param desc}
  Specifies the Java compiler program to use for this rule.
  The value is a source path (e.g., //foo/bar:bar).
  Only one of "javac" and "javac_jar" may be set for a given rule.
  Overrides the value in "javac" in the "tools" section
  of <a
  href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'javac_jar' /}
  {param default : '<global value>' /}
  {param desc}
  Specifies the Java compiler program to use for this rule.
  The value is a source path (e.g., //foo/bar:bar).
  Only one of "javac_jar" and "javac" may be set for a given rule.
  Overrides the value in "javac_jar" in the "tools" section
  of <a
  href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'extra_arguments' /}
  {param default : '[]' /}
  {param desc}
  List of additional arguments to pass into the Java compiler.  These
  arguments follow the ones specified in <a
  href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'exported_deps' /}
  {param default : '[]' /}
  {param desc}
  Other <code>java_library</code> rules that depend on this rule will also
  include its <code>exported_deps</code> in their classpaths. This is useful
  when the public API of a rule has return types or checked exceptions that are
  defined in another rule, which would otherwise require callers to add an
  extra dependency. It's also useful for exposing e.g. a collection of
  {sp}<code>prebuilt_jar</code> rules as a single target for callers to depend
  on. Targets in <code>exported_deps</code> are implicitly included in the
  {sp}<code>deps</code> of this rule, so they don't need to be repeated there.
  {/param}
{/call}

{call buck.arg}
  {param name: 'provided_deps' /}
  {param default : '[]' /}
  {param desc}
  These represent dependencies that are known to be provided at run
  time, but are required in order for the code to compile. Examples of
  {sp}<code>provided_deps</code> include the JEE servlet APIs. When this
  rule is included in a <code>java_binary</code>, the
  {sp}<code>provided_deps</code> will not be packaged into the output.
  {/param}
{/call}


{call buck.visibility_arg /}

{/param} // close args

{param examples}

{literal}<pre class="prettyprint lang-py">
# A rule that compiles a single .java file.
java_library(
  name = 'JsonUtil',
  srcs = ['JsonUtil.java'],
  deps = [
    '//third_party/guava:guava',
    '//third_party/jackson:jackson',
  ],
)

# A rule that compiles all of the .java files under the directory in
# which the rule is defined using glob(). It also excludes an
# individual file that may have additional dependencies, so it is
# compiled by a separate rule.
java_library(
  name = 'messenger',
  srcs = glob(['**/*.java'], excludes = ['MessengerModule.java']),
  deps = [
    '//src/com/facebook/base:base',
    '//third_party/guava:guava',
  ],
)

java_library(
  name = 'MessengerModule',
  srcs = ['MessengerModule.java'],
  deps = [
    '//src/com/facebook/base:base',
    '//src/com/google/inject:inject',
    '//third_party/guava:guava',
    '//third_party/jsr-330:jsr-330',
  ],
)

# A rule that builds a library with both relative and
# fully-qualified deps.
java_library(
  name = 'testutil',
  srcs = glob(['tests/**/*.java'], excludes = 'tests/**/*Test.java'),
  deps = [
    ':lib-fb4a',
    '//java/com/facebook/base:base',
  ],
)
</pre>{/literal}
{/param}

{/call} // close buck.rule

    {/param}
  {/call}
{/template}