Application Launcher Patches
From VCGR Wiki
Contents |
Pre-requisites
Before you can begin making a patch, you have to understand how the patching system works. First of all, the patching system will only patch the software when it starts up. Usually, this happens when a machine reboots. When the application starts up, and before any jars are loaded except for the application launcher itself, the patcher will check to see what the current version of the system is and what versions are available. Once that is done, any versions larger then the current (in consequitive order) will be downloaded and applied. If, at any point along the way, something goes wrong, the patch process will fail, rollback, and the system will start with the old version.
Finding the Update Directory and the Current Version
The update directory is indicated by the edu.virginia.vcgr.appwatcher.update-directory property, usually located in the $GENESISII/ApplicationWatcher/genii-base-application.properties file. This file also indicates the URLs to download patches from.
Inside the update directory should be a file called current-version.dat which must have the format ###.###.### Build ###. This describes the version in terms of a major number, a minor number, a sub-minor number, and a build number.
Making a Patch
- Identify the patch changes that have occurred. At the moment, the patcher supports two kinds of patch operations: Writing a file out, or deleting a file.
- Create a directory structure with the patches inside of it. This structure has the following format:
- A patch description file called META-INF/patch/patch-description.txt
- An optional directory called common
- An optional directory called linux
- An optional directory called windows
- The patch-description.txt file describes the patch operations to perform
- common, linux, and windows serve as the root directories of patch files to apply for writes. The path to the files must match the relative path in the Genesis II install for the patch. Files under common are applied to all platforms (assuming that the patch-description.txt file indicates this. Files under windows and linux are applied only on their respective platforms.
patch-description.txt Format
The patch-description.txt file is a series of lines describing, one operation per line, the operations to perform as part of the patch. The has symbol # is considered a line comment symbol and blank lines are ignored. Each line has the format:
- An optional permissions mode followed by at least one whitespace
- The token WRITE or DELETE followed by an amount of whitespace
- An optional operating system and hostname restriction
- A colon followed by any amount of whitespace
- A relative path
permissions mode
The permissions mode string is similar in format to a unix ls permissions display except that it only covers owner and others. This string is of the form rwxrwx where any single letter may be replaced by a - indicating that the permission should NOT be given. If this permissions mode string is omitted, the default permissions are used or, to the best of our ability, the permissions of the previously existing file are used.
operating system and hostname restriction
These restrictions are enclosed in square brackets. The format, within the square brackets is the token linux or the token windows or neither token, followed by a required colon (:) followed by an optional regular expression to match against the hostname. If the os restriction is given, this string indicates that the patch line should only be applied to installations on the indicated operating system. If the hostname pattern is given, then it is assumed to be a regular expression which MUST match the name of the host on which the patch is running (using case-insensitive matching).
relative path
The relative path describes both the source of a new file to write out, as well as the destination of a file to write or delete. When used as a source, the file is first checked for in the patch jar file's os specific path. Failing to find it there, the patching system looks for it in the common path structure.
Examples
The following example patch description text file shows various options in use.
WRITE: lib/foo.jar DELETE: bad-data/some-file.txt rwxr-x WRITE [linux:]: bin/some-script.sh rwxr-x WRITE [windows:^\w+\.eservices\.virginia\.edu$]: bin/some-script.bat
Forming the Patch
Once the patch directory structure has been formed and filled in, jar the whole directory structure up into a patch file. Place this on the website where patching are being retrieved from. Finally, update the file patch-versions file given by the target urls in the genesisII-base-application.properties file.
= patch-versions file
The patch-versions file is a file indicated by URLs in the application description properties file. This file is a file which describes, one per line, all known versions of the system that are available as patches. For this file, the has symbol # is a line comment character and empty lines are ignored.
Each line of the file is of the form:
<version-number>=<url>
Version numbers, as before, are strings with 3 integers, spaces, the word Build, spaces, and a build number. The url give the exact location of the patch jar file created that contains the patch. This can be a relative url or an absolute URL. The following is an example patch versions file.
1.1.1 Build 1000=Patch-1.1.1.jar 1.1.2 Build 1001=../Patch-1.1.2.jar 1.1.2 Build 1002=http://www.cs.virginia.edu/~mmm2a/AnotherPatch.jar
