Loki Update Tool 1.0 Introduction ============ This is a tool written by Loki Software, Inc., designed to be used in conjunction with their setup and patchkit tools to automatically update installed products. Licensing ========= This update tool is available for use under the GNU General Public License. Basic Operation =============== First the update tool looks for updates for itself, and if any are available, automatically downloads and applies them and restarts. If an application name is given on the command line, the update tool looks for all updates that apply to the existing application, automatically applies them, and then quits. If the update tool is not given any command line arguments, then it enters an interactive mode in which the user can select available updates for any installed products. It then downloads the README for the patch and makes it available to the user while the rest of the patch is downloaded. If a GPG signature is available, it will be downloaded and used to verify the update. If the GPG signature isn't available, or cannot be verified for some reason, then an MD5 checksum is downloaded and used for verification. When the user chooses to continue, the update is executed, and passed the "--nox11" and "--noreadme" options, telling it to run in quiet mode and print out percentage progress information. When the patch completes, the user can continue applying updates until an error occurs or all updates are complete. Loki's games have a special feature built into them which allow you to run the game with the '--update' option to automatically update them and then restart for normal play. Update Creation =============== The update tool assumes that your patches have been created using the Loki patchkit tools, and packed using the makeself.sh script written by Stephane Peter. The patchkit tools are available from Loki Software, Inc. The makeself.sh script is available from: http://www.lokigames.com/~megastep/makeself/ When the product is installed with Loki's setup tool, it is provided with an product update URL, a place where a list of updates for this product are listed. The listing can be text or HTML, and must contain a set of entries in the form: Product: Version: Architecture: Libc: Applies: File: The product is the keyword name of the product, as specified by the "product" tag in the product installation description file. The name of the product actually shown the user is the product description, as specified by the "desc" tag in the product installation description file. The version is the version of the patch, i.e. what the final version of the product will be after the patch is applied. The patch is responsible for updating the installation database, which is done automatically by Loki's patchkit tools. The architecture is an optional comma separated list of architectures for which the patch is valid. The default is to match any architecture. Recognized keywords are: x86, ppc, alpha, sparc64, arm, any New keywords may be added by modifying arch.c in the setupdb distribution. The libc is an optional comma separated list of versions of libc for which the patch is valid. The default is to match any version of libc. Recognized keywords are: libc5, glibc-2.0, glibc-2.1 New keywords may be added by modifying arch.c in the setupdb distribution. The applies field is a comma separated list of product versions to which the patch may be applied. If the installed version of the product doesn't match one of these strings, then the patch is discarded. The file field is the archive file used to upgrade this product. You can also add an optional "Note: blah blah" field which is listed in parenthesis after the update version when shown to the user. These notes apply to versions, not patches, so if you want a note about a version, you only need to add it to one of the update listings for that version. The update tool supports patches that linearly increase an application version, convert to a different "flavor" of the product, or add extra functionality to the application. Components ========== Patches that add extra functionality to an application, in the form of an "add-on" or expansion pack are considered special in several ways: * They are considered separate components and may be patched separately from the main application. * They require a separate "Component" keyword that comes before the "Version" keyword in the patch description indicating the verbose name of the component. * The applies field of the patch description contains only a single version, and represents the minimum version of the product which must be installed for this component to show up as an update option. * Patches to this component must have a matching "Component" keyword. * The component installation update must be specified in the same file as the patches to this component. Since the description syntax for a new component update and patches to that component are the same, the entry with the lowest version number is considered the base update. * The component update must not modify any files in the base install, it should just add new files. Examples of good candidates for "components" might be game level editors, mission packs, development kits, etc. Flavors ======= An application flavor is designated by an extension to the application version, using any character except alphanumeric characters, the period, or a comma, followed by any amount of non-whitespace characters. An example of an application flavor might be "1.0 Spanish", or "1.1-demo" The patch tools support patches that convert from one flavor to another or upgrade the version of a particular flavor, but keep in mind that this is equivalent to a separate product in that only updates for your particular product flavor will be visible on the update selection list. The product as installed usually has no "flavor", this is the default. GNU Privacy Guard ================= While the update tool does not ship with GPG for legal reasons, it will take advantage of GPG for update checksum and verification if it is installed on the user's system. They do not need to know how to use GPG, the appropriate public keys are automatically downloaded from a public key server for update verification. More information about GNU Privacy Guard can be found at: http://www.gnupg.org/ Advanced Operation ================== If you give the update tool the command line argument "--verbose", it will be verbose about file transfers and patch application. If you give the update tool the command line argument "--debug", it will give full debug information about file transfers and internal parsing. If you give the update tool the command line argument "--noselfcheck", it will skip the normal check for updates for itself before going into normal operation. If you give the update tool the command line argument '--tmppath" followed by a directory name, it will use that directory as the temporary download path for updates and signatures. This defaults to ~/.loki/loki_update/tmp If you give the update tool the command line argument "--meta_url URL", it will parse the given URL for "product: URL" key/value pairs, and use those as the update URLs for the listed products. URL's may be relative filenames as well as normal internet style URLs. This makes it easy to create patch update disks. On the final download screen, you have three buttons that give you control over the update download sites. Each update download site is called a "mirror", and you can choose which site gives you the best download speed. The first button, "Choose Mirror", brings up a list of download sites for the current update, and let's you choose which one you want to use. The second button, "Next Mirror", automatically connects to the next available download site, continuing the download where it left off, if possible. The third button, "Save Mirror", saves the current download site to the file ~/.loki/loki_update/preferred_mirror.txt, and will use that site first for future downloads. If you download an update that has a GPG signature, the update tool will automatically try to download the public key for that signature from a public key server. The list of keyservers that are contacted for public keys is stored in ~/.loki/loki_update/keyservers.txt. You can add new servers to this file, one per line. Author ====== The Loki update tool was written by Sam Lantinga at Loki Software, Inc.