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.
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:
This document will guide you in more detail through these steps.
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.
<!DOCTYPE luau-repository SYSTEM "http://luau.sourceforge.net/luau-repository-1.1.dtd">
<!-- Updates file for myproject (id: "@ftp.example.com/myproject") -->
<desc>Projectilize projecting projectiles</desc>
<short>Upgrade to myproject version 1.1.1</short>
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
<package type="RPM" size="1200144" md5="29168bed9cc7e04652e82bc09b3c7b98">
<package type="DEB" size="1432534" md5="98336d9f8cb04bc909a9a2a13a9e893c">
<package type="SRC" size="6323511" md5="717ab9d5dfcb8900ca14182dc0a0dbb2">
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 email@example.com
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. :)
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.
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.
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.
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:
Specify the location of the Luau repository file for this program. This is a required argument.
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.
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.
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).
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.
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.
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.
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:
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.
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:
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.