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

Latest revision as of 22:05, 26 April 2012

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 before running make -f client.mk:

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

XXX will setting them in the mozconfig work?

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

In addition, you must replace the Camino Project DSA public key with your DSA public key. Before beginning your build, copy your DSA public key to resources/application/camino_dsa_pub.pem. 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>

@@ Line 1: / Line 1: @@
 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 <code>sparkle/generate_keys.rb</code> script (see [http://wiki.github.com/andymatuschak/Sparkle/ 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 (<code>dsa_'''pub'''.pem</code>) 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:
+To build Camino with software update enabled, you must configure your build to export certain variables '''before''' running <code>make -f client.mk</code>:
 * <code>APP_UPDATE_URL = https://yourserver.tld/path_to_appcast</code>
 * <code>APP_UPDATES_ENABLED = true</code>
+'''XXX will setting them in the mozconfig work?'''
 While an https: URL is preferred, http: URLs will work, too.
-In addition, you currently must manually paste your DSA public key into the <code>Camino.app/Contents/Info.plist</code>, replacing the existing value for the <code>SUPublicDSAKey</code> 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.)  To generate a key, run the provided <code>sparkle/generate_keys.rb</code> script (see [http://wiki.github.com/andymatuschak/Sparkle/ the Sparkle documentation] for more on keys and signing).  Be sure to do this to the universal Camino before packaging (before running <code>make -C camino/installer</code>).
+In addition, you must replace the Camino Project DSA public key with your DSA public key.  Before beginning your build, copy your DSA public key to <code>resources/application/camino_dsa_pub.pem</code>. <!--Be sure to replace the Camino Project key with your own key in the universal Camino (<code>$OBJDIR/$arch/universal/camino/Camino.app</code>) before packaging (before running <code>make -C camino/installer</code>).-->  '''WARNING: Flying monkeys will h4xx0r your users’ Macs if you make the private key public,''' so be sure to use the public key (<code>dsa_pub.pem</code>), not your private key.
 Once the build is complete and your disk image is created (in <code>$objdir/$arch/dist</code> for the <code>$objdir/$arch</code> where you ran <code>make -C camino/installer</code>), you will need to sign the disk image.  Run the provided <code>sparkle/sign_update.rb</code> script, which will output a hash that your appcast requires.
@@ Line 16: / Line 24: @@
 ==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).
+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 <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.
-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.
+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.
-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).
+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.
-===Sample Update Definition file===
+When creating a new release, you should update the <code><nowiki><item></nowiki></code> portion of your appcast for your release.
-''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).''
-<pre>Version = 2010.02.16
-VersionString = 2.0.2
-MinOSVersion = 10.4
-Arch = ppc,x86
-Intl = 0
-FileURL = http://download.mozilla.org/?product=camino-2.0.2&os=osx&lang=en-US
-FileSignature = MCwCFBHRB1s6R0jwf3V2P3lk0zh2B3OrAhQoKkN9upF3le9zQZrKTp1v8ZqhrQ==
-FileSize = 16527557
-Date = Tue, 23 Feb 2010 13:00:00 GMT-8</pre>
-===Sample Update Description 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 English update description for Camino 2.0.2 (this file can be localized).''
+* Update the the <code><nowiki><description></nowiki></code> as you see fit, remembering to escape any entities.
-<pre><p>Camino 2.0.2 is a security and stability update for Camino 2.0.x. All users are urged to upgrade.</p>
+* Update the <code><nowiki><enclosure></nowiki></code> to match the new build, remembering to escape any entities.
-<p>For details, see the <a href="http://caminobrowser.org/releases/2.0.2/">release notes</a>.</p></pre>
+** <code>url</code> should contain the URL to your download (be sure to escape any literal ampersands in the URL).
+** <code>length</code> is the size, in bytes, of your disk image.
+** <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.
+** <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.
+** <code>sparkle:dsaSignature</code> is the update hash, the output of the <code>sparkle/sign_update.rb</code> script above.
 ===Sample Appcast===

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

Latest revision as of 22:05, 26 April 2012

Contents

Generating a DSA Key for Updates

Application and Build Configuration

Server Configuration

Sample Appcast

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools