/core/externals/update-engine/Samples/HelloEngine/README.html
HTML | 256 lines | 188 code | 68 blank | 0 comment | 0 complexity | 4a4721f4d109d70b2a5cb2775f62d96e MD5 | raw file
1<html> 2 3<head> 4 <title>Welcome to HelloEngine</title> 5</head> 6 7<body bgcolor="white"> 8 9<h1>Welcome to HelloEngine</h1> 10 11Welcome to HelloEngine, a minimal, but functional, Update Engine 12program. <tt>HelloEngine.m</tt> has some comments about how Update 13Engine works. This file has instructions on how to run the sample, 14and to get your own Stuff into Update Engine's pipeline. 15 16<p> 17 18Here's how to run things: 19<ul> 20 <li> Copy <tt>Samples/HelloEngine/TestApp.dmg</tt> to <tt>/tmp</tt> 21 <li> Copy <tt>Samples/HelloEngine/ServerResponse.plist</tt> to <tt>/tmp</tt> 22 <li> Build HelloEngine 23 <li> Run HelloEngine:<br> 24<pre>HelloEngine -productID com.google.HelloEngineTest -version 1.2 -serverURL file:///tmp/ServerResponse.plist</pre> 25 <li> Note new file, <tt>/tmp/HiEngine.sh</tt>, which has been "updated". 26Run that for a little message of greetings. 27<pre> 28 29</pre> 30</ul> 31 32<p> 33 34You'll see a lot of output. This is Update Engine letting you know 35what's going on, and can be useful when debugging things. It also 36looks cool. 37 38<p> 39 40The very last line of the output will look something like: 41<pre> 422008-09-12 11:51:01.933 HelloEngine[7055/0x0b0e] [lvl=2] main Update Succeeded 43</pre> 44 45<p> 46 47 48The last word from HelloEngine will be "Succeeded" or "Failed". If it 49Succeeded, try running <tt>/tmp/HiEngine.sh</tt> 50 51 52 53<h1>Getting HelloEngine to run your own stuff</h1> 54 55There are a couple of steps to get HelloEngine to run your stuff: 56<ul> 57 <li> Edit the <tt>.engine_install</tt> script 58 <li> Build your disk image 59 <li> Calculate hash and file size 60 <li> Edit your <tt>ServerResponse.plist</tt> 61</ul> 62 63 64<h2>.engine_install</h2> 65 66First you'll need to edit the install script, which you can find at 67<tt>Samples/HelloEngine/TestAppDMGSource/.engine_install</tt>. This script 68is what does the heavy lifting of updating your product. 69 70<p> 71 72<tt>.engine_install</tt> is required for Update Engine to function 73properly. You can also create <tt>.engine_preinstall</tt> and 74<tt>.engine_postinstall</tt> scripts to do preflight and postflight 75work. Outside of these scripts, Update Engine doesn't care what you 76have on the disk image. 77 78<p> 79 80The standard-out of the preinstall script gets added to the 81environment of the install and postinstall scripts under the 82environment variable <tt>KS_PREINSTALL_OUT</tt>. Likewise, the 83standard-out of the install script gets added to the environment of 84the postinstall script under the environment variable 85<tt>KS_INSTALL_OUT</tt>. This way you can pass information from one 86script phase to the next. 87 88<p> 89 90The scripts can be written in any language you want, but you'll want to 91stick to the languages (and language versions) that exist on your 92user's machines - they probably don't want to download and install the 93Object Fortran++ Scripting Bridge so that you can update your 94software. Likewise, if you're using Python, don't use any Python 2.5 95features if you intend to update users on Tiger, who only have python 2.3. 96 97<p> 98 99<tt>.engine_install</tt> and the others don't even have to be a 100script, they can be compiled C programs if that makes sense for what 101you need to do. 102 103<p> 104 105The first argument of the script is the directory to the mount point 106of the disk image that Update Engine downloads. Be aware that this 107path can contain spaces, so do whatever string-space-quoting hygiene 108is necessary for your language of choice. 109 110<p> 111 112Inside of the script, you're welcome to do whatever you want, assuming 113it can be done as the user ID that the HelloEngine tool is run as. If 114you run it as root, then you can do most anything, please don't delete 115the user's <tt>/Application</tt> directory. 116 117 118<h2>Build your Disk Image</h2> 119 120Once you've written your script, you'll need to build your disk image. 121The easy way to do this is to drop all your stuff into a directory and 122use Disk Utility to create the disk image. The command to do so is 123hidden under <i>File > New > New Disk Image From Folder</i>. 124Choose the <tt>TestAppDMGSource</tt> folder, or whatever folder you're using for 125your product update, and make sure you're making a compressed, 126unencrypted disk image. 127 128<p> 129 130Here's a command for doing the same thing that's easier to put into an 131Xcode project: 132<pre> 133hdiutil create -ov -imagekey zlib-level=9 -fs HFS+ -format UDZO -scrub 134-srcfolder $DIR $DISKIMAGENAME 135</pre> 136 137<p> 138 139In a real-world application, this can (and should) be the disk image 140that you give your users. This saves you from having to build, test, 141and deploy two different payloads for your product. The reason 142the scripts have the leading dot is so that they won't interfere with 143the Finder's presentation of the disk image when it's mounted by the user. 144 145<h2>Caculate Hash and File Size</h2> 146 147Once you have the disk image, you'll need to calculate a checksum, and 148put the checksum and size into the <tt>ServerResponse.plist</tt> file. 149 150<p> 151 152First, calculate the checksum: 153<pre> 154$ openssl sha1 -binary TestApp.dmg | openssl base64 155</pre> 156 157This will output something like 158<pre> 159BnKj+Bpy4KspQ4qzlkRn6EIaJ4g= 160</pre> 161 162After you figure out how to pronounce that, you'll need to figure out 163how big the file is: 164 165<pre> 166$ ls -l TestApp.dmg 167-rw-r--r-- 1 bork bork 50405 Sep 11 18:29 TestApp.dmg 168</pre 169 170So it's 50405 bytes. 171 172<h2>Edit your ServerResponse.plist</h2> 173 174Edit the ServerResponse.plist and plug the values into the Size and 175Hash settings: 176 177<pre> 178<font color="gray"> 179... 180 <array> 181 <dict> 182 <key>ProductID</key> 183 <string>com.google.HelloEngineTest</string> 184 <key>Predicate</key> 185 <string>Ticket.version != '2.0'</string> 186 <key>Codebase</key> 187 <string>file:///tmp/TestApp.dmg</string> 188<font color="black"> 189 <key>Size</key> 190 <string><b>50405</b></string> 191 <key>Hash</key> 192 <string><b>BnKj+Bpy4KspQ4qzlkRn6EIaJ4g=</b></string> 193</font> 194 </dict> 195 </array> 196... 197</font> 198</pre> 199 200In a real development environment, you'll probably want an Xcode 201script build phase to do this automatically for you. 202 203<p> 204 205Now you can use your <tt>ServerResponse.plist</tt> and your 206<tt>TestApp.dmg</tt> with HelloEngine to get your stuff run. 207 208 209<h1>What can go wrong</h1> 210 211There are some moving pieces involved, and some things that might go wrong 212as you get things working. Here are some common ones: 213 214<ul> 215 216 <li> Forgot to replace <tt>/tmp/TestApp.dmg</tt> 217 <li> Forgot to copy <tt>ServerResponse.plist</tt> to <tt>/tmp</tt> 218 <li> Bad hash or bad size when you change the payload<br> 219</ul> 220 221These result in <tt>ServerResponse.plist</tt> having a size and/or hash that's 222out of sync with the TestApp.dmg file. Update Engine will reject any paylod 223that doesn't match the size and hash. 224 225<ul> 226 <li> Your <tt>.engine_install</tt> is not <tt>+x</tt> 227</ul> 228 229Make sure that your .engine_install file has the executable bit, set with 230<tt>chmod +x .engine_install</tt> 231 232<ul> 233 <li> Making assumptions about the current working directory 234</ul> 235 236The current working directory for your script is undefined, and will 237probably be the directory where you are running the HelloEngine 238command from. This can confuse your testing if you run HelloEngine 239with your current working directory being that of your 240TestAppDMGSource directory. The script will work fine when you run 241the install script by hand, but will fail when Update Engine is doing 242its thing. 243 244<p> 245 246Make sure you get the path to your mounted disk from the 247first argument to the script, and make sure that you account for the 248the fact that it might contain spaces. Even if your disk image name 249doesn't contain spaces, the system might mount it at 250<tt>"/Volumes/Payload 1"</tt> if <tt>/Volumes/Payload</tt> is already 251in use. 252 253</ul> 254 255</body> 256</html>