Kickstart 2.0 documentation

This is the online documentation page about the Kickstart 2.0 release.

Requirements

You need a Windows operating system running J2SE 1.4 or later.

Install instructions

Unzip the contents of the distribution into a directory in your file system. Have care to preserve the following file structure:

<kickstart-directory>
   |
   +- lib
   |   |
   |   +- kickstart.jar
   |
   +- Kickstart.exe

This is required to launch the Kickstart GUI application.

Before you start

In order to use the Kickstart application you need to package your finished Java application into a runnable JAR archive. It can be done using the jar command line tool that comes with your JDK. Don't forget to include in the manifest file a Main-Class statement, required to make your JAR a self-contained runnable archive. If you are not experienced in this process you can find more about it in your JDK documentation. Otherwise follow this link.

If your JAR works launching from the command-line the instruction

java -jar yourapplication.jar

then it is suitable for the use in a Kickstart generated EXE.

Using the GUI

Launch Kickstart.exe. You will see this GUI:

Kickstart GUI

To make your EXE follow these steps:

Give a name to your application. This is required.
Choose a type for your application. The GUI type will treat your application as a Windows GUI; the Console option will cause your application to be launched from inside a command-line window.
Supply your application runnable JAR. This is required.
Supply the path for the EXE that will be generated. This is optional. If omitted the EXE will be placed in the same directory of the source JAR, and it will have the same name of the archive, except for the .exe extension.
Select a Windows ICO file to use as the icon of the EXE. This is optional. If omitted a default icon will be used.
Supply any fixed JVM parameter your application needs. This is optional.
Press the Generate EXE button.

Easy, isn't it?

Moreover the Kickstart GUI gives to you another feature: the project management capability. You can save to a file all the parameters supplied in a given moment, to load them back again later.

The Kickstart Ant task

The Kickstart Ant task lets you take use of the EXE generator from within an Ant build procedure. In order to use the task copy kickstart.jar (it can be found in the lib directory of the distribution) in a place where it can be reached by your build.xml.

First of all you need to declare the task inside your build.xml file:

<taskdef
	name="kickstart"
	classname="it.sauronsoftware.kickstart.ant.KickstartTask"
	classpath="<path>/kickstart.jar" />

You have to supply a valid path to kickstart.jar inside the classpath attribute.

Once the task has been defined it can be used as showed below:

<kickstart
	name="..."
	type="..."
	jar="..."
	exe="..."
	icon="..."
	jvmparameters="..." />

Here comes an attribute reference:

name. The name of your application. It's required.
type. The type of your application. Accepted values are gui and console. It's optional and if omitted gui value will be assumed.
jar. The path that lead to your source JAR file. Obviously it's required.
exe. The path that lead to the target EXE file. Differently from the Kickstart GUI, this parameter is required in the Ant task.
icon. The path that lead to the Windows ICO file that should be used as the icon for the generated EXE. It's optional and if omitted a default one will be used.
jvmparameters. The parameters line that should be supplied to the JVM every time the application will be run. It's optional.

That's all, folks!

Programming issues

Let me explain how a Kickstart generated EXE works. When the user launchs it, the executable rebuilds the wrapped JAR file into a Windows temporary directory. Then a silent java -jar (or javaw -jar, depending on the type of the application) command is supplied to the system in order to start the newly recreated archive. Since the temporary directory isn't the one where the EXE is placed, the Java system property called user.dir will assume an unexpected (and also unpredictable) value. This issue afflicts every relative file system path used in the whole application, since the File class resolves relative paths according to the user.dir property value.

What does it means? Assume your application is running from "C:\myapp". When you do something like

File f = new File("config.txt");

it means "C:\myapp\config.txt" if you run directly the JAR, but it means "<an-unpredictable-path>\config.txt" if it has been launched by a Kickstart generated EXE.

Since the user.dir property value can't be changed, to avoid this issue the Kickstart generated EXE supply to your code an alternative system property, called kickstart.exe.dir. It represents the user effective path, from which the EXE has been launched.

In order to develop a more robust code, you should avoid the use of pure-relative paths. You can observe the following pattern to refer a file in a relative manner:

String userDir = System.getProperty("kickstart.exe.dir", System.getProperty("user.dir"));
File config = new File(userDir, "config.txt");

The code fetchs the value of the property kickstart.exe.dir. If it isn't supplied (maybe the Kickstart generated EXE isn't the only way you want to distribute your software) then the user.dir value will be assumed to be the good one. The value fetched will contribute to locate your needed resource in the File class constructor.