Automatic dependency retrieval

Autopackage is capable of downloading packages from the network in order to satisfy dependencies. This functionality is provided by luau, and for it to work correctly a few pieces of information are required:

The URL is stored in the Repository key of the skeleton file. This isn't the only way register a repository for a particular package - the registerRepository function is available as well. The XML file pointed to by the URL should be on an HTTP or FTP server.

A sample repository XML looks like this: below:

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

<luau-repository interface="1.1">

        <program-info id="@foo.org/libbar"> 

                <shortname>libbar</shortname>
                <fullname>Bar widget library</fullname>
                <desc>A library for barmen</desc> 

        </program-info>

        <software version="1.2">
                <date>2005-06-11</date>
                <interface version="1.2" />
                <keyword>UNSTABLE</keyword> 

                <short>Short declarative statement(s) about release for language en.</short>
                <long>
                        Paragraphs describing the release for language en.
                </long> 

                <package type="autopackage"
                         size="8746"
                         md5="e5ece8caf2b00d37d30cab0def847dd6">
                        http://foo.org/bar/libbar-1.2.x86.package
                </package>
        </software>

</luau-repository>

Most of the information in the repository XML file should match the package .apspec file, but particular details of this release need to be added to the software section.

Adding parameters b and x to makeinstaller when the package is generated will automatically create a new repository XML file for the package. makeinstaller will generate a single full package and two split packages into a meta package and a software payload package. In the above instance, the automatically created repository XML file would be named libbar.xml or libbar.xml.new to not overwrite a previous repository XML file.

                
$ makeinstaller -bx default

generates files:
    libbar-1.2.x86.package
    libbar-1.2.x86.package.meta
    libbar-1.2.x86.package.payload
    libbar.xml or libbar.xml.new [if .xml file already exists]

The table shows how the .apspec file relates to the repository XML file with some comments.

Table 6.4. Data Definitions between Package Repository File and .apspec File

XML Tag/Argument .apspec Meta Key Comments REQ?
program-info id Unversioned RootName Yes
shortname ShortName Yes
fullname DisplayName Yes
desc Summary No
url Matches Repository key in .apspec specfile No
date Matches the build date from the package environment file. No
short Short declarative statements about this release. No
long Paragraphs to describe this release. No
type Use 'autopackage' to describe package as an autopackage. Yes
size File size in bytes of the meta package. No
md5 md5 of the meta package. No
software version SoftwareVersion Yes
interface version InterfaceVersion Yes
version PackageVersion No
weight Proportional amount of time that the following mirror uri should be used. No
mirror Uri to be used to retrieve the package. http, https or ftp are available through curl. Yes

Note

The md5 and size are of the meta package. autopackage initially downloads the meta package to determine dependencies. The luau downloader uses the md5 to validate what to download and size gives some additional status information to the user.

All of the package files should all be in the same directory so that autopackage can find what it needs. If a user wants to start installing this package, the user would download and execute the full package ( .package ) . If another package has a dependency for this package, then autopackage would download the package repository XML file (.skeleton key) to determine where to find the packages. autopackage proceeds to download the meta package ( .package.meta ) to validate the package and determine what dependencies exist. This process is repeated until all the dependencies are fulfilled.

So how to tie this new XML file into peoples packages? The easiest way is to put a new Repository key into the skeleton files Meta section. It should contain the URL of the XML file. In this way, when people use the skeleton for libbar to depend on it, the URL of the XML file is compiled into the package. If the URL changes the dep resolution will break, so make sure it's stable!

Most of the time that's all you'll have to do. Autopackage provides more flexibility though for if you need it. The first mechanism is the [Retrieval] section. This goes into skeleton files and is invoked when a dependency is missing in order to try and retrieve it. Most of the time this section will be missing so autopackage will use the default instead, which just calls the "retrieve" API. If you want to, you can provide any arbitrary script here.

The second mechanism is the repository registration mechanism. Repositories are XML files and you can associate root names with URLs to XML files using the registerRepository() API. If you add a Repository key to the skeleton file this call is done for you, but any package or skeleton can register a repository for any root name. This is most often useful when a packager wishes to also package some dependencies, but because they aren't the maintainer of the dependency they shouldn't modify the skeleton file. Instead, in the [Prepare] section of the package, they can call registerRepository for their own private dependency repository and this will override any repositories registered later.

Luau supports mirroring. To use mirrors, define a set of them at the top of the XML file like so:

                
<mirror-list id="sourceforge">
    <mirror-def id="osdn">http://osdn.dl.sourceforge.net/sourceforge/libbar/</mirror-def>
    <mirror-def id="internap">http://internap.dl.sourceforge.net/sourceforge/libbar/</mirror-def>
    ... etc ...
</mirror-list>

Then refer to the mirrors in your package tags, like this:

                
<package type="autopackage" mirror-id="osdn" filename="libbar-1.2.x86.package" />