{namespace android_build_config}

/***/
{template .soyweb}
  {call buck.page}
    {param title: 'android_build_config()' /}
    {param prettify: true /}
    {param description}
      A rule that is used to generate a BuildConfig class with global
      configuration variables that android_library() rules can compile against.
    {/param}
    {param content}

{call buck.rule}
{param status: 'UNFROZEN' /}
{param overview}
An <code>android_build_config()</code> rule is used to generate
a <code>BuildConfig</code> class with global configuration variables
that other {call buck.android_library /} rules can compile against.
Currently, the only variable exposed by <code>BuildConfig</code> is
a global <code>boolean</code> named <code>DEBUG</code>, much like
the <code>BuildConfig.java</code> generated by the official Android
build tools based on Gradle.
<p>
<p>
The fields in the generated <code>BuildConfig</code> class will
be non-constant-expressions (see{sp}
<a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-15.html#jls-15.28">JLS 15.28</a>).
However, if <code>BuildConfig</code> is packaged into an APK, it will
be replaced with a new version where:
<ul>
  <li>The fields will be set to literal values (i.e., constant expressions).
  <li>The <code>boolean BuildConfig.DEBUG</code> field will correspond to
that of the <code>package_type</code> argument to the {call buck.android_binary /} rule
that is packaging it.
</ul>
This transformation is done before ProGuard is applied (if applicable), so
that it can propagate constants from <code>BuildConfig</code> and eliminate
dead code.
{/param}

{param args}

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

{call buck.arg}
  {param name: 'package' /}
  {param desc}
  Name of the Java package to use in the generated <code>BuildConfig.java</code> file.
  Most developers set this to the application id declared in the manifest
  via <code>&lt;manifest package="APP_ID"&gt;</code>.
  Example: <code>com.facebook.orca</code>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'values' /}
  {param default : '[]' /}
  {param desc}
  <p>
  List of strings that defines additional fields (and values) that should be declared in the
  generated <code>BuildConfig.java</code> file. Like <code>DEBUG</code>, the values will be
  non-constant-expressions that evaluate to the value specified in the file at compilation
  time.
  To override the values in an APK, specify <tt>build_config_values</tt>{sp}or{sp}
  <tt>build_config_values_file</tt> in {call buck.android_binary /}.
  {/param}
{/call}

{call buck.arg}
  {param name: 'values_file' /}
  {param default : 'None' /}
  {param desc}
  <p>
  Optional path to a file that defines additional fields (and values) that should be declared in the
  generated <code>BuildConfig.java</code> file. Like <code>DEBUG</code>, the values will be
  non-constant-expressions that evaluate to the value specified in the file at compilation
  time.
  To override the values in an APK, specify <tt>build_config_values</tt>{sp}or{sp}
  <tt>build_config_values_file</tt> in {call buck.android_binary /}.
  <p>
  Note that <tt>values_file</tt> can be a generated file, as can <tt>build_config_values_file</tt> as
  demonstrated in the example below.
  {/param}
{/call}

/*
Technically, the deps argument exists, but there is no use for it yet.
{call buck.arg}
  {param name : 'deps' /}
  {param default : '[]' /}
  {param desc}
{/call}
*/

{call buck.visibility_arg /}

{/param} // close args

{param examples}
<p><p>
Here is an example of an <code>android_build_config()</code> rule that
is transitively included by both <em>debug</em> and <em>release</em> versions
of an {call buck.android_binary /} rule. The value
of <code>com.example.pkg.BuildConfig.DEBUG</code> will be different in each APK
even though they both transitively depend on the same <code>:build_config</code> rule.

{literal}<pre class="prettyprint lang-py">
android_build_config(
  name = 'build_config',
  package = 'com.example.pkg',
  values = [
    'String COMMIT_ID = "0000000000000000000000000000000000000000"',
  ],
)

# The .java files in this library may contain references to the boolean
# com.example.pkg.BuildConfig.DEBUG because :build_config is in the deps.
# It could also reference BuildConfig.COMMIT_ID.
android_library(
  name = 'mylib',
  srcs = glob(['src/**&#47;*.java']),
  deps = [
    ':build_config',
  ],
)

android_binary(
  name = 'debug',
  package_type = 'DEBUG',
  keystore =  '//keystores:debug',
  manifest = 'AndroidManifest.xml',
  target = 'Google Inc.:Google APIs:19',
  deps = [
    ':mylib',
  ],
)

# The contents of the file generated by this rule might be:
#
# String COMMIT_ID = "7bf804bdf71fdbfc99cce3b155b3643f022c6fa4"
#
# Note that the output of :build_config_release_values will be cached by Buck.
# Assuming that generate_release_build_config.py depends on state that is not
# expressed by its deps (which violates a fundamental invariant in Buck!), a
# workaround is to ensure that the inputs to :build_config_release_values are
# changed in some way before :release is built to ensure that the output from
# :build_config_release_values is not pulled from cache. For example:
#
# $ buck build :release
# $ uuidgen > dummy_state_file.txt
# $ buck build :release
#
# This makes sure that generate_release_build_config.py is re-run before
# :release is rebuilt. This is much cheaper than deleting your build cache
# before rebuilding.
genrule(
  name = 'build_config_release_values',
  srcs = [ 'generate_release_build_config.py', 'dummy_state_file.txt' ],
  bash = 'generate_release_build_config.py $OUT',
  out = 'build_config_release_values.txt',
)

android_binary(
  name = 'release',
  package_type = 'RELEASE',
  keystore =  '//keystores:release',
  manifest = 'AndroidManifest.xml',
  target = 'Google Inc.:Google APIs:19',
  build_config_values_file = ':build_config_release_values',
  deps = [
    ':mylib',
  ],
)
</pre>{/literal}
{/param}

{/call} // close buck.rule

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