Luau:
Automatically Update Programs And Libraries.
Power And Flexibility Through Decentralized Control
 
 

Luau Developer's Overview: A Crash-Course Guide to Supporting Luau in Your Application

This document will give you a quick, five-step introduction to supporting Luau in your application. It is not meant as an exhaustive reference: for that, please see the Luau Whitepaper. Here we will go over the general principles involved in utilizing the Luau framework; you should refer to the whitepaper for a complete guide to all the Luau repository XML tags and the ins and outs of the programs distributed with Luau.

If you have not already, you may want to first read the more general Introduction to Luau. It will give you a an overview of what exactly Luau is and how it works. Here we'll just show you how to set it up for your project.

Overview

The heart of Luau is the "Luau repository file." This is an XML file which describes all the currently available software releases for your project and any messages you may want to disseminate to your user base. What you as a developer has to do is:

  1. Write the repository file,
  2. Host it on a public web server,
  3. Make its location publicly available,
  4. Tie support for it in with your software package, and
  5. Keep the repository file and all related information updated.

This document will guide you in more detail through these steps.

1) Write the Repository File

The Luau repository file acts as a database for your users to access and query all available software packages (in addition to receiving any important messages or Luau configuration updates you make available). Your first responsibility in supporting Luau in your application is to write this file.

Luckily, the format is simple. Below you'll see an example repository file for the imaginary project "MyProject" — most likely, you'll be able to pick up on most everything just by glazing over it.

<?xml version="1.0"?>
<!DOCTYPE luau-repository SYSTEM "http://luau.sourceforge.net/luau-repository-1.1.dtd">

<!-- Updates file for myproject (id: "@ftp.example.com/myproject") -->


<luau-repository interface="1.0">
  <program-info id="@example.com/myproject">
    <shortname>myproject</shortname>
    <fullname>MyProject Projector</fullname>
    <desc>Projectilize projecting projectiles</desc>
    <url>ftp://ftp.example.com/myproject/myproject.repository.xml</url>
  </program-info>
  
  <software version="1.1.1">
    <date>2003-04-12</date>
    <keyword>UNSTABLE</keyword>
    <short>Upgrade to myproject version 1.1.1</short>
    
    <long>
Version 1.1.1 supports CoolStuff extensions and drops legacy support for pre-1.0 versions.
Many bug fixes have also been made, including:
o Preventing myproject from crashing when user inputs curse words
o No more gamma radiation problems (hopefully)
!!! NOTE !!!
INSTALLING version 1.1.1 WILL DROP COMPATIBILITY WITH BINARIES COMPILED WITH PRE-1.0 versions!
If this is a problem, please stick with the 1.0 branch
    </long>
    
    <package type="RPM" size="1200144" md5="29168bed9cc7e04652e82bc09b3c7b98">
      ftp://ftp.example.com/pub/myproject-1.1.1/binaries/myproject-1.1.1.rpm
    </package>
    <package type="DEB" size="1432534" md5="98336d9f8cb04bc909a9a2a13a9e893c">
      ftp://ftp.example.com/pub/myproject-1.1.1/binaries/myproject-1.1.1.deb
    </package>
    <package type="SRC" size="6323511" md5="717ab9d5dfcb8900ca14182dc0a0dbb2">
      <mirror weight="80%">ftp://ftp.example.com/pub/myproject-1.1.1/src/myproject-1.1.1.tar.gz</mirror>
      <mirror weight="20%">http://www.example.com/myproject/myproject-1.1.1.tar.gz</mirror>
    </package>
  </software>
  
  <update type="message">
    <id>201</id>
    <date>2003-04-14</date>
    <short>Artists needed!</short>
    <long>
  myproject is looking for some talented artists to help with the newly planned action simulation adventure game, "MyProject: The GAME." If you're interested, please contact jimbo@example.com
    </long>
  </update>
  
  <update type="luau-config">
    <id>301</id>
    <date>2003-04-14</date>
    <keyword>IMPORTANT</keyword>
    <short>New server</short>
    <long>
  We've got our own ftp server now, so we're trying to get everyone to switch over to using the example.com database. Please accept this update, since the old ftp server will be unavailable in a month or so, and trying to autoupdate from it after that will fail. Thanks. :)
    </long>
    <set url="ftp://ftp.example.com/pub/myproject/updates"/>
  </update>
</luau-repository>

A couple important things to note:

We've only gone over some of the more important aspects of the repository file here; for a complete reference, please see the Luau Whitepaper.

2) Host the Repository File on a Public Web Server

In order for your user-base to be able to retrieve message and software updates, they obviously have to be able to access the associated repository file. Therefore, your second responsibility as a developer is to host the repository file somewhere that it can be accessed by any of your users. This can be on either an FTP or HTTP (web) server, or really any protocol that cURL supports. Try to avoid hosting on secure HTTPS only locations, though, since some users may not have a SSL-enabled version of cURL installed and therefore won't be able to retrieve it.

Also, please try to host your repository on a stable host, i.e. somewhere you'll be able to host it for a long time without having to move it to a different location. Because of the way Luau works, in order to move a repository file to a different location, you must first inform your users (through the use of a Luau configuration update) of the new location and keep the old location available long enough for all your users to get the message and switch to the new URL. If you simply delete the repository file at the old location before all of your user-base has had the time to convert (which is essentially inevitable), then those users who didn't get the message in time will simply be left in the dust, with no clue as to what happened when they go to update your software and get a "404 Not Found" error message from Luau.

