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
From versin 1.0 MiniInstaller is distributed free (binaries and source
under GNU's General Public License!
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 text files
ask user to input values
ask the user to choose directories
execute java classes or (better)
JARs to perform custom operations
move back and forward during installation
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)..
for further infos..
Changes from 1.0
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
Added _LOOK_AND_FEEL to set look & feel of GUI
Added _SET_FONT to set various
Corrected behaviour with _DIMS
- Added _STEP_SHOW & HIDE to show/hide left step
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
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/
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:
+- 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)
| +- any file of data you like here .... (directory names are just a suggestion)
| +- any imgs you like here .... (you can use just one directory or many)
+- 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
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.
> java -jar MiniInstaller.jar
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...
> java -jar MiniInstaller.jar COPY src_dir "*.txt,*.java"
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'
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
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
exit at any time, aborting the
move back/forward one step at
a time, if the step has completed
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 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:
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
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
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",
has a special meaning and means <tab character>.. The same holds
that means <new line character>.
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
hides the main window
displays the main window
hides the left step list
displays the left step list
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
color of the title string (as written on the TOP panel)
title of textual panel, if any
color of text in the RIGHT panel
color of steps names in the LEFT panel
caption color (as in Bottom panel)
set the title of the isntallation
set the Java look and feel of the
installer: This can be one of "windows",
_SET_FONT, <element>, <font_face>,
set the specified font element to
the one provided.
title of textual panel (if any), copy, unzip panels etc..
steps names in the LEFT panel
can be almost anything, but to maintain portability among platform use:
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>
Defines a start state, with a
title and a text
START_IMG, <step_name>, <text>
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
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
<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
UNZIP, <STEP_NAME>, <TEXT>,
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>,
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*
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
<JAR_FILE>, <CLASS_NAME>, <METHOD>, <PARAM_1>,
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
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
As an example:
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.
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
yes.. there is a console-only installation version.
Currently this cannot be enabled directly.
The following variables are automatically defined by
the name of the user running the installer
the home directory oif the user
home directory of currently running Java VM
name of the operating System
platform onto whcih the operating System is running
version of the operating System
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 $_$)
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
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:
- Write/Modify code in the src/
- Javdoc documentation is stored in the javadoc/
- Compile it in the bin/ directory
- Write sample.conf file in
bin directory, along with any data file you plan to test MiniInstaller
- test it from bin directory: >java
- If you are satisfied, pack classes with
> jar cvmf miniinstaller.mf MiniInstaller.jar
- copy MiniInstaller.jar inside
the install/ directory, and test it with
your very own (actual) script
- Wrap everything up from install/ director, using the
- Copy the resulting install.jar
file to an empty directory and test it again
The resulting install.jar file has the following layout:
| +- manifest.mf
| +- yagga/
| +- 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
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
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
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.
Better deletion of installed files
(and directories!!) upon abortion of installation
Implementing simple IF THEN ELSE statements
Adding check boxes/ radio button panels