1# Introduction 2 3This document describes the `.build_config.json` files that are used by the 4Chromium build system for Android-specific targets like APK, resources, 5and more. 6 7[TOC] 8 9# I. Overview of .build_config.json files: 10 11The Android build requires performing computations about dependencies in 12various targets, which are not possible with the GN build language. To address 13this, `.build_config.json` files are written during the build to store the needed 14per-target information as JSON files. 15 16They are always written to `$target_gen_dir/${target_name}.build_config.json`. 17 18Many scripts under [`build/android/gyp/`](build/android_gyp/), which are used 19during the build, can also accept parameter arguments using 20`@FileArg references`, which look like: 21 22 --some-param=@FileArg(<filename>:<key1>:<key2>:..<keyN>) 23 24This placeholder will ensure that `<filename>` is read as a JSON file, then 25return the value at `[key1][key2]...[keyN]` for the `--some-param` option. 26 27Apart from that, the scripts do not need to know anything about the structure 28of `.build_config.json` files (but the GN rules that invoke them do and select 29which `@FileArg()` references to use). 30 31For a concrete example, consider the following GN fragment: 32 33```gn 34# From //ui/android/BUILD.gn: 35android_resources("ui_java_resources") { 36 custom_package = "org.chromium.ui" 37 resource_dirs = [ "java/res" ] 38 deps = [ 39 ":ui_strings_grd", 40 ] 41} 42``` 43 44This will end up generating the following JSON file under 45`$CHROMIUM_OUTPUT_DIR/gen/ui/android/ui_java_resources.build_config.json`: 46 47```json 48{ 49 "deps_info": { 50 "deps_configs": [ 51 "gen/ui/android/ui_strings_grd.build_config.json" 52 ], 53 "name": "ui_java_resources.build_config.json", 54 "package_name": "org.chromium.ui", 55 "path": "gen/ui/android/ui_java_resources.build_config.json", 56 "r_text": "gen/ui/android/ui_java_resources_R.txt", 57 "resources_dirs": [ 58 "../../ui/android/java/res" 59 ], 60 "resources_zip": "resource_zips/ui/android/ui_java_resources.resources.zip", 61 "srcjar": "gen/ui/android/ui_java_resources.srcjar", 62 "type": "android_resources" 63 }, 64 "gradle": {}, 65 "resources": { 66 "dependency_zips": [ 67 "resource_zips/ui/android/ui_strings_grd.resources.zip" 68 ], 69 "extra_package_names": [], 70 } 71} 72``` 73 74NOTE: All path values in `.build_config.json` files are relative to your 75`$CHROMIUM_OUTPUT_DIR`. 76 77# II. Generation of .build_config.json files: 78 79They are generated by the GN [`write_build_config()`](gn_write_build_config) 80internal template, which ends up invoking 81[`write_build_config.py`](write_build_config_py). For our example above, this 82is with the following parameters: 83 84``` 85python ../../build/android/gyp/write_build_config.py \ 86 --type=android_resources \ 87 --depfile gen/ui/android/ui_java_resources__build_config_crbug_908819.d \ 88 --deps-configs=\[\"gen/ui/android/ui_strings_grd.build_config.json\"\] \ 89 --build-config gen/ui/android/ui_java_resources.build_config.json \ 90 --resources-zip resource_zips/ui/android/ui_java_resources.resources.zip \ 91 --package-name org.chromium.ui \ 92 --r-text gen/ui/android/ui_java_resources_R.txt \ 93 --resource-dirs=\[\"../../ui/android/java/res\"\] \ 94 --srcjar gen/ui/android/ui_java_resources.srcjar 95``` 96 97Note that *most* of the content of the JSON file comes from command-line 98parameters, but not all of it. 99 100In particular, the `resources['dependency_zips']` entry was computed by 101inspecting the content of all dependencies (here, only 102`ui_string_grd.build_config.json`), and collecting their 103`deps_configs['resources_zip']` values. 104 105Because a target's `.build_config.json` file will always be generated after 106that of all of its dependencies, 107[`write_build_config.py`](write_build_config_py) can traverse the 108whole (transitive) set of direct *and* indirect dependencies for a given target 109and extract useful information out of it. 110 111This is the kind of processing that cannot be done at the GN language level, 112and is very powerful for Android builds. 113 114 115# III. Usage of .build_config.json files: 116 117In addition to being parsed by `write_build_config.py`, when they are listed 118in the `--deps-configs` of a given target, the `.build_config.json` files are used 119by other scripts under [build/android/gyp/] to build stuff. 120 121For example, the GN `android_resources` template uses it to invoke the 122[`process_resources.py`] script with the following command, in order to 123generate various related files (e.g. `ui_java_resources_R.txt`): 124 125```sh 126python ../../build/android/gyp/process_resources.py \ 127 --depfile gen/ui/android/ui_java_resources_1.d \ 128 --android-sdk-jar ../../third_party/android_sdk/public/platforms/android-29/android.jar \ 129 --aapt-path ../../third_party/android_sdk/public/build-tools/29.0.2/aapt \ 130 --dependencies-res-zips=@FileArg\(gen/ui/android/ui_java_resources.build_config.json:resources:dependency_zips\) \ 131 --extra-res-packages=@FileArg\(gen/ui/android/ui_java_resources.build_config.json:resources:extra_package_names\) \ 132 --resource-dirs=\[\"../../ui/android/java/res\"\] \ 133 --debuggable \ 134 --resource-zip-out resource_zips/ui/android/ui_java_resources.resources.zip \ 135 --r-text-out gen/ui/android/ui_java_resources_R.txt \ 136 --srcjar-out gen/ui/android/ui_java_resources.srcjar \ 137 --non-constant-id \ 138 --custom-package org.chromium.ui \ 139 --shared-resources 140``` 141 142Note the use of `@FileArg()` references here, to tell the script where to find 143the information it needs. 144 145 146# IV. Format of .build_config.json files: 147 148Thanks to `@FileArg()` references, Python build scripts under 149[`build/android/gyp/`](build/android/gyp/) do not need to know anything 150about the internal format of `.build_config.json` files. 151 152This format is decided between internal GN build rules and 153[`write_build_config.py`][write_build_config_py]. Since these changes rather 154often, the format documentation is kept inside the Python script itself, but 155can be extracted as a Markdown file and visualized with the following commands: 156 157```sh 158# Extract .build_config.json format documentation 159build/android/gyp/write_build_config.py \ 160 --generate-markdown-format-doc > /tmp/format.md 161 162# Launch a browser to visualize the format documentation. 163python tools/md_browser/md_browser.py -d /tmp /tmp/format.md 164``` 165 166[build/android/gyp/]: https://chromium.googlesource.com/chromium/src/build/+/main/android/gyp/ 167[gn_write_build_config]: https://cs.chromium.org/chromium/src/build/config/android/internal_rules.gni?q=write_build_config&sq=package:chromium 168[write_build_config_py]: https://chromium.googlesource.com/chromium/src/build/+/main/android/gyp/write_build_config.py 169