source: trunk/components/flow-cytometry/dist/launcher.txt @ 6163

Revision 6163, 7.6 KB checked in by curtis, 10 years ago (diff)

Quick, sloppy launcher files for flow cytometry app.

Line 
1The Java launcher for Windows v1.22
2by Jacob Marner
3sep 9th 2003
4
5-----------------------------------------------------
6
7Purpose of this program:
8---------------------------------------
9Java is a great programming language, but it is
10generally somewhat complex for novice end-users to
11get the program up running. Traditionally they have
12to install a JRE, install any optional packages like
13Java3D, set the path environment variable and then
14start a batch file.
15
16This doesn't exactly seem professional to the Windows
17end-user who generally just expect to be able to hit
18an icon or .exe file to run. This launcher adresses this
19problem.
20
21This program is open-source under no license at all.
22Use it for what ever you want.
23
24
25Bundle your own Java VM
26--------------------------------------------
27A common problem with Java on the Windows platform
28is that various versions may be installed, including
29Microsofts own incompatible one and some of these
30may even be installed into the system path. To be
31absolutely sure that your program runs no matter what
32I highly recommend that you bundle a Java virtual
33machine with your application. Simply take the JRE
34directory of your preferred version and ship it with
35your program (in a zip file or whatever). I usually
36make a JRE subdirectory in my main application folder.
37
38
39Instructions
40-------------------------------------------
41Examples are shown in the next section.
42
43In this directory is a file called Launch.exe. This
44is the file that end-user will need to execute to
45run your Java program.
46
47You can rename it to whatever you want to fit your
48purposes.
49
50When the user starts the exe the following things
51will happen.
52
53It will try to open a text file in the current dir with
54the same name as the .exe file but with the .cfg extension.
55If that was not found it will look for a file named
56launcher.cfg. The found file will contain the
57information needed to start the application. You will
58need to edit that file.
59
60The first line of the launcher.cfg file is the
61current directory you want to use when your program
62runs. I usually find it convenient to change the
63directory to the root of my classes. If you do not
64want to change directory, just set this to the
65current directory (.). You can use both relative and
66absolute paths.
67
68The second line of the launcher.cfg file is the
69executable you want to run. This will usually be
70either java.exe or javaw.exe. To ensure that the
71correct VM is called you must give the full path
72(possibly relative) to the file. If you use a
73relative path it must be relative to the *new*
74workign directory as set in the first line.
75
76The third line of the launcher.cfg file is the
77parameters to the executeable. Say, I have
78packaged my program into a .jar file called
79MyCoolGame.jar then I would write:
80-jar MyCoolGame.jar
81Note that you can end this line with any
82parameters you wish to pass to your program.
83
84And thats that. You are running.
85
86Example 1:
87-----------------------------------------
88
89I have a game tetris that I want to distribute on the
90net. I have a lot of graphics and sound in it.
91
92Make a directory structure like this:
93
94tetris.exe (renamed version of launcher.exe)
95JRE/ (a copy of of JRE 1.3.1 files - you can use any JRE)
96launcher.cfg
97classes/tetris.jar (the java program)
98classes/data/ (the graphics and sound needed for the game)
99
100The set launcher.cfg to this:
101
102classes
103..\Jre\1.3.1\Bin\javaw.exe
104-jar tetris.jar
105
106RUN!
107
108Advanced issues:
109---------------------------------------------
110
111Desktop icon:
112Also you will likely want to make a shortcut
113to it from the desktop or start menu. If you use
114programs such as InstallShield then this can be done
115for you automatically. If you package your program
116with say WinZip (possibly self-extracting) then
117users will have to click the .exe file to start.
118
119Changing icon embedded in exe:
120To change the icon embedded in launch.exe you need
121to recompile the program. The source and project
122files for Microsoft Visual C++ can be found in the
123source directory. In Visual C++ just replace the
124icon with your own one and then recompile.
125
126An issue with native DLLs:
127To be sure that your own native DLLs can be
128found you must place them in one of the
129following directories:
130* The current directory
131* The directory with the executable you started.
132   (usually JRE\1.3.1\bin)
133If you change the current directory during the
134execution of your program I recommend putting
135them in the JRE\1.3.1\bin directory.
136
137Having multiple launchers in the same directory:
138When just using launcher.cfg it is impossible to start
139several Java applications from within the same directory
140since they would all use the same launcher.cfg file.
141To allow this, the launcher will first look for a
142file that has the same name as the .exe file but has the
143.cfg extension instead. If such a file is found that is
144used instead of launcher.cfg. Note that this only works
145if the .exe file has no spaces in its name.
146   
147Error messages:
148--------------------------------------------------------
149First, let me note that the launcher error messages
150are written with the end-user in mind - not you, so
151to get the explanations you must read here.
152
153Error message: "Could not find file %s or launcher.cfg.
154Please reinstall the application."
155Reason: The file launcher.cfg could not be found
156in the working directory. Put it in the same
157directory as the exe itself. If you start the
158exe via a shortcut make sure that the working
159directory set in the shortcut is current.
160
161Error message: "Could not find the directory given
162in %s. Please reinstall the application."
163Reason: The directory given in the first line of
164the launcher.cfg could not be found. Make sure it
165exists.
166
167Error message: "Could not start the application.
168Please reinstall the application"
169Reason: The executable file given in line two of
170launcher.cfg (typically javaw.exe) could not be found
171in the directory given in line 1 of launcher.cfg. Since
172this error is produced after the one stating that the
173directory could not be found (see above) it is most like
174that it is line two in launcher.cfg that is incorrect.
175
176
177Trouble shooting:
178--------------------------------------------------------
179
180Problem: Nothing happens when I start the exe.
181
182Reason 1: You made a console application but started
183it with javaw.exe in line 2 of launcher.cfg. Change it
184to java.exe
185
186Reason 2: The java class or jar file you gave to the
187launcher in line 3 of launcher.cfg could not be
188found or did not contain a main file (class files) or
189a manifest file (jar). Line 3 of launcher.cfg should
190be the same command line arguments that you use with
191java or javaw on the command line to start the application
192manually. I.e. if you are used to writing
193java -hotspot myapp
194on the command line then line 3 should be
195-hotspot myapp
196
197Problem: The custom named configuration file I made could
198not be found.
199
200Reason: The .exe file name may not contain any spaces. be
201sure to remove them.
202
203
204Tips:
205------------------------------------------------------
206
207Passing arguments to the JVM:
208
209If you need special JVM options simply pass them
210by writing them in the beginning of launcher.cfg
211line 3 before the jar or class file name.
212
213Passing arguments to java:
214
215If you need to pass arguments to your java program
216you can do this in two ways:
2171. Write them in the end of the line 3 in launcher.cfg
2182. Pass them to the exe file (e.g. launch.exe).
219If you pass arguments both places then they are
220concatenated and all passed to your Java application.
221The ordering of the arguments in Java is such that
222those in launcher.cfg comes first.
Note: See TracBrowser for help on using the repository browser.