Pigskin

Program Tutorial

Pigskin Home   Pigskin Documentation

First we will set up a simple scenario in which Pigskin will be used to update the version of a client program called foo on a user's machine (we'll say the client machine is a Windows workstation). The executable files for the foo application are found in C:\Program Files\foo. In order to make foo update itself we need to have a few things set up: A running Pigskin server that knows about the foo application. This server can be located anywhere on the internet. An installation of the Pigskin client software installed somewhere on the client computer. A small program or batch file that will update the foo installation then run the (possibly newly updated) foo application. We'll address each of these steps one at a time below. Setting up and running the Pigskin server Because all of the information for the Pigskin system is stored on the server, setting up the server will likely be the most complicated part of setting up the Pigskin system. The steps invloved in setting up a server for our example are described below: First you must copy the Pigskin binary files to a permanent location on the server. Let's say our server is a Linux machine -- a good place to put the binary files might be /usr/local/pigskin. Make sure the apps directory is present in the installation. Next we have to set up the application directory so the server knows about the foo application. In the /usr/local/pigskin/apps directory, create a directory named foo. This directory will contain the executable files for versions of the foo application. You should put each stored version of the application in its own subdirectory. Each version has a version string which describes it. Let's say the version string of the active version of foo is 110 (representing version 1.10). So inside the /usr/local/pigskin/apps/foo directory we will make a directory named 110. Inside the /usr/local/pigskin/apps/foo/100 directory, you should put all the files needed to run the foo application version 110 (or possibly just the files needed to update it to version 110). Finally, you must let Pigskin know what the active version of the foo application is. Do this by creating a text file in the /usr/local/pigskin/apps/foo directory called active. This file contains the active version of the application on the first line. So in our example, the active file will just have 110 on the first line and that's it. Now the server should be set up to update the foo application. If you need an example of setting up the server, you can look at the apps/PIGSKIN directory. Now all we have to do is start the Pigskin server. All interaction with Pigskin programs is done through the PigskinDriver class. To start the server,change into the /usr/local/pigskin directory and run java pigskin.PigskinDriver -m server. This will start the server on the default port. You will have to investigate platform specific methods for appropriately running the server in your OS (such as running in the background in Unix or running as a service in Windows). Installing the Pigskin Client You must install the Pigskin binary files in a central location on the client. In our example, the client is a Windows machine. A good place to put these file might be C:\Program Files\Pigskin. Once the binary files are copied to the client, Pigskin is ready to be run. Creating a batch program to run Pigskin This batch program will run Pigskin to update the foo application, then run the foo application. In our example, the client is a Windows machine with foo installed at C:\Program Files\foo. We will create a batch file in C:\Program Files\foo to run the program. The contents of the batch file are listed and explained below. java -cp "C:\Program Files\Pigskin" pigskin.PigskinDriver -h mypigskinserver.com -a foo You must pass the -cp option to the JVM to tell java where to find the Pigskin executable files. The -h option to Pigskin tells the client where to find the server (in this case we're saying our server can be found at mypigskinserver.com). The -a option to Pigskin specifies the application name. This command downloads the active version of foo from the server. foo Assuming, the foo program can be started with the command foo. New in version 101a -- Pigskin Wrapper When Pigskin is run in "wrapper" mode, it will automatically start your application after updating it. Additionally, if your application terminates with error code 46, Pigskin will download the latest version of your application then re-start it. The idea behind this mode is that if your application determines that it is no longer running the same version as the server, it can terminate with error code 46 and Pigskin will update and restart it. To use wrapper mode, the batch file created above would now look like this: java -cp "C:\Program Files\Pigskin" pigskin.PigskinDriver -m wrapper -wrapper-command foo -h mypigskinserver.com -a foo The command above will automatically start foo, so there is no need to include an additonal command which starts the application. Additional Notes When a program is updated by Pigskin as described above, a file is created in the program directory called PIGVER. This file contains the active version of the application. Issues may arise if the application writes over this file or expects the file to contain a different value. If this is the case, you should specify a different location for the PIGVER file or use Pigskin in a different way.