BuildInstaller provides support for installing Jape (or any other java-based application) on any machine on which java is installed, and for building self-extracting ``jar'' archives.
It was originally designed and written in less than a working day, so there may be some aspects of its implementation to simplify and some aspects of its functionality to enhance, but for the moment it will do the job we need doing. It is small, and the facilities it offers are minimal.
For a considerably more refined installer kit see: The IzPack site
Our method is to build an (executable) jar file containing everything that the application needs, together with a primary bootstrap installer class whose main program gets executed from the jar.
The primary bootstrap unpacks the jar in-situ at the installation site, before loading and instantiating a designated secondary bootstrap that can be written in java, or can be a shell script.
The point of building an executable jar is that some Windows java installations will let one execute a jar file by double-clicking on it -- this saves the poor installer from having to find out how to get java to work on a command line, and/or finding a way of unpacking a jar and/or making a windows shortcut to an executable.
Construct the resources you need for your application to work; place them in suitably-named folders/directories and files, then
java -jar buildinstaller.jar $(TARGET).jar [-switch parameter | filename]or, if you have installed the build installer command,
buildinstaller $(TARGET).jar [-switch parameter | filename]
This builds a self-installing jar called $(TARGET).jar
that can be
transported to any machine on which Java has been installed already.
To use the resulting installer on a Windows machine,
on which java has been properly installed (only the
jre is needed, not the whole jdk) just doubleclick on
$(TARGET).jar
. A control panel appears which
gives you the option to install the software beneath the
directory from which the command was run, or of choosing
a new installation folder.
It's usually possible to arrange to create runtime
scripts, and to make shortcuts to them with the appropriate
icons within. The -autoinstall
does this
without too much trouble.
To use the resulting installer on a Unixoid machine,
on which java has been properly installed, (only
the jre is needed, not the whole jdk), just run the
$(TARGET).jar
by a command such as the following
java -jar $(TARGET).jarThe following command turns on maximal monitoring at install-time, which can be useful
java -jar -DEBUG $(TARGET).jar
A control panel appears which gives you the option to install the software beneath the directory from which the command was run, or of choosing a new installation folder.
It's usually possible to arrange to create runtime
scripts, and to make shortcuts to them with the appropriate
icons within. The -autoinstall
does this
without too much trouble.
Filename (or folder name) arguments specify files that are
part of the permanent installation. At install-time they
are shipped (in their entirety in the case of folders)
to the installation folder -- the directory prefix of the
``source'' file or folder is replaced with the name of
the installation folder. (The -boot
switch
modifies this behaviour slightly: see below)
-debug -- Turns on maximal monitoring at installer-construction time -app "the app name" -- (not very optional) default is Jape -splash image file -- (optional) the installation splash image (should be a GIF or PNG) -splashside West, East or North -- (optional) which side of the screen the splash image is placed on (default North) -installdir folder name -- the (default) path to the folder into which the software will be installed This is relative to the path from which the installer is executed, and can be changed at install-time.
-autoinstall appname -- arrange to install (and construct a shortcut to, where appropriate) the application executable as appname. -autoicon icon filename -- the icon file to be used for the Windows shortcut (optional) -comment stuff -- (optional: default is the app name) comment to attach to the symbolic link (Windows) -autojar filename -- (optional) the name of the jar (default is appnameArguments to the following switches are subject to the substitutions described later..jar
as set by-autoinstall
) (The named jar file is shipped automatically)
-autocmd filename -- (optional) (Windows) if specified, is the name of a command file that will run the jar; otherwise we construct a shortcut directly to the jar. -autowork filename -- (optional) (Windows) if specified, is the name of the working directory in which the application will open. -explore command -- (optional) (Windows) command run in windows when the installation has finished.Arguments to the following switches are subject to the substitutions described later, as well as having %JAR% replaced by the aboslute path to the jar file
-windowsrun command -- (optional) (Windows) The windows command used to run the program. (default) javaw.exe -jar "%JAR%" %*% -unixrun command -- (optional) (Unix) The shell command used to run the program. (default) exec java -jar "%JAR%" "$@"
Up to 20 shortcuts can be installed by using the following switches. In the descriptions below n is a number between 1 and 20. Arguments are subject to the substitutions described later.
-shortcutn filename Install a shortcut with the given filename -ton filename The shortcut points to the given filename (it may be a program)The remaining shortcut-modifying switches are optional
-iconn filename The shortcut uses the given file as its icon -argsn arguments The shortcut is to a running program; it uses the given arguments (surround arguments that may have filenames in them with apostrophes; these are converted to double quotes within the shortcut) -dirn foldername The shortcut is to a running program; it starts in the given folder -commentn text Associate the text with the shortcut as a comment
%INSTALL% -- the installation folder %DESKTOP-COMMON% -- the common desktop folder %PROGRAMS-COMMON% -- the common programs folder %DESKTOP% -- the installing user's desktop %PROGRAMS% -- the installing user's programs %DOCUMENTS% -- the installing user's ``My Documents'' folder %PROGRAM-FILES% -- the system's ``Program Files'' folder
-choosebutton "caption" -- (optional) the folder-selection dialogue start button ("Choose Installation Folder") -setbutton "caption" -- (optional) the folder-selection dialogue confirm button ("Set Installation Folder") -label "caption" -- (optional) the caption placed beside the folder name ("Installation Folder") -exit "caption" -- (optional) the initial caption on the exit button ("Exit without installing") -finished "caption" -- (optional) the post-install caption on the exit button ("Exit (and cleanup) now") -desktop "caption" -- (optional) the caption on the ``Shortcut'' checkbox ("Shortcut on Desktop"/"Executable in $HOME/bin") -installbutton "caption" -- (optional) the caption on the start installation button ("Install") -bfont fontname -- (optional) button font (default Sanserif-PLAIN-14) -tfont fontname -- (optional) feedback window font (default Monospaced-PLAIN-14)
-delunix -- subsequent files are to be deleted during clean-up after a unix install -delwindows -- subsequent files are to be deleted during clean-up after a windows install
-cmdunix "command" -- the post-unpack shell command for Unixoid systems -cmdwindows "command" -- the post-unpack shell command for Windoid systems -cmdunix1 "command" -- the second post-unpack shell command for Unixoid systems -cmdwindows1 "command" -- the second post-unpack shell command for Windoid systems -classwindows class name -- the post-unpack class to load and instantiate (on Windows) -classunix class name -- the post-unpack class to load and instantiate (on non-Windows) -class class name -- the post-unpack class to load and instantiate (everywhere)
-cmd
XXX are normally deprecated, although: -cmdwindows 'explore %INSTALL%'
might be a useful one to try.
%INSTALL%
.
-cmd
XXX are run. The .class
file for the classes is automatically
shipped (and deleted during the cleanup phase).
import java.util.*; /** This is a skeletal post-install class */ public class postinstall { public void run(String install, Properties props) // This method must be defined { System.err.println("Install: "+install); System.err.println("Properties: "+props); } }
-sync -- synchronize and ship the files which follow as if they came from the directory in which the installation is being constructed (not usually needed). -boot -- ship the files and folders that follow into the %INSTALL%/bootstrap directory (for use by low-level post-install scripts and classes). This directory is removed at ``clean-up'' time. +sync -- turns off -sync (obsolete: meaningless) +boot -- turn off -boot (obsolete: implied by all switches other than -boot)
It would be simpler and better if this class were split into the bootstrap-builder and the primary bootstrap installer, but the overhead of the builder being present at install time is small anway.
I may need to add something for MacOSX installation.
.jar
file. On a Unix system this
is straightforward, on a Windows system the .jar
file extension must be
associated with the java runtime (rather than some archiving program, as sometimes happens).
java -jar buildinstaller.jar \ InstallBuildInstaller.jar \ installer.html \ -app "Build Installer" \ -autoinstall buildinstaller \ -autojar buildinstaller.jar
Also see the ant build file that is shipped with the sources.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
$Id: install.html,v 1.1 2005/07/29 14:57:41 rbornat Exp $