blob: 453b04656a8ff2b0452484278e9fb12b18c30a33 [file] [log] [blame]
/*
* Copyright (c) Facebook, Inc. and its affiliates.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
{namespace android_build_config}
/***/
{template .soyweb}
{call buck.page}
{param title: 'android_build_config()' /}
{param navid: 'rule_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.name_arg /}
{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}
*/
{/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}