• View
• Edit
• History
• Print

PublishingAnUpdate

So you're ready to release a new version of your app. How do you go about doing that?

• Archive your app. Either:
  • Put a copy of your .app (with the same name as the version it's replacing) in a .zip, .dmg, .tar.gz, or .tar.bz2.
  • Create an Installer .pkg with the same name as your app and put that .pkg in one of the archive formats above.
• Sign your update (unless you're hosting your update over SSL):
  • Sparkle includes a script to help you sign your update.
  • (from the Sparkle distribution root):
  • ruby "Extras/Signing Tools/sign_update.rb" \
path_to_your_update.zip path_to_your_dsa_priv.pem
  • The string outputted is your update's DSA signature; you'll add this as an attribute to your enclosure in the next step.
• Update your appcast:
  • You need to create an <item> for your update in your appcast. See the sample appcast for an example.
  • Here's a template you might use:
    

    <item>
        <title>Version 2.0 (2 bugs fixed; 3 new features)</title>
        <sparkle:releaseNotesLink>
            http://you.com/app/2.0.html
        </sparkle:releaseNotesLink>
        <pubDate>Wed, 09 Jan 2006 19:20:11 +0000</pubDate>
        <enclosure url="http://you.com/app/Your Great App 2.0.zip"
                   sparkle:version="2.0"
                   sparkle:dsaSignature="MC0CFBfeCa1JyW30nbkBwainOzrN6EQuAh="
                   length="1623481"
                   type="application/octet-stream" />
    </item>

• Test your update
  • And you're done!

Internal build numbers

If you use internal build numbers for your CFBundleVersion key (like an SVN revision number) and a human-readable CFBundleShortVersionString, you can make Sparkle hide the internal version from your users.

Set the sparkle:version attribute on your <enclosure> to the internal version (ie: "248"). Then set a sparkle:shortVersionString attribute on the <enclosure> to the human readable version (ie: "2.0").

Remember that the internal version number (CFBundleVersion and sparkle:version) must consist of numbers and periods only. This is expected by Mac OSX, as well as Sparkle.

Minimum system version requirements

If an update to your application raises the required version of Mac OS X, you can only offer that update to qualified users.

Add a sparkle:minimumSystemVersion child to the <item> in question specifying the required system version, such as "10.4.5":

<item>
    <title>Version 2.0 (2 bugs fixed; 3 new features)</title>
    <sparkle:minimumSystemVersion>10.5.5</sparkle:minimumSystemVersion>
    [...]
</item>

Embedded release notes

Instead of linking external release notes using the <sparkle:releaseNotesLink> element, you can also embed the release notes directly in the appcast item, inside a <description> element. If you wrap it in <![CDATA[ ... ]]>, you can use unescaped HTML.

<item>
    <title>Version 2.0 (2 bugs fixed; 3 new features)</title>
    <description><![CDATA[
<h2>New Features</h2>
[...]
    ]]></description>
    [...]
</item>

Xcode integration

Here’s a description of how to automate the archiving and signing process with a script build phase in Xcode.

Using DMGs

If you're using a DMG, note that sparkle:dsaSignature should be generated from the DMG file, but the length attribute in the enclosure should represent the .app bundle size, not the DMG size.