| {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><manifest package="APP_ID"></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/**/*.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} |