Software updater

  For Developers

The OLPC software has a "software update" mechanism in the Sugar Control Panel. This can install and update activities on the XO.

Features

There are two main features of the software update system.

1. Activity authors can specify an "update url" at which notifications of new versions of their activity can be found. If no update url is specified, the system falls back to the Activities page on the OLPC wiki, allowing a convenient bootstrap for existing activities with no specified "update url".
2. The software updater contains an "activity group" feature which makes it easy to install and maintain a set of activities on an XO. XO-1 machines for users and developers are subscribed to the Activities/G1G1Lite group; XO-1.5 machines with greater capacity are subscribed to the Activities/G1G1 group with a larger set of activities; machines shipped to Peru have shipped with the activities listed on the Activities/Peru group page, and so forth.

You do not need to be subscribed to an activity group to get updates for your installed activities.

For activity authors

Using the activity update mechanism is intended to be as simple as possible. If you like, you need make no updates to your activity at all; just keep the Activities page updated with the most recent version of your activity. If your activity is included in the G1G1, Joyride or Peru groups, keep those pages updated as well. (An planned improvement to our template system will eventually keep these pages automatically in sync, but for the moment you should check each page for consistency.)

After 8.2 is released and we start working on the next build, we will freeze the set of activities known to work well on 8.2 at Activities/G1G1/8.2. If you then released a new version of your activity which is backwards compatible with 8.2, you should update the Activities/G1G1/8.2 page as well. (Again, our new templates will eventually do this automatically.)

The main advantage of this system is its simplicity: anyone can upload an activity bundle to our wiki and update the activities information there; no special web hosting ability is required. This is, however, also its main disadvantage: *anyone* can update an activity bundle there. If you want a little more control over who can release new versions of your activity, you can specify an update_url in the activity.info file in your activity. By pointing the update_url at a web site you control, you can ensure that only you can publish new versions of your activity.

Consult the documentation on the activity bundles page for more information about the update_url field, and the activity microformat page for descriptions and an example of the information which should be present at the page pointed to by update_url. The format has been designed to be easily embeddable into an existing web page or blog for your activity.

If the version for an activity in the update URL is smaller than the activity version installed on the XO, Software updater will not "downgrade" the installed activity.

Activity groups

You can edit the set of activity groups you are subscribed to using "software update" in the Sugar Control Panel. The same activity microformat is used for specifying activity groups. It's easy for motivated individuals to create and share their own activity groups; we list all the ones we know about on the activity groups page.

Lists of subscribed activity groups are kept in a simple one-line-per-url file format. The update control panel first looks for a group list in ~olpc/Activities/.groups (which will be preserved across upgrades, since it is in the user's home directory). If this file is not present, the group list in /etc/olpc-update/activity-groups is used. This allows the joyride builds, for example, to default to the Activities/Joyride activity group.

If the /etc/olpc-update/activity-groups file does not exist, the system performs a special test to determine if we are upgrading from an old release where activities were installed as part of the core OS, by looking to see if an activity with bundle_id 'org.laptop.WebActivity' is installed. If it is not, it guesses that the user would be left with the "no activities" bug after this upgrade (<trac>7093</trac>), and adds the G1G1 group to work around this.

The group URL uses the same "url extension" mechanism documented for the update_url field on the activity bundles page. That is, if the group URL is http://wiki.laptop.org/go/Activities/G1G1, the updater (running on "build 802" of an 8.2.1 release) will look for the following URLs in order:

• http://wiki.laptop.org/go/Activities/G1G1/802
• http://wiki.laptop.org/go/Activities/G1G1/8.2.1 Note: Software update in 8.2.1 does not look for this "dot-dot" version of update URLs, see <trac>9317</trac>
• http://wiki.laptop.org/go/Activities/G1G1/8.2
• http://wiki.laptop.org/go/Activities/G1G1

using the info from the first URL that it successfully retrieves and that appears to have valid microformat information. Unfortunately Software Update does not indicate which of these URLs it uses (<trac>10321</trac>).

This allows you to provide different versions of the activity group if some of your activities are not compatible with older (or newer) releases. Generally:

• the unsuffixed version of the group URL will always contain the latest versions of the activities for the very latest build (possibly an unstable "Joyride" build)
• as releases happen and work begins on the next release, a copy of the unsuffixed page will be "frozen" with an appropriate suffix for that release, and only updated if and when a newer version of an activity is compatible with that release.

On the server side

The urls in the group files point to html-pages. These pages are expected to contain info on one or more activities in a specific form, as per the output of this pyton function:

def makeItemString(actId, actVer, actUrl, actName):
    return """
      <br/>
      <span class="olpc-activity-info">
          <span class="olpc-activity-id" style="display:none;">%s</span>
          <span class="olpc-activity-version" style="display:none;">%s</span>
          <span class="olpc-activity-url"><a href='%s'>%s</a></span>
      </span>
    """ % (actId, actVer, actUrl, actName)

It doesn't matter how, or where on the page you put this. You can happily intermingle it with other html code. Of course make sure the link in the olpc-activity-url span is valid.

At OLE Nepal we automatically generate a page from the activities in a certain folder on a schoolserver, with the help of a cron-job; which is a wrapper for a python script. Change the htmlName and the bundleBaseUrl variables in the python script to customize your setup.

For deployments

In a deployment scenario, you would create an appropriate group file (ie, http://wiki.laptop.org/go/Activities/Peru, or a group file living on our School server at a URL like http://schoolserver/my-deployment/group) by creating a .xo bundle that installs /home/olpc/Activities/.groups pointing at the appropriate location. You would then install that .xo bundle from your customization key. The group file would like all the activities you plan to have installed on XOs in your deployment. Pre-seeded web content on the school server should serve the group file URL as well as the updated activity bundles (possibly including the update-url pages referenced by the activity bundles).

Support will be added to the updater in the future to add deployments to pin activities at a given version (overriding suggestions in the activities update-url) and provide hints to ensure specific activities are uninstalled.

Debugging the updater

Logs from crashes will be recorded in ~olpc/.sugar/default/logs/shell.log, and sometimes in ~olpc/.sugar/default/logs/shellservice.log.

You can often get better debugging or crash information by invoking the updater from the command line. Open the terminal activity, and type:

$ sugar-control-panel -l

This will list the keys available in the control panel; in particular look for the keys listed under the 'updater' module. To see what updates are available:

$ sugar-control-panel -g available_updates

To install all available updates

$ sugar-control-panel -s install_update all

To install an update for a particular activity (say, Firefox):

$ sugar-control-panel -s install_update Firefox

A common problem is multiple passes through the installer. This is caused by an older version of the activity being listed in a subscribed update group, while a newer version is available from the activity's update_url (which may be http://wiki.laptop.org/go/Activities, the default) once the older version of the activity has been installed. These bugs should be filed against the maintainer of the activity.

Another common problem is upgrades that "never complete": even after you click 'Install', the activity always shows up as needing an upgrade. This is typically caused by a problem installing the activity; the command-line mechanism described above will usually yield more information about what exactly failed. File bugs against the activity, for MalformedBundleExceptions of various types, or sugar (for problems that occur despite a correct activity bundle).