3) Make the Location of the Repository File Publicly Available

What this means is to simply put a small link or bit of information somewhere on your project web page giving the current location of the Luau repository file for your application. While this step is optional, it's helpful in two regards. First, in case that you do have to move your repository file to a different location, it lets any users who didn't get the Luau configuration update in time find out where the new repository location is without personally bugging you. Also, though, it lets users who have not yet installed your application register your application with the Luau database (through the --from-url option of luau-register) and from there either a) download and install your software, or b) keep tabs on the progress of your project. While this isn't currently one of the more advertised features of Luau, it is something I may consider expanding upon in future releases.

4) Tie Support for Luau in with Your Software Package

In order for the Luau front-ends to work with and find updates for your software application on the client machine, it needs to know a few essential bits of information about your software. Since Luau works on a decentralized basis (i.e. there isn't a central database that stores all relevant information about all Luau-supported software), you have to manually feed this information to Luau when your application is installed. This is done through the "luau-register" application distributed with Luau.

This is a good place to remind you that in order for your users to retrieve software and message updates through Luau, they must first install Luau on their machines. While you shouldn't (if possible) require your users to have Luau installed to use your application, you may want to do a simple check for the luau-register binary in your configure script (in the case of a source distribution) and give them a friendly suggestion that they install Luau in order to get automatic software updates if you can't find it.

Luckily, there isn't all that much data you have to give Luau in order for it to function. All of the options you have to (or may want to) pass to luau-register are described below:

The final argument to luau-register is simply the ID of your project. While simply using the short name of your project as your ID would seem to make sense, there's one significant problem that we want to avoid at all costs in such a loose, decentralized environment: ID overlap. That is to say, if two applications both use "myproject" as their ID and some unfortunate soul attempts to install both, the settings of one will simply overwrite the settings of the other. For that reason, while you are essentially free to choose whatever ID you find fit for your project (Luau doesn't impose any restrictions on it), I highly recommend you use the "root-name" format used by Autopackage, which looks something like this: "@mysite.org/shortname", where mysite.org is ideally a domain name you own and host your project off of. If you host your project off sourceforge.net, that's fine too ("@shortname.sf.net/shortname" or even just "@sf.net/shortname" would be sufficient); or if you host elsewhere, you can probably safely use that domain as well. This format leverages off the uniqueness of DNS domains to prevent collisions. The really important thing, though, is that you choose a name that there's no way anyone else could accidentally choose as well.

Here's the luau-register line used by Luau itself (version 0.1.7):

luau-register -u http://luau.sourceforge.net/luau.repository.xml -d "2004-06-12" -v 0.1.7 -i "4.0" -n "luau" -f "Luau Software Updater" -s "Automatically download and install updates" luau

Note that a lot of these options (specifically all those that don't relate to one particular software revision but rather to your project as a whole — e.g. description and name but not version or interface) are the same as the tags that fall under <program-info> in the Luau repository file (which makes sense: when you feed a repository file into Luau and tell it to register that application, it just reads those values and pipes them into luau-register). You should try to set these to the same values in both locations to prevent confusion.

After deciding on what all these options should be set to, you have to add the final luau-register command to your package so that it runs automatically when it is installed. In the case of a binary distribution, most package managers provide the ability to specify a "post-install script," which would be a good location to call luau-register (see the documentation for the respective package manager to figure out how to do this). If you're distributing source code and use automake, you'll probably want to use an "install hook," such as the following:

install-exec-hook:
  luau-register -u http://luau.sourceforge.net/luau.repository.xml -d ...

Finally, if you write your Makefiles by hand, then you can simply add a command to the end of your "make install" section.

5) Keep the Repository File and All Related Information Updated

This is your final responsibility as a developer, and probably the most annoying one, since it adds yet another item to the list of tasks you have to complete every time you release a new version of your software application. Unfortunately, there's no way around it: in addition to writing release notes, repackaging all your binaries, updating your project web page, making a freshmeat.net announcement, etc. etc., you now also have to make sure to remember to update and upload your Luau repository file and update any information (such as version, interface, etc.) in your post-install call to luau-register. This is the pivotal step in supporting Luau, since having an automatic update framework is useless if there isn't anyone providing the updates! While this is a nuisance, it's at least a rather simple one; just remember to do the following with each release:

  1. Update the following luau-register command-line options in your post-install script: --version, --date, and (if specified) --interface.
  2. Add a new <software> section to your repository file. Don't do this until after you've packaged up and uploaded your software package though, since you'll need to know the MD5 checksum and size of the package and the URL where it can be obtained. Simply copying and pasting in your release notes or your freshmeat.net announcement for the <long> tag is usually sufficient.
  3. After you've updated and uploaded the new repository file, fire up Luau-X and double check! Make sure the new release shows up, and then try to download a package to make sure you got the URL right. This may seem trivial, but trust me — especially if you simply copy and paste your old <software> section and edit the relevant parts for the new release, it is far too easy to miss something like a URL or an MD5 checksum. Always double check!

Conclusion

That's it! You're now a certified Luau Autoupdate Engineer (which is probably about as useful on your resume as that MCSE certification). While this document has been somewhat long, you'll find that Luau provides an extremely simple interface which should take no time at all to get acquainted with. If you do ever have any questions or comments about any aspect of Luau, please email me at "deklund at fastmail.fm". I'm always eager to hear what you have to say about Luau, whether it's an idea for a future release or a criticism of the current one.

Sidebar

Hosting by:

SourceForge.net Logo