Development:Providing Software Update for Third-Party Camino Builds

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 DSA key to sign your updates and generate a hash to include in your appcast. To create a key for your updates, 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’ Macs if you make the private key public. Guard the keys with your life, and never mistake the public key (dsa_pub.pem) for the private one (which has no pub in its filename).

Application and Build Configuration

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

• APP_UPDATE_URL = https://yourserver.tld/path_to_appcast
• APP_UPDATES_ENABLED = true

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

Until Bug 558966 is fixed, you must edit camino/Makefile.in and change this variable declaration to APP_UPDATES_ENABLED ?= false before beginning your build.

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, once Bug 558966 is fixed, the key will move 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’ Macs if you make the private key public, so be sure to use the public key (dsa_pub.pem), 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

You must 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>