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