1 <html devsite> 2 <head> 3 <title>OTA Package Tools</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>The <a 27 href="https://android.googlesource.com/platform/build/+/master/tools/releasetools/ota_from_target_files">ota_from_target_files</a> 28 tool provided in <code>build/tools/releasetools</code> can build two types of 29 package: <i>full </i> and <i>incremental</i>. The tool takes the 30 <i>target-files</i> .zip file produced by the Android build system as 31 input.</p> 32 33 <h2 id="full-updates">Full updates</h2> 34 <p>A <i>full</i> update is one where the entire final state of the device 35 (system, boot, and recovery partitions) is contained in the package. As long 36 as the device is capable of receiving the package and booting the recovery 37 system, the package can install the desired build regardless of the current 38 state of the device.</p> 39 <p>Example: Using the release tools to build a full update for the 40 hypothetical <b>tardis</b> device:</p> 41 42 <pre class="devsite-click-to-copy"> 43 # first, build the target-files .zip 44 <code class="devsite-terminal">. build/envsetup.sh && lunch tardis-eng</code> 45 <code class="devsite-terminal">mkdir dist_output</code> 46 <code class="devsite-terminal">make dist DIST_DIR=dist_output</code> 47 </pre> 48 49 <p>The target-files .zip contains everything needed to construct OTA packages. 50 </p> 51 52 <pre class="devsite-click-to-copy"> 53 <code class="devsite-terminal">./build/tools/releasetools/ota_from_target_files dist_output/tardis-target_files.zip ota_update.zip</code> 54 </pre> 55 56 <p>The ota_update.zip is now ready to be sent to test devices (everything is 57 signed with the test key). For user devices, generate and use your own private 58 keys as detailed in <a href="/devices/tech/ota/sign_builds.html">Signing builds 59 for release</a>. 60 61 <h2 id="incremental-updates">Incremental updates</h2> 62 <p>An <i>incremental</i> update contains a set of binary patches to be applied 63 to the data already on the device. This can result in considerably smaller 64 update packages:</p> 65 <ul> 66 <li>Files that have not changed don't need to be included.</li> 67 <li>Files that have changed are often very similar to their previous versions, 68 so the package need only contain an encoding of the differences between the 69 two files.</li></ul> 70 <p>You can install the incremental update package only on a device that has 71 the old or source build used when constructing the package. To build an 72 incremental update, you need the target_files .zip from the previous build 73 (the one you want to update <i>from</i>) as well as the target_files .zip from 74 the new build.</p> 75 76 <pre class="devsite-click-to-copy"> 77 <code class="devsite-terminal">./build/tools/releasetools/ota_from_target_files -i PREVIOUS-tardis-target_files.zip dist_output/tardis-target_files.zip incremental_ota_update.zip # make incremental from the older version</code> 78 </pre> 79 80 <p>This build is very similar to the previous build, and the incremental 81 update package is much smaller than the corresponding full update (about 1 MB 82 instead of 60 MB).</p> 83 <p class="note"><strong>Note:</strong> To generate a 84 <a href="/devices/tech/ota/block.html">block-based OTA</a> 85 for subsequent updates, pass the <code>--block</code> option to 86 <code>ota_from_target_files</code>.</p> 87 <p>Distribute an incremental package only to devices running exactly the same 88 previous build used as the incremental package's starting point. Attempting to 89 install the incremental package on a device with some other build results in 90 the recovery error icon. Rebooting the device at this point returns the user 91 to the old system; the package verifies the previous state of all the files it 92 updates before touching them, so the device should not be left in a half 93 upgraded state if this occurs.</p> 94 95 <h2 id="update-packages">Update packages</h2> 96 <p>An update package (<code>ota_update.zip</code>, 97 <code>incremental_ota_update.zip</code>) is a .zip file that contains the 98 executable binary <code>META-INF/com/google/android/update-binary</code>. After 99 verifying the signature on the package, recovery extracts this binary to 100 <code>/tmp</code> and runs it, passing the following arguments:</p> 101 <ul> 102 <li><b>Update binary API version number</b>. If the arguments passed to the 103 update binary change, this number is incremented.</li> 104 <li><b>File descriptor of the <i>command pipe</i></b>. The update program can 105 use this pipe to send commands back to the recovery binary (mostly for UI 106 changes such as indicating progress to the user).</li> 107 <li><b>Filename of the update package .zip file</b>.</li> 108 </ul> 109 <p>A recovery package can use any statically-linked binary as the update 110 binary. The OTA package construction tools use the updater program (source in 111 <code>bootable/recovery/updater</code>), which provides a simple scripting 112 language that can do many installation tasks. You can substitute any other 113 binary running on the device.</p> 114 <p>For details on the updater binary, edify syntax, and builtin functions, see 115 <a href="/devices/tech/ota/inside_packages.html">Inside OTA Packages</a>. 116 </body> 117 </html> 118
