MINI INSTALLER 1.0.1 free! JARS rated top 25%
see other Java utilities at:
Yagga's Java pages!

A simple package to build self installating programs in Java. The process is script driven, the result is a unique JAR file that the user can double click to execute a wizard-like installation process.

From versin 1.0 MiniInstaller is distributed free (binaries and source code)
under GNU's General Public License!

Download
bin & docs [Zip ] [JAR] (270K)
bin, src & docs [Zip ] [JAR] (660K)
[browse javadoc documentation]

If your browser messes up with the JAR, download the zip, and extract the jar.

(hits 38020 )
Older version (no src) 0.7 [Zip ] [JAR]
Older version 0.9 (no src)[Zip ] [JAR]

JDK:
1.2,1.3 or 1.4
version:
1.0.1
date: 16/Aug/2002
author:
Walter Gamba
e-commerce:
Free under GNU's GPL
inside Yagga framework: YES
thanx:

to everybody that wrote me asking for help, making suggestions, and criticizing.

Special thanx to Jean Pierre Daviau whithout whom there wouldn't be any version 1.0b, let it alone version 1.0...

MiniInstaller consists of a complete environment to build your own, simple, self installing JARs. The resulting JAR has only a 70K overhead added to the bare data you want to install.
Actions that can be performed by the resulting jar include:

  • display graphics
  • display text files
  • display notes
  • ask user to input values
  • ask the user to choose directories /files
  • unzip files
  • execute java classes or (better) JARs to perform custom operations
  • move back and forward during installation
  • copy files

All this behaviour is controlled via a very simple script language. The user can then launch the resulting big JAR file, and move back and forth in the installation process, just like the Inst*llWiz*rd-like Windows app.

The actual process of building the resulting self installing JAR file is done by copying MiniInstaller files in a directory, along with the application specific JARs and ZIPs and data files, modifying the script file, then launching from the command line a simple script.

The script simply JARs everything up, along with a suitable manifest file, so all the final user has to do in order to launche the installation wizard is to double click the jar file, or type: java -jar install.jar!


a sample screenshot of the installer

In this project I use some other classes that I'm also publishing. These classes regards JAR based resource managers and class loaders, and even can be used form inside a JAR file that is class-loaded by a class enclosed in another JAR (or in the same JAR if the former JAR is jar-red long)..

See MetaJarUtilities for further infos..

Changes from 1.0

  • Corrected glitch that made installation under JDK/JRE 1.4 go broke if path
    of install file contained spaces. Now the behaviour is corrected

Changes from 0.9

  • Added clean up of written files during install, if aborting installation
  • Corrected bugs with COPY
  • Corrected bugs and made interface more consisten
  • Corrected behaviuor for various EXEC_ steps.
  • Corrected execution of shell script upon exit of GUI
  • Added _LOOK_AND_FEEL to set look & feel of GUI
  • Added _SET_FONT to set various fonts
  • Corrected behaviour with _DIMS
  • Added _STEP_SHOW & HIDE to show/hide left step list
  • Added coloured Dialog Boxes

Changes from 0.7

  • Added working back button
  • Added EXEC_JAR_METHOD to execute a given method of a given class in a jar file
  • Added Splash Screen like options to (implicit state) START (text,title and image)
  • Added simple error messages (for copy, for example)
  • Added FINAL stage with simple ability to execute Java programs
  • Added default values to INPUT/INPUT_DIR
  • Added COPY stage to copy file. Very inefficientat this moment
  • Added predefined varibles that reflect user/java environment

Installation

To install the MiniInstaller, simply double click the JAR. Everything will be MiniInstalled for you!
Everything will be installed under a base directory, but among the several directories, if you plan to use only the installer facility, (disregarding source code etc) you can just look for the
install/ subdirectory.
This directory is the starting point for building your installers.
The simple directory layout (we call our install/ directory our base dir) that is created by default is explained in next section and will be created for you to experiment witha a sample file.

Installing Directory Layout

In order to create a self-installing JAR file you have to provide the following directory layout:

 <base_dir> 
