Automatic Software Updater

Use cases

• U1. Updates of the production download-client (user)
• U2. Initial download and updates of the production webstart-client (user)
• U3. Running the client in a development environment (coder)
• U4. Adding resources to the production client by non coders (graphic and sound contributor)
• U6. Providing a production download-client without update (packagers for linux distributions)
• U7. Providing production download-client and webstart-client for a forked projects (third party developers)

Documentation

This section describes how to implement the use cases mentioned above.

Adding resources to the production client (U4)

It is easy to add resources such as sounds and images to an official client by creating the folder structure next to the .jar files. So far example create a folder data/sound and place new ogg files in there.

Creating a simple, normal build without signing (U3, U6)

This is the easiest variant, just use Eclipse to setup a development environment or ant dist to do a unsigned build. The unsigned build is fully workable except for the updater.

In most cases you don't need the updater: The official one is incompatible with your changes and setting up your own one is quite a bit of work that may not worth the trouble.

If you are packing the Stendhal client for a Linux distribution, consider to just include a start-menu entry to the webstart-client and the required java dependencies: javaws http://arianne.sf.net/jws/stendhal.jnlp for the general client or https://stendhalgame.org/account/mycharacters.html for a client specific to the official server. This way you comply with the distribution policies that you need to recompile the code (there is no code in the package). But the client will automatically get our updates and people will not get angry at you or us because it is out of date compared to the official server. We do put a lot of effort into supporting old clients, but there are often minor glitches.

Creating an automatic updater (U7)

• Important: In the folder stendhal/src/games/stendhal/client/update copy game-default.properties to game.properties and change the GAME_NAME variable. This is vital because otherwise your updates and the official ones get mixed up.

• Next you need to create a key pair and save it in a file keystore.ks in the stendhal root folder:

keytool -genkeypair -keyalg RSA -keystore keystore.ks -alias certificatename -keysize 2048

• You may want to export a csf (certificate signing request) to get it signed by an official CA so that the Java Webstart does not complain about an untrusted signature

• Export the certificate to a file in stendhal/src/games/stendhal/client/update and adjust the variables in the "Automatic Updates" section

• Create a file build.ant-private.properties in the stendhal root folder with three entries: keystore.alias, keystore.update-alias and keystore.password. The first two variables should be the same.

• Make sure you never ever give keystore.ks or the build.ant-private.properties away

• Place the last stendhal-0.xx.jar into the folder build-archive and adjust version.old and version in build.ant.properties (Note: You may want to edit build.ant.properties and build.xml to use a different name).

• Run ant dist piping the output into a file

• Create your update.properties file based on the example version in the folder stendhal/src/games/stendhal/client/update. The file-signature.* section needs to be filled with the output from the build process. Alternativly you can use this command to generate the signature (for example for external files such as log4j.jar, marauroa.jar, jobirs.jar):

java -cp .:build/build_stendhaltools/:libs/ant.jar games.stendhal.tools.updateprop.UpdateSigner libs/log4j.jar libs/jorbis.jar ...

See also

• Fixing the updater