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:

Write the repository file,
Host it on a public web server,
Make its location publicly available,
Tie support for it in with your software package, and
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">



<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:

The root tag is the <luau-repository> tag. The "interface=" option for this tag specifies the repository XML file format interface — Luau uses it to decide whether it is capable of reading and interpreting the given file. As of this writing the most current interface revision is "1.1," which hopefully won't have to be updated again soon. However, in the case of updates to the file format, you should try to modify your repository files as soon as possible in order to support the latest revision (especially in the case of a new "major" revision — e.g., "2.0" instead of "1.0"). For a full explanation of the "interface" format (which is also used for classification of libraries within Luau), see the Luau Whitepaper.
There are three tags valid within the <luau-repository> tag: <program-info>, <software>, and <update>. <software> tags specify different software revisions, while <update> tags encompass both messages and Luau configuration updates; any given repository file will likely have several <update> and <software> tags. On the other hand, there should be only one <program-info> tag, which specifies "meta-data" for the repository at hand. It allows users to feed a repository file into Luau and have it automatically register itself with the local Luau database.
The "version=" attribute of the <software> tag specifies the version of that software package. This attribute is required, and (this is the important part) must be "Luau compliant." The exact definition of "Luau compliant" is in the Luau Whitepaper, but in short, if you have a versioning scheme that follows something along the lines of MAJOR.MINOR.REVISION (or some minor variation), then you should be fine; otherwise, you should check the Whitepaper to see if your scheme will work (you should also be sure to check the Whitepaper if you ever use letters in your version numbers, since this may confuse Luau). If your versioning scheme is not Luau compliant, you'll have to use the <display-version> tag to specify the "real" version and use a "fake" version for the "version=" attribute — again, see the Whitepaper for details.
Both the <software> and <update> tags support the <date> tag, which specifies when that update was released (in the case of software) or announced (in the case of messages). You should always specify a date for any of the three kinds of updates since it gives the user a context in which to view the update. Note that the format is strict: all dates must be specified in the form YYYY-MM-DD, in conformance with the ISO 8601 standard. No delimiter other than "-" is valid; the year must be four digits long; both the month and day must be two digits long and padded with zeros if necessary (e.g. "2004-07-09" instead of "2004-7-9"); and the components must be specified in the right order. This is done in order to clarify an inherent ambiguity associated with any non-standard date format.
Also, the <software> and <update> tags both support the <id> tag, but there's an important difference here: the <id> tag is required for the <update> tag, but only optional (and really not recommended) for the <software> tag. The reason here is that Luau needs an ID attribute for all updates (including software updates) in order to differentiate between them; for software definitions, though, the version is simply used as the ID. There isn't any particular criterion for how you select IDs, but they should be short and preferably somewhat descriptive.
<package> tags occur in <software> definitions, specifying the location of the different available software package formats (e.g. RPM, DEB, etc.) available for any given software revision. The "size=" and "md5=" attributes are optional but recommended. Note that for any given file there should be only one <package> tag — if the file is available at several separate locations (i.e. mirrors), then you should use the <mirror> tag within the <package> tag (don't use separate <package> tags for separate mirrors of the same file).

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:

-u, --url=LOCATION
Specify the location of the Luau repository file for this program. This is a required argument.
-d, --date=\"YYYY-MM-DD\"
The date this software revision was released. This is an optional argument, and Luau doesn't even do much of anything with it, but it is useful for your users as it lets them know how old the software revision they're using is.
-k, --keywords="KEY1,KEY2,..."
Specify keywords specific to this release. This isn't used for anything internally in Luau as of yet (though it may be in the future), so only use it if you're going to interface directly with libuau and use the keyword capability to some effect.
-v, --version=VERSION
The (Luau compliant!) version of this software released. While this isn't technically required, it's highly recommended: it allows the Luau front-ends to automatically hide all software versions older than the one currently installed (since users usually aren't interested in downgrading their software — though that capability is present if needed).
-i, --interface=VERSION
The interface version of this software revision (most likely a library). This again isn't used internally by Luau, but it is used by Autopackage in determining dependency compatibility. If you're distributing a library, you may want to go to the trouble of keeping this field valid since it will be useful to anyone distributing an autopackage which depends on your software library. See the Luau Whitepaper for more details.
-n, --shortname=NAME
The short "UNIX name" of your software. This comes in handy for the Luau console front-end, in which case the ID of your program may be too cryptic to understand but the "full name" (explained below) may be too verbose to be typing out all the time. This should just be a one-word descriptive name of your program (e.g. "luau" for the Luau Software Updater or "gimp" for the Gimp Image Manipulator). If not specified, this will default to the ID of your software project.
-f, --fullname=NAME
The full, descriptive name of your software. This would be the "Luau Software Updater" or the "Gimp Image Manipulator" in the examples above. While this isn't required, it is highly recommended; if not specified, it will default to your short name.
-s, --desc=DESC
A short, one-line description of what your application does. Again, not required, but highly recommended.

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:

Update the following luau-register command-line options in your post-install script: --version, --date, and (if specified) --interface.
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.
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.