| +- MiniInstaller.jar (main jar for installation utilities - Don't modify)
| +- installer.mf (manifest file for self-installing jar - Don't modify)
|
+- sample.conf (config file for installatin - Modify this file)
| +- makeinst.bat (bacth file (WIN95) 4 jarring process - Can modify)
| +- makeinst.sh (bacth file (UNIX) 4 jarring process - Can modify)
| +- data/
| | | +- any file of data you like here .... (directory names are just a suggestion)
|
+- imgs/
|
|
| +- any imgs you like here .... (you can use just one directory or many)
| +- jars/ | +- any jars you like here .... (just another name)

What to put and where to put it

Leave the 5 files alone. Just touch and modify the sample.conf file, DON'T RENAME it (unless you know what you are doing), but modifiy it to suit your configuration needs. Put the ZIPs with bundled software, JARs with software you want to execute on the target computer, IMGes and text files where you like. We suggest creating one or more subdirectories under the base dir in order to keep everything in order. Of course you can create subdirectories under DATA and so on. There is no limit on the depth of such directories.

If you add/remove directories from the above layout, you would likelymodify the makeinst script for your O.S. Simply add in the second command line (java -jar ...) the appropriate <dir_name>/* (/*.* for Win95).

How to test the script and the resulting installer

Once you have configured the installation script (sample.conf) and you have put every file in its proper place (as it is referenced by the config file) and before you run the 'makeinst' script jou can test the installer in a simpler way.

Just type:

> java -jar MiniInstaller.jar sample.conf

And test the interface. By setting DEBUG on you can debug easily the interface.

You can also test specific options by typing:

> java -jar MiniInstaller.jar COMMAND arguments...

for example:

> java -jar MiniInstaller.jar COPY src_dir "*.txt,*.java" dest_dir

COMMAND is one of the commands explained below, and arguments are arguments as needed, separted by a space. If arguments should enclose spaces, use double quotes around them. Using MiniInstaller this way has automatically DEUBG on, and there is no GUI, but everything is command line.

How to run the installer-building process

Once you have configured the installation script (sample.conf) and you have put every file in its proper place (as it is referenced by the config file) you can run the 'makeinst' script.

If the directory you have used are "data" "imgs" and "jars" (or even less) everything is ok, if not you have to modify the installation script on the second jar command by adding the specified directories.

Choose the appropriate script depending on your Operating System. In order to work the script (under unix) must have write and execute permission on the current directory.

The script takes no parameter, and if anything goes well, it generates a file named 'install.jar' in the current directory. Of course you can rename this file in any way you like.

How to test the Installer

Once you have generated the install.jar, copy it to an empty directory, and double click it with the mouse. If you have installed properly the JRE1.2 this should bring up the installatio program. If this doesn't work, open a console window (terminal under unix, DOS box under WIN95) change directory to the one with just the install.jar file, and type: > java -jar install.jar
This should bring up the same window.

The resulting installing application

The resulting installing application is a Inst*llShi@ld-like frame. The user can

  1. exit at any time, aborting the process.
  2. move back/forward one step at a time, if the step has completed
  3. terminate the installation if every step was executed

The window is divided in 4 areas.

  • TOP: title of the current step (with title of the installation)
  • LEFT: list of all steps. The current step is highlighted
  • RIGHT: the main panel. Displays infos, prompts the user, etc...
  • BOTTOM: navigation buttons: Exit, Back and Forward.

The script

The script is a simple text file, containig commands that drive the installation process. Commands are executed in the sme order as they appear in the file. Comments are lines that begin with '#' Commands can regard the installation window (colors, dimension etc..) or the actual installation process. Commands can have zero or more parameters.

Usually proper commands (not the ones beginning with "_" that affects how the Installer will look like) have associated a step name. This name is the name of the step, as it will appear in the LEFT panel.

NOTE: Please avoid intermixing appeareance commands with usual commands. If the installer hangs please group all commands that start with underscore at the brginning of the script file.

To debug the script you can set the internal variable DEBUG to true or 1, with the command:
SET,DEBUG,true
To unset debugging remove th line, or set DEBUG to false.

Please note that in the following list, parameters enclosed in square brackets are optional. So
_COMMAND <state_name> [,<value>]
means that a the command takes one or two parameters.

If a command has any parameter, these are separated with a sepration character, usually a comma. Strings enclosed in double quotes are considered as a single string, even if they contain the separator character.

There is VARIABLE substitution. If in a string parameter there is a substring of the form $VAR_NAME$ ('$' any_valid_var_char '$') than the character between the dollar signs form a variable name. If there is such a variable, the value of the variable is substituted in place of $...$.

Such a substitution can not be used inside step names.

So if FOO is 'Albert' the string "Hi $FOO$ how are you" becomes "Hi Albert how are you".

There are also C-like escape sequences, so if you have to write a path, for example "c:\temp" you should really write "c:\\temp", because "\t" has a special meaning and means <tab character>.. The same holds for "\n" that means <new line character>.

 

Appearance commands

Note: please try to use all apperance command as the first commands in the script. You can usually use them wherevery you want, but as for release 1.0 there is no handling of reverting settings when going back & forth during installation.
As a further suggestion, do a _HIDE command before changing settings, and display again the interface with _SHOW when you are done

_HIDE
hides the main window
_SHOW
displays the main window
_STEP_HIDE
hides the left step list
_STEP_SHOW
displays the left step list
_SEP_STR= <character>
set the separation character between parameters to <character>
_DIMS, <width>, <height>
set the dimension of the main panel (RIGHT) to <width> x <height> pixels. Please experiment a little with size before settling to a given dimension.
_SET_COL, <element>, <red> , <green>, <blue>
set the color of the specified <element> to (<red>, <green>, <blue>)
colors values can range from 0 to 255
<element> can be:
  • BK background
  • TITLE color of the title string (as written on the TOP panel)
  • SMALL_TITLE title of textual panel, if any
  • TEXT color of text in the RIGHT panel
  • STEP color of steps names in the LEFT panel
  • BTN button caption color (as in Bottom panel)
_TITLE, <string>
set the title of the isntallation to <string>
_LOOK_AND_FEEL, <look&feel name >
set the Java look and feel of the installer: This can be one of "windows", "motif", "metal" and "mac".
_SET_FONT, <element>, <font_face>, <font_style>, <font_size>
set the specified font element to the one provided.
<element> can be:
  • TITLE main title
  • SMALL_TITLE title of textual panel (if any), copy, unzip panels etc..
  • TEXT generic text
  • STEP steps names in the LEFT panel
<font_face> can be almost anything, but to maintain portability among platform use:
  • Dialog font used in dialog boxes
  • SansSerif like Arial..
  • Serif like Times New ROman
  • DialogInput
  • Monospaced like Courier
 
<style> can be:
  • 0 plain
  • 1 bold
  • 2 italic
  • 3 bold and italic
 

Commands

SET, <var_name>, <value>
set the value of a variable to the one given. Please note that the variable name is specified without enclosing $s. As a special case, setting "DEBUG" to 1 or true enables console debugging
START, <step_name>, <title> , <text>
Defines a start state, with a title and a text
START_IMG, <step_name>, <text> , <img_path>
Defines a start state, with a caption and an image
 
Please note that even if no explicit START or START_IMG state is given, a default one is created.
SHOW, <step_name>, <image_file>
adds a step named <step_name> that display an image (JPG or GIF supported).The path to the image file can be absolute, or -better- relative to files packed inside the main JAR file.
DISPLAY, <step_name>, <text_file>
adds a step named <step_name> that display a scrollable text file. The path to the text file can be absolute, or -better- relative to files packed inside the main JAR file.
WRITE, <step_name>, <text>
adds a step named <step_name> that display a text string
INPUT, <STEP_NAME>, <TITLE>, <PROMPT TEXT>, <VAR_NAME> [, <DEFAULT_VALUE>]
adds a step named <STEP_NAME> that propmt the user to specify a value. The prompt has a text and a global title, and the value the user enters is stored in the variable named <VAR_NAME>. If there is a default value, this value is pre-inserted in the input field
INPUT_FILE, <STEP_NAME>, <TITLE>, <PROMPT TEXT>, <VAR_NAME> [, <DEFAULT_VALUE>]
adds a step named <STEP_NAME> that propmt the user to choose a directory. A convenience "Browse" button is provided. The prompt has a text and a global title, and the chosen directory is stored in the variable named <VAR_NAME>. If there is a default value, this value is pre-inserted in the input field
UNZIP, <STEP_NAME>, <TEXT>, <ZIP_FILE>, <DEST_DIR>
adds a step named <STEP_NAME> that unzip a file in the user file system. The zip file specified must be JARred in the install.jar file. The destination directory is a directory in the user file system. If the directory does not exists, MiniInstaller tries to create it.
COPY, <STEP_NAME>, <SRC_DIR>, <FILE_MASK/FILE_MASK_LIST>, <DEST_DIR>
Copy files from source dir to destination dir. Files copied are the one given by the file mask. If a file list is given, it is a list of files or files mask separated by a comma (so enclose the list in double quotes). Masks are in the very simpe form of: 1) * 2) *.* 3) foo* 4) *bat 5) Ast*.java. No serious things like a*b.foo* are allowed.
EXEC_JAR, <STEP_NAME>, <JAR_FILE>, <PARAM_1>, .., <PARAM_N>
adds a step named <STEP_NAME> that excutes a jar file with parameters. The JAR file specified must be JARred in the install.jar file. The JAR file must specify in its manifest the Main-Class attribute. When executing the Jar, the installer invokes the main class's (provided it is Public) "main" method with the given number of parameters, that can be zero or more. The STDOUT result is storer in the special variable $_$ and displayed on the page.
It is more or less formally eqivalent to writing:

EXEC_JAR_METHOD, <STEP_NAME>, <JAR_FILE>, main_class, "main", param1, .., paramN
with the differcence that here parameters are packed inside a String array (String[]) that is passed as the only parameter to the main method.
EXEC_JAR_METHOD, <STEP_NAME>, <JAR_FILE>, <CLASS_NAME>, <METHOD>, <PARAM_1>, .., <PARAM_N>
adds a step named <step_name> that excutes a method inside a jar file with parameters. The JAR file specified must be Jarred in the install.jar file. The installer looks for the STATIC PUBLIC method of the given CLASS (give the fully qualified name of the class!), and the method is invoked with the given parameters. The first method of the given class with the same number of parameters as the ones passed is invoked. Simple conversion is made from String to appropriate types. No conversion is possible to arrays, so avoid using arrays. Use this to build libraries of classes and methods. The result of the method invokation, if any, is converted to String using standard toString() methods, is displayed on the page and stored in the special variable $_$.
You can specify the actual path or relative path of the jar file inside the main JAR. If you experience problems try making the main Class public.
As an example:
EXEC_JAR_METHOD,executing,data/myarkive.jar,my.com.MyClass,myMethod,"hello, boy!"

EXEC_JAVA, <STEP_NAME>, class, method, arg1, .., argN
executes a java public static method on an object of the class given. The method must be static and public, along with the class. The .class must be jarred in the jar file plainly (i.e. not inside another jar file). It cannot reside in a separate direcvtory but must BE in the root directory. Or in directories that reflect the package the class belongs to, but starting from the root directopry.
So EXEC_JAVA, net.userlab.Test, doSelfTest, true looks for a public static method named "doSelfTet", in a class whose byte code should reside in a directory located UNDER the ROOT directory, and named net/userlab/. It is better if the class also be public.
The result of the method invokation, if any, is converted to String using standard toString() methods, is displayed on the page and stored in the special variable $_$.
FINAL, <STEP_NAME>, <TITLE>, <TEXT> [,<SHELL_COMMAND>, <SHELL_CAPTION>]
adds the final step named <step_name> that concludes the installation process. The <title> followed by <text> is displayed. If a a Shell command and a caption are given, ask user if they want to execute the given shell command. The caption of the button that enables user to chose to execute the program is SHELL_CAPTION. The program is executed AFTER the graphical user interface is shut down, and just before MiniInstaller exits. It is kinda spawned, and so it is not in the control of MiniInstaller.
The program is almost equivalent to typing at the shell/command prompt "SHELL_COMMAND", but please note that STD_IN, STD_ERR and STD_OUT are directed to MiniInstaller, so the are not seen/usable by the user. Try using graphicl programs.
To obtain a certain degree of portability I have defined the special variable $OS_SHELL$ that you can use in SHELL_COMMAND. If you are launching an external program you shouldn't need such varible, but if you plan to invoke system commands (like 'dir' in Windoze, which it is not a separate program) you have to prefix it with $OS_SHELL$. Moreover this variable evaluates correctly (and differently) in Win98 and WinNT. So "$OS_SHELL$ start data/info.txt" evaluates to "command.exe /C start data/info.txt" on my Win2K machine, and this brings up notepad showing the file data/info.txt.
Not-much tested options are:
 

INPUT_CONSOLE (much like INPUT)

DISPLAY_CONSOLE (much like DIPLAY)

yes.. there is a console-only installation version. Currently this cannot be enabled directly.

Predefined varibles

The following variables are automatically defined by the system:

  • USER_NAME the name of the user running the installer
  • USER_HOME the home directory oif the user
  • JAVA_HOME home directory of currently running Java VM
  • JAVA_VERSION Java version!
  • OS_NAME name of the operating System
  • OS_ARCH platform onto whcih the operating System is running
  • OS_VERSION version of the operating System
  • OS_SHELL a special prefix to put before shell-like comamnds you may want to execute on exit, and it evaluates to "sh -c" on Uni*, "command /c" or "cmd /C" on Windoze
  • _ holds the textual results of the last EXEC_XXX command execution (use it as $_$)

Notes

Please note that the only way to copy one or more files to the target computer is to put those file(s) in a ZIP file, and unzip it. Then these files can be copied via the COPY command to desired directories.

Moreover, if you exit installation before its proper end, the program will delete isntalled files. Installed files are the one copied and unzipped. PLEASE be sure to write into empty directories.

How to build code

If you plan to buld your own code here is the flow-of-work I use:

  1. Write/Modify code in the src/ directory
  2. Javdoc documentation is stored in the javadoc/ directory
  3. Compile it in the bin/ directory
  4. Write sample.conf file in bin directory, along with any data file you plan to test MiniInstaller with
  5. test it from bin directory: >java net.yagga.miniinstaller.MiniInstaller sample.conf
  6. If you are satisfied, pack classes with
    > jar cvmf miniinstaller.mf MiniInstaller.jar net/yagga/miniinstaller/*.class net/yagga/miniinstaller/gui/*.class net/yagga/util/*.class img/*.*
  7. copy MiniInstaller.jar inside the install/ directory, and test it with your very own (actual) script
  8. Wrap everything up from install/ director, using the makeinst.xx script
  9. Copy the resulting install.jar file to an empty directory and test it again

The resulting install.jar file has the following layout:

install.jar
   |   
   +- MiniInstaller.jar
   |  
   +- sample.conf
   |  
   +- META-INF
   |    |
   |    +- manifest.mf 
   | 
   +- net/
   |   |
   |   +- yagga/
   |        |
   |        +-util/
   |            |
   |            +- BoostrapJarClassLoader.class  
   |   
   +- data/   (or whatever name you like)
   |    |
   |    +- any files.. 
   |
   +-imgs/ (or whatever name you like)
        |
        +- any img files.. 

The core of the MiniInstaller is the net.yagga.util.BootstrapJarClassLoader class. This class is the main class (as defined in the manifest file used by makeinst.xx scripts) of the install.jar file.
This class, using code cut & pasted from other classes of the net.yagga.util package (mostly MetaJarClassLoader, tailored to just this need) loads the main class from the MiniInstaller.jar file.
This class loads (using the same class loader..) all the MiniInstaller application.

In turn the application, run from inside MiniInstaller.jar (which, in turn, is inside install.jar) load resources (as classes, jars, images, etc) from the data/ (or whatever youhave named this directory) directory, or from jars in the data/ directory, or even from inside the same old MiniInstaller.jar, using net.yagga.util.ResourceMgr and related MetaJar* classes.

If you are interested in these tricks with jars and resources see the page of the MetaJarUtilities

Notes:

MiniInstaller uses four image files (that you can modify, of course) stored in the bin/img/ directories: The icon and two images (arrow diasbeld and arrow enabled) that appear on the left of step names, and a generic alert icon.

The default MiniInstaller code looks for a file name sample.conf to read commands from. At the moment you have to change the source code to modify this.

TO-DOs

  • Better deletion of installed files (and directories!!) upon abortion of installation
  • Implementing simple IF THEN ELSE statements
  • Adding check boxes/ radio button panels

BUGs

  • many.. I'm sure..

Yagga's Java pages are copyright(C) 1999
Walter Gamba

Yagga server and PbML are copyright (C) 1999
of Marco Becchio and Walter Gamba