Difference between revisions of "Development:Providing Software Update for Third-Party Camino Builds"

From Camino Wiki
Jump to navigation Jump to search
(→‎Application and Build Configuration: add key section first, per stuart)
(→‎Server Configuration: just explain an appcast; it's much simpler)
Line 22: Line 22:
 
==Server Configuration==
 
==Server Configuration==
  
Configure your server to provide a Camino appcast.  The easiest way to do this is to use the Camino Project’s own appcast script (<code>tools/autoupdate/update-check</code>) on your own server, though this requires your server to support perl and cgi scripts.  As an alternative, you can provide a static appcast file that conforms to the output format of the Camino Project’s appcast script (if you use a static appcast, it should be served with an xml content-type; often the easiest way to do this is to give the file an <code>.xml</code> extension).
+
Configure your server to provide a Camino appcast.  The easiest way to do this is to provide a static appcast file that conforms to the output format of the Camino Project’s appcast script.  This appcast should be served with an xml content-type; often the easiest way to do this is to give the file an <code>.xml</code> extension.
  
If you use the Camino Project’s appcast script, you will also need to provide update definition and update description files.  Be sure to escape any entities in the update description/HTML portion of the appcast.
+
Note: If you are releasing multiple series of builds (for example, branch releases and trunk milestones), you should configure each branch with a separate appcast URL when building.
  
If you use the Camino Project’s appcast script, you should change the script to output the correct values for the <code><nowiki><link></nowiki></code> and <code><nowiki><author></nowiki></code> elements.
+
You should customize the <code><nowiki><channel></nowiki></code> portion of your appcast, as well as the <code><nowiki><author></nowiki></code> element in the <code><nowiki><item></nowiki></code> portion, to reflect your own build series and site.
  
When creating a new release, you should update the <code>Version</code>, <code>VersionString</code>, <code>FileURL</code>, <code>FileSignature</code> (the output of the <code>sparkle/sign_update.rb</code> script above), and <code>FileSize</code> (in bytes) values in the update definition file (or your static appcast file).
+
When creating a new release, you should update the <code><nowiki><item></nowiki></code> portion of your appcast for your release.
  
===Sample Update Definition file===
+
* Change the <code><nowiki><title></nowiki></code> to include the new version number and update the <code><nowiki><pubDate></nowiki></code>.
''This is the update definition for the Camino 2.0.2 English-only build (separates file are necessary if you have separate English and Multilingual builds).''
+
* Update the the <code><nowiki><description></nowiki></code> as you see fit, remembering to escape any entities.
<pre>Version = 2010.02.16
+
* Update the <code><nowiki><enclosure></nowiki></code> to match the new build, remembering to escape any entities.
VersionString = 2.0.2
+
** <code>url</code> should contain the URL to your download (be sure to escape any literal ampersands in the URL).
MinOSVersion = 10.4
+
** <code>length</code> is the size, in bytes, of your disk image.
Arch = ppc,x86
+
** <code>sparkle:version</code> is the <code>CFBundleVersion</code> of your build; this can be found in the <code>Info.plist</code> of your final Camino binary.
Intl = 0
+
** <code>sparkle:shortVersionString</code> is the <code>CFBundleShortVersionString</code> of your build; this, too, can be found in the <code>Info.plist</code> of your final Camino binary.
FileURL = http://download.mozilla.org/?product=camino-2.0.2&os=osx&lang=en-US
+
** <code>sparkle:dsaSignature</code> is the update hash, the output of the <code>sparkle/sign_update.rb</code> script above.
FileSignature = MCwCFBHRB1s6R0jwf3V2P3lk0zh2B3OrAhQoKkN9upF3le9zQZrKTp1v8ZqhrQ==
 
FileSize = 16527557
 
Date = Tue, 23 Feb 2010 13:00:00 GMT-8</pre>
 
 
 
===Sample Update Description file===
 
''This is the English update description for Camino 2.0.2 (this file can be localized).''
 
<pre><p>Camino 2.0.2 is a security and stability update for Camino 2.0.x. All users are urged to upgrade.</p>
 
<p>For details, see the <a href="http://caminobrowser.org/releases/2.0.2/">release notes</a>.</p></pre>
 
  
 
===Sample Appcast===
 
===Sample Appcast===

Revision as of 17:26, 12 April 2010

Camino only enables software updates for official builds produced by Camino tinderboxen and disables parts of the application’s software update infrastructure at build time in other builds. If you are a third-party builder, or a Camino developer managing a long-lived series of experimental builds, these instructions will help you enable software update in your builds.

Generating a DSA Key for Updates

You will need a key to sign your updates and generate a hash to include in your appcast. To generate a key, run the provided sparkle/generate_keys.rb script (see the Sparkle documentation for more on keys and signing).

WARNING: flying monkeys will h4xx0r your users boxen if you make the private key public.

Application and Build Configuration

To build Camino with software update enabled, you must configure your build to export certain variables:

While an https: URL is preferred, http: URLs will work, too.

In addition, you currently must manually paste your DSA public key into the Camino.app/Contents/Info.plist, replacing the existing value for the SUPublicDSAKey key. (In the future, we plan to move the key to a separate file inside the bundle, allowing you to simply replace the Camino Project key with your own key file.) Be sure to replace the Camino Project key with your own key in the universal Camino before packaging (before running make -C camino/installer). WARNING: flying monkeys will h4xx0r your users boxen if you make the private key public, so be sure to use the public key (dsa_pub.pem</code), not your private key.

Once the build is complete and your disk image is created (in $objdir/$arch/dist for the $objdir/$arch where you ran make -C camino/installer), you will need to sign the disk image. Run the provided sparkle/sign_update.rb script, which will output a hash that your appcast requires.

Server Configuration

Configure your server to provide a Camino appcast. The easiest way to do this is to provide a static appcast file that conforms to the output format of the Camino Project’s appcast script. This appcast should be served with an xml content-type; often the easiest way to do this is to give the file an .xml extension.

Note: If you are releasing multiple series of builds (for example, branch releases and trunk milestones), you should configure each branch with a separate appcast URL when building.

You should customize the <channel> portion of your appcast, as well as the <author> element in the <item> portion, to reflect your own build series and site.

When creating a new release, you should update the <item> portion of your appcast for your release.

  • Change the <title> to include the new version number and update the <pubDate>.
  • Update the the <description> as you see fit, remembering to escape any entities.
  • Update the <enclosure> to match the new build, remembering to escape any entities.
    • url should contain the URL to your download (be sure to escape any literal ampersands in the URL).
    • length is the size, in bytes, of your disk image.
    • sparkle:version is the CFBundleVersion of your build; this can be found in the Info.plist of your final Camino binary.
    • sparkle:shortVersionString is the CFBundleShortVersionString of your build; this, too, can be found in the Info.plist of your final Camino binary.
    • sparkle:dsaSignature is the update hash, the output of the sparkle/sign_update.rb script above.

Sample Appcast

This is the output of the Camino Project’s appcast script for an English-only Camino 2.0.1 build running on Mac OS X 10.5.8 on an Intel Mac.

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
  <channel>
    <title>Camino Updates</title>
    <link>http://caminobrowser.org</link>
    <description>Camino Updates</description>
    <language>en</language>
    <item>

      <title>Camino 2.0.2</title>
      <pubDate>Tue, 23 Feb 2010 13:00:00 GMT-8</pubDate>
      <author>The Camino Project</author>
      <description><![CDATA[
        <p>Camino 2.0.2 is a security and stability update for Camino 2.0.x. All users are urged to upgrade.</p>
<p>For details, see the <a href="http://caminobrowser.org/releases/2.0.2/">release notes</a>.</p>

      ]]></description>
      <link>http://caminobrowser.org</link>
      <enclosure url="http://download.mozilla.org/?product=camino-2.0.2&os=osx&lang=en-US" length="16527557" sparkle:version="2010.02.16" sparkle:shortVersionString="2.0.2" sparkle:dsaSignature="MCwCFBHRB1s6R0jwf3V2P3lk0zh2B3OrAhQoKkN9upF3le9zQZrKTp1v8ZqhrQ==" type="application/octet-stream"/>
    </item>

  </channel>
</rss>