PageRenderTime 17ms CodeModel.GetById 11ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 1ms

/core/externals/update-engine/Samples/HelloEngine/README.html

http://macfuse.googlecode.com/
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 &gt; New &gt; 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  &lt;array&gt;
181    &lt;dict&gt;
182      &lt;key&gt;ProductID&lt;/key&gt;
183      &lt;string&gt;com.google.HelloEngineTest&lt;/string&gt;
184      &lt;key&gt;Predicate&lt;/key&gt;
185      &lt;string&gt;Ticket.version != '2.0'&lt;/string&gt;
186      &lt;key&gt;Codebase&lt;/key&gt;
187      &lt;string&gt;file:///tmp/TestApp.dmg&lt;/string&gt;
188<font color="black">
189      &lt;key&gt;Size&lt;/key&gt;
190      &lt;string&gt;<b>50405</b>&lt;/string&gt;
191      &lt;key&gt;Hash&lt;/key&gt;
192      &lt;string&gt;<b>BnKj+Bpy4KspQ4qzlkRn6EIaJ4g=</b>&lt;/string&gt;
193</font>
194    &lt;/dict&gt;
195  &lt;/array&gt;
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>