svn-gvsig-desktop / tags / v1_9_Build_1235 / install / IzPack / src / doc / chapter4.tex @ 33814
History | View | Annotate | Download (42.2 KB)
1 |
% IzPack - Documentation |
---|---|
2 |
|
3 |
% Shortcut definition |
4 |
|
5 |
\chapter{Desktop Shortcuts} (by Elmar \textsc{Grom} and Marc \textsc{Eppelmann})\\ |
6 |
|
7 |
\section{Defining Shortcuts} |
8 |
|
9 |
\subsection{Introduction} |
10 |
|
11 |
On todays GUI oriented operating systems, users are used to launching |
12 |
applications, view web sites, look at documentation and perform a |
13 |
variety of other tasks, by simply clicking on an icon on the desktop or |
14 |
in a menu system located on the desktop. Depending on the operating |
15 |
system these icons have different names. In this context we will refer to |
16 |
them collectively as shortcuts.\\ |
17 |
|
18 |
Apart from actually placing an application on the target system, users |
19 |
routinely expect an installer to create the necessary shortcuts for the |
20 |
application as well. For you as application developer, this means that |
21 |
for a professional appearance of your product you should also |
22 |
consider creating shortcuts.\\ |
23 |
|
24 |
In contrast to the general specification of an IzPack installer, the |
25 |
specification of shortcuts in IzPack requires a little more effort. In |
26 |
addition, some of the concepts are a bit more complex and there are some |
27 |
operating system specific issues to observe. Fortunately, you only need |
28 |
to worry about operating system specifics if you want to deploy your |
29 |
application to multiple different operating systems. In any case, it |
30 |
will pay off to spend some time to study this documentation and the |
31 |
example spec files before you start to implement your own shortcuts.\\ |
32 |
|
33 |
At the time of writing this Chapter the current IzPack Version 3.7.0-M3 is only |
34 |
capable to creating shortcuts on |
35 |
\begin{enumerate} |
36 |
\item Microsoft Windows\\ |
37 |
and |
38 |
\item Unix and Unix-based operating systems (like Linux), which use the \href{http://www.x11.org/}{X11} GUI-System and \href{http://www.freedesktop.org/}{FreeDesktop.org} |
39 |
based shortcut handling (such as \href{http://www.kde.org/}{KDE} and \href{http://www.gnome.org/}{Gnome}). |
40 |
|
41 |
\end{enumerate} |
42 |
|
43 |
Other operating or GUI systems, such as MacOS \texttt{<} MacOS-X are |
44 |
not supported. However, there is a special UI-variant that automatically pops up |
45 |
on unsupported systems. It informs the user about the intended targets of your shortcuts and allows |
46 |
the user to save this information to a text file. While this is not an |
47 |
elegant solution, at least it aids the user in the manual creation of |
48 |
the shortcuts.\\ |
49 |
|
50 |
If you would like to review what an end user would see if the target |
51 |
operating system is not supported, you can do the following. Simply |
52 |
place the tag \texttt{<notSupported/>} in the spec file. This tag requires no |
53 |
attributes or other data. It must be placed under \texttt{<shortcuts>}, just like |
54 |
the individual shortcut specifications. Be sure to remove this tag |
55 |
before getting your application ready for shipment.\\ |
56 |
|
57 |
We expect other operating systems to be supported in the near future and |
58 |
as always, contributions are very welcome. At present someone is |
59 |
actively working on Mac support. |
60 |
|
61 |
\subsection{What to Add to the Installer} |
62 |
|
63 |
There are some things that you have to add to your installer to enable |
64 |
shortcut creation. Obviously you need to add the panel |
65 |
responsible for creating shortcuts. This panel is aptly enough called |
66 |
ShortcutPanel. However, in order for the ShortcutPanel to work |
67 |
properly a number of additional items are required. These must be added |
68 |
manually to the installer, as all other resourcs, since the front-end will be rewritten. |
69 |
In this chapter we will explain which of these items are |
70 |
required and for what reason.\\ |
71 |
|
72 |
First, we would like to discuss items that are supplied with IzPack and |
73 |
only need to be added to the installer. After that, we move on to the |
74 |
things you have to prepare yourself before you can add them. The way in |
75 |
which shortcuts are created varies widely among operating systems. In |
76 |
some cases it is possible to do this with pure Java code, while |
77 |
other systems -such as MS-Windows- require native code to accomplish |
78 |
this task. On the other side, the current implementation, which creates shortcuts on |
79 |
Unix based systems needs no native library at all, since it works with 'these' pure Java code. |
80 |
The native library required for the Windows operating |
81 |
systems are supplied with IzPack is called \texttt{ShellLink.dll}. |
82 |
Note: They will not be automatically added to your installer file. |
83 |
You need to list them yourself in the XML file for |
84 |
the installer. A describtion how to do this follows in the next section.\\ |
85 |
|
86 |
Native libraries can be added to the installer by using the |
87 |
\texttt{<native>} tag. To add the \texttt{ShellLink.dll}, you just |
88 |
have to add the following line to the installer XML file:\\ |
89 |
\texttt{<native type="izpack" name="ShellLink.dll"/>}\\ |
90 |
For more details about the use of the \texttt{<native>} tag see the |
91 |
chapter about the format of the XML file.\\ |
92 |
|
93 |
You have also to add an extra specification file for each platform family to enable shortcut creation on these platforms. |
94 |
At least one (the default file) is required by the shortcut panel. The format of all spec files is XML and they must be |
95 |
added to the installer as a resource. The source name of this |
96 |
specification does not matter, however its resource name (also called id or alias) when added to the |
97 |
installer must be \texttt{(prefix)+shortcutSpec.xml}.\\ |
98 |
At this release, there are only two prefixes supported: "Win\_" for the Windows family and "Unix\_" for all Unixes. |
99 |
If the prefix is ommited the shortcut panel searches for a named resource: \texttt{shortcutSpec.xml}. This is the default resource name. |
100 |
As the default resource name will be used on Windows platforms, the \texttt{"Win\_shortcutSpec.xml"} can be ommited.\\ |
101 |
Hint: If the shortcut panel does not find one of these named resources, it will never appears. |
102 |
So, do not use different resource names and do not add a path to these.\\ |
103 |
|
104 |
\textbf{Example}\\ |
105 |
|
106 |
\footnotesize |
107 |
\begin{verbatim} |
108 |
<res src="C:\MyDocuments\Installer\default_shortcut_specification.xml" |
109 |
id="shortcutSpec.xml"/> |
110 |
<res src="C:\MyDocuments\Installer\unix_shortcut_specification.xml" |
111 |
id="Unix_shortcutSpec.xml"/> |
112 |
\end{verbatim} |
113 |
\normalsize |
114 |
|
115 |
Why use different shortcut spec files?\\ |
116 |
|
117 |
\begin{enumerate} |
118 |
\item The Target filenames are most different.(batch files on Windows vs. shell scripts on Unix.) |
119 |
\item The Icon file formats are different. ICOs on Windows-, PNGs on Unix-platforms. |
120 |
\item The Target locations can be different. |
121 |
\end{enumerate} |
122 |
|
123 |
This is the simple reason.\\ |
124 |
|
125 |
|
126 |
|
127 |
\subsection{Why Native Code to do the Job on Windows?} |
128 |
|
129 |
by Elmar\\ |
130 |
|
131 |
This little chapter is not strictly part of the documentation but I have |
132 |
been asked this question sufficiently often that I think it's worth |
133 |
explaining right here. It is certainly a natural question to ask. After |
134 |
all IzPack is an application completely written in Java and primarily |
135 |
targeted for the installation of Java based programs. So why wouldn't we |
136 |
try to keep everything pure Java and avoid the use of native code |
137 |
altogether? There must be some personal preference of the developer |
138 |
hidden behind this approach you might think. Well, not really, but I |
139 |
admit at first it seems quite feasible to write it all in Java. On |
140 |
virtually any operating system or GUI surface around, Shortcuts are |
141 |
simply files on the local file system. Files can be created and accessed |
142 |
directly from within Java, so why should there be a need for using |
143 |
native code?\\ |
144 |
|
145 |
Well, it turns out that just creating a file is not good enough, it also |
146 |
needs to have the right content. Shell Links as they are called in |
147 |
Windows land are binary files. I actually managed to find documentation |
148 |
on the format. Naturally this was hacker data, you won't get this sort |
149 |
of thing from Microsoft (by the way: thanks a lot to Jesse Hager for a |
150 |
smash job!). Armed with this information I tried to create these files |
151 |
myself in Java. The problem was that the documentation was not entirely |
152 |
accurate and had some gaps as well. I tried for over a month to get this |
153 |
to work but finally I had to give up. Even if I would have succeeded, it |
154 |
would have been a hack, since a shell link requires some information that |
155 |
is impossible to obtain from within Java. Usually you can successfully |
156 |
create a shell link by only filling in the bare minimum information and |
157 |
then ask Windows to resolve the link. Windows then repairs the shell |
158 |
link. Unfortunately this was only the beginning, soon I encountered a |
159 |
host of other problems. For one thing, the installer needs to know the |
160 |
correct directories for placing the links and it turns out they are |
161 |
named differently in different countries. In addition, there are ways of |
162 |
manually modifying them, which some people might actually have done. The |
163 |
only way to place the shortcut files reliably is through accessing the |
164 |
Windows Registry. Naturally, this operation also required native code. |
165 |
Same thing with asking Windows to resolve the link... On the bottom |
166 |
line, at every step and turn you run into an issue where you just need |
167 |
to use native code to do the trick. So I decided that I would do it the |
168 |
proper way all the way through. That is in a nutshell the reason why I |
169 |
used native code to create shortcuts on MS-Windows.\\ |
170 |
|
171 |
As I am writing this I am at work with a friend to replicate this work |
172 |
for the Mac and it looks very much like we need to take the same |
173 |
approach there as well. On the various Unix GUIs on the other hand, we are lucky that we |
174 |
can do the job without native libraries.\\ |
175 |
|
176 |
\subsection{The Shortcut Specification} |
177 |
|
178 |
As we say above, the specification for shortcuts is provided to the ShortcutPanel in the |
179 |
XML fileformat. At the time of this writing (for IzPack version 3.7.0-M3) |
180 |
the front-end will be rewritten. Until these work is in progress |
181 |
you have to write the specification files manually. For your convenience, there are two annotated sample |
182 |
specification files in the sample subdirectory of your IzPack installation. At the beginning you might want to experiment with these files.\\ |
183 |
|
184 |
Both specification files have one root element called \texttt{<shortcuts>}. |
185 |
This root elements recognizes 3 different child elements:\\ |
186 |
\texttt{<programGroup>}, \texttt{<skipIfNotSupported/>} and \texttt{<shortcut>}.\\ |
187 |
|
188 |
\texttt{<skipIfNotSupported/>} can be used to avoid the panel to show the alternative UI which shows the shortcut information |
189 |
that would have been created on a system that supports it. In other words, |
190 |
using this tag will make the panel be silent on non-supported systems. The |
191 |
default is to show the alternative UI.\\ |
192 |
|
193 |
The \texttt{<programGroup>} tag allows you to specify the name of the |
194 |
menu, or more precise, the folder in which the shortcuts will be grouped. The exact location and |
195 |
appearance of the program group depends on the specific target system on |
196 |
which the application will be installed, however you can partially control it. |
197 |
Please note that \texttt{<programGroup>} may only appear once |
198 |
in the specification. If more than one instance occurs, only the first |
199 |
one will be used. This tag requires two attributes: \texttt{defaultName} |
200 |
and \texttt{location}. \texttt{defaultName} specifies the name that the |
201 |
group menu should have on the target system. You should be aware that |
202 |
the ShortcutPanel will present this name to the user as a choice. The |
203 |
user can then edit this name or select a group that already exists. As a |
204 |
result, there is no guarantee that the actual name of the program group |
205 |
on the target system is identical with your specification. |
206 |
\texttt{location} specifies where the group menu should show up. There |
207 |
are two choices: \texttt{applications} and \texttt{startMenu}. If you |
208 |
use \texttt{applications}, then the menu will be placed in the menu that |
209 |
is ordinarily used for application shortcuts. \texttt{applications} is recommended for Unix shortcuts. |
210 |
If you use \texttt{startMenu}, the group menu will be placed at the top most menu |
211 |
level available on the target system. Depending on the target system, it |
212 |
might not be possible to honor this specification exactly. In such |
213 |
cases, the ShortcutPanel will map the choice to the location that most |
214 |
closely resembles your choice. Unix shortcuts do not need to support the \texttt{startMenu}, because the \texttt{applications} menu is already on the highest level. This means this has no affect on thess platform.\\ |
215 |
|
216 |
For each shortcut you want to create, you have to add one \texttt{<shortcut>} tag. |
217 |
Most details about the shortcut are listed as attributes with this tag. |
218 |
The following sections describe what each attribute does, which |
219 |
attributes are optional and which ones are required and what the values |
220 |
are that are accepted for each of the attributes. Note that all |
221 |
attributes that have a yes/no choice can also be omitted. Doing so has |
222 |
the same effect as using a value of no. The shortcut attributes can be |
223 |
divided into two groups\\ |
224 |
|
225 |
\begin{itemize} |
226 |
\item attributes that describe properties of the shortcut |
227 |
\item attributes that define the location(s) at which a copy of the |
228 |
shortcut should be placed. |
229 |
\end{itemize}\ |
230 |
|
231 |
The following attributes are used to define location: |
232 |
\begin{itemize} |
233 |
\item \texttt{programGroup} |
234 |
\item \texttt{desktop} |
235 |
\item \texttt{applications} |
236 |
\item \texttt{startMenu} |
237 |
\item \texttt{startup} |
238 |
\end{itemize}\ |
239 |
|
240 |
\subsection{Shortcut Attributes} |
241 |
|
242 |
There are three classes of attributes. Some are required, most are |
243 |
completely optional and some are semi-optional. The set of semi-optional |
244 |
attributes are all the attributes used to define the location of a |
245 |
shortcut. These are semi-optional because for any individual one it is |
246 |
your choice if you want to include it or not. However they are not |
247 |
completely optional. You must specify at least one location. If all were |
248 |
omitted, the instruction would essentially tell the panel that a copy of |
249 |
this shortcut is to be placed at no location. In other words no copy is |
250 |
to be placed anywhere. |
251 |
|
252 |
\textbf{name} \texttt{- required}\\ |
253 |
|
254 |
The value of this attribute defines the name that the shortcut will |
255 |
have. This is the text that makes up the menu name if the shortcut is |
256 |
placed in a menu or the caption that is displayed with the shortcut if |
257 |
it is placed on the desktop.\\ |
258 |
|
259 |
\textbf{target} \texttt{- required}\\ |
260 |
|
261 |
The value of this attribute points to the application that should be |
262 |
launched when the shortcut is clicked. The value is translated through |
263 |
the variable substitutor. Therefore variables such as |
264 |
\texttt{\$INSTALL\_PATH} can be used to describe the location. |
265 |
\textbf{You should be aware that the use of this tag is likely to change |
266 |
once other operating systems are supported}.\\ |
267 |
|
268 |
\textbf{commandLine} \texttt{- optional}\\ |
269 |
|
270 |
The value of this attribute will be passed to the application as command |
271 |
line. I recommend to work without command line arguments, since these are |
272 |
not supported by all operating systems. As a result, your applications |
273 |
will not be portable if they depend on command line arguments. Instead, |
274 |
consider using system properties or configuration files.\\ |
275 |
|
276 |
\textbf{workingDirectory} \texttt{- optional}\\ |
277 |
|
278 |
This attribute defines the working directory for the application at the |
279 |
time it is launched. I would recommend some caution in relying on this |
280 |
too heavily if your application should be portable, since this might not |
281 |
be supported by all operating systems. At this time I don't have enough |
282 |
information to make a definite statement one way or the other. The value |
283 |
is translated through the variable substitutor. Therefore variables such |
284 |
as \texttt{\$INSTALL\_PATH} can be used to describe the directory.\\ |
285 |
|
286 |
\textbf{description} \texttt{- optional}\\ |
287 |
|
288 |
The value of this attribute will be visible to the user when a brief |
289 |
description about associated application is requested. The form of the |
290 |
request and the way in which this description is displayed varies |
291 |
between operating systems. On MS-Windows the description is shown as a |
292 |
tool tip when the mouse cursor hovers over the icon for a few seconds. |
293 |
On some operating systems this feature might not be supported but I |
294 |
think it is always a good idea to include a brief description.\\ |
295 |
|
296 |
\textbf{iconFile} \texttt{- optional}\\ |
297 |
|
298 |
The value of this attribute points to the file that holds the icon that |
299 |
should be displayed as a symbol for this shortcut. This value is also |
300 |
translated through the variable substitutor and consequently can contain |
301 |
variables such as \$INSTALL\_PATH. If this attribute is omitted, no icon |
302 |
will be specified for the shortcut. Usually this causes the OS to |
303 |
display an OS supplied default icon. \textbf{The use of this attribute |
304 |
is also likely to change once other operating systems are supported. |
305 |
Read the Section about Icons below, for more information.}\\ |
306 |
|
307 |
\textbf{iconIndex} \texttt{- optional}\\ |
308 |
|
309 |
If the file type for the icon supports multiple icons in one file, then |
310 |
this attribute may be used to specify the correct index for the icon. I |
311 |
would also advise against using this feature, because of operating |
312 |
system incompatibilities in this area. In file formats that do not |
313 |
support multiple icons, this values is ignored.\\ |
314 |
|
315 |
\textbf{initialState} \texttt{- optional}\\ |
316 |
|
317 |
There are four values accepted for this attribute: \texttt{noShow}, |
318 |
\texttt{normal}, \texttt{maximized} and \texttt{minimized}. If the |
319 |
target operating system supports this feature, then this value will have |
320 |
the appropriate influence on the initial window state of the |
321 |
application. \texttt{noShow} is particularly useful when launch scripts |
322 |
are used that cause a command window to open, because the command window |
323 |
will not be visible with this option. For instance on MS-Windows |
324 |
starting a batch file that launches a Java application has the less than |
325 |
pretty side effect that two windows show: the DOS command prompt and the |
326 |
Java application window. Even if the shortcut is configured to show |
327 |
minimized, there are buttons for both windows in the task bar. Using |
328 |
\texttt{noShow} will completely eliminate this effect, only the Java |
329 |
application window will be visible. \textit{On Unix use } \texttt{normal} |
330 |
\textit{, because this is not supported}.\\ |
331 |
|
332 |
\textbf{programGroup} \texttt{- semi-optional}\\ |
333 |
|
334 |
The value for this attribute can be either yes or no. Any other value |
335 |
will be interpreted as no. If the value is yes, then a copy of this |
336 |
shortcut will be placed in the group menu. |
337 |
\textit{On Unix (KDE) this will always be placed on the top level.}\\ |
338 |
|
339 |
\textbf{desktop} \texttt{- semi-optional}\\ |
340 |
|
341 |
For this attribute the value should also be yes or no. If the value is |
342 |
yes, then a copy of the shortcut is placed on the desktop. |
343 |
\textit{On Unix the shortcuts will only be placed on the (KDE-) desktop |
344 |
of the user, who currently runs the installer. For Gnome the user can |
345 |
simply copy the *.desktop files from } \texttt{\~/Desktop} \textit{ to } |
346 |
\texttt{\~/gnome-desktop}. |
347 |
(This is already a TODO for the Unix-shortcut implementation.)\\ |
348 |
|
349 |
\textbf{applications} \texttt{- semi-optional}\\ |
350 |
|
351 |
This is also a yes/no attribute. If the value is yes, then a copy of the |
352 |
shortcut is placed in the applications menu (if the target operating |
353 |
system supports this). This is the same location as the applications |
354 |
choice for the program group. |
355 |
\textit{This makes no sense on Unix.}\\ |
356 |
|
357 |
\textbf{startMenu} \texttt{- semi-optional}\\ |
358 |
|
359 |
This is a yes/no attribute as well. If the value is yes, then a copy of |
360 |
the shortcut is placed directly in the top most menu that is available |
361 |
for placing application shortcuts. |
362 |
\textit{This is not supported on Unix. see above.}\\ |
363 |
|
364 |
\textbf{startup} \texttt{- semi-optional}\\ |
365 |
|
366 |
This is also a yes/no attribute. If the value is yes, then a copy of the |
367 |
shortcut is placed in a location where all applications get automatically |
368 |
started at OS launch time, if this is available on the target OS. |
369 |
\textit{This is also not supported on Unix.}\\ |
370 |
|
371 |
\subsubsection{Unix specific shortcut attributes } |
372 |
|
373 |
This extension was programmed by \textsc{Marc Eppelmann}. |
374 |
This is still in development and may be changed in |
375 |
one of the next releases of IzPack.\\ |
376 |
|
377 |
\textbf{type} \texttt{- required}\\ |
378 |
|
379 |
This must be one of \texttt{Application} or \texttt{Link}\\ |
380 |
|
381 |
\begin{itemize} |
382 |
|
383 |
\item Application: To start any application, native, Java or shell-script based, |
384 |
the \textbf{type} has to be \texttt{Application}. The GUI-System will launch |
385 |
this Application, so as is, thru their native shell or application launcher. |
386 |
In this case, note that the right \texttt{workingDirectory} |
387 |
is always important on Unix platforms. If the users PATH environment |
388 |
variable does not contain the path, where the application is located, |
389 |
this can never be run, until the \texttt{workingDirectory} does not contain |
390 |
these path. The needed current path: ".", this is the case on most |
391 |
systems, should be in the users PATH environment variable. |
392 |
Consult the Unix manuals for more details. |
393 |
|
394 |
\item Link: If you want to open a URL in the users default Webbrowser, |
395 |
you have to set the \textbf{type} to \texttt{Link}. Note: The \texttt{url} attribute |
396 |
must be set to work properly. |
397 |
|
398 |
\item Other: There are more supported types on KDE, like FSDevice, |
399 |
but these types makes no sense for IzPack, in my opinion. |
400 |
\end{itemize} |
401 |
|
402 |
Without the type the Unix shortcut does not work.\\ |
403 |
|
404 |
\textbf{url} \texttt{- semi-optional}\\ |
405 |
|
406 |
If you want to create a shortcut as type \textit{Link}, then you have |
407 |
to set the \texttt{url} attribute. The value can be a locally installed |
408 |
html or another document, with a known MIME type, like plain text, |
409 |
or a WWW Url i.e. 'http://www.izforge.com/izpack'.\\ |
410 |
|
411 |
A local document can be referenced by i.e. "\$INSTALL\_PATH/doc/index.html".\\ |
412 |
|
413 |
The IzPack variable substitution system is supported by the \textbf{url}.\\ |
414 |
|
415 |
\textbf{encoding} \texttt{- required}\\ |
416 |
|
417 |
This should always set to \textbf{UTF-8}.\\ |
418 |
|
419 |
\textbf{terminal} \texttt{- optional}\\ |
420 |
|
421 |
If you want, the user can see the console output of a program |
422 |
(in Java applications "System.outs"), set the \texttt{terminal} attribute to \textbf{true}.\\ |
423 |
|
424 |
\textbf{KdeSubstUID} \texttt{- unused}\\ |
425 |
|
426 |
This is not fully implemented by IzPack. |
427 |
I the future this is the sudo option for a shortcut.\\ |
428 |
|
429 |
\subsection{Selective Creation of Shortcuts} |
430 |
|
431 |
Usually all shortcuts that are listed will be created when the user |
432 |
clicks the 'Next' button. However it is possible to |
433 |
control to some degree if specific shortcuts should be created or |
434 |
not. This is based on install conditions. By including one or more |
435 |
\texttt{<createForPack name=''a pack name'' />} tags in the |
436 |
specification for a shortcut, you can direct the ShortcutPanel to |
437 |
create the shortcut only if any of the listed packs are actually |
438 |
installed. The 'name' attribute is used to define the name of one of |
439 |
the packs for which the shortcut should be created. You do not need to |
440 |
list all packs if a shortcut should always be created. In this case |
441 |
simply omit this tag altogether.\\ |
442 |
|
443 |
\textbf{A word of caution}\\ |
444 |
|
445 |
For any shortcut that is always created, I would recommend to omit this |
446 |
tag, since I have seen a number of problems related to changing pack |
447 |
names. You can save yourself some troubleshooting and some Aspirin by |
448 |
not using this feature if it's not required. On the other hand if you |
449 |
need it I would advise to be very careful about changing pack names.\\ |
450 |
|
451 |
\subsection{Summary} |
452 |
|
453 |
\textbf{Native Libraries} |
454 |
\begin{itemize} |
455 |
\item ShellLink.dll \texttt{- required by Microsoft Windows} |
456 |
\item 'Nothing' \texttt{- for KDE/Gnome shortcuts} |
457 |
\end{itemize}\ |
458 |
|
459 |
\textbf{Names of the Specification Files}\\ |
460 |
\texttt{shortcutSpec.xml} for Windows and as default.\\ |
461 |
\texttt{Unix\_shortcutSpec.xml} for Unix.\\ |
462 |
|
463 |
\textbf{Specification File Layout - Windows} |
464 |
\footnotesize |
465 |
|
466 |
\begin{verbatim} |
467 |
<shortcuts> |
468 |
<skipIfNotSupported/> |
469 |
<programGroup defaultName="MyOrganization\MyApplication" |
470 |
location="applications||startMenu"/> |
471 |
<shortcut |
472 |
name="Start MyApplication" |
473 |
target="$INSTALL_PATH\Path\to\MyApplication\launcher.bat" |
474 |
commandLine="" |
475 |
workingDirectory="$INSTALL_PATH\Path\to\MyApplication" |
476 |
description="This starts MyApplication" |
477 |
iconFile="$INSTALL_PATH\Path\to\MyApplication\Icons\start.ico" |
478 |
iconIndex="0" |
479 |
initialState="noShow||normal||maximized||minimized" |
480 |
programGroup="yes||no" |
481 |
desktop="yes||no" |
482 |
applications="yes||no" |
483 |
startMenu="yes||no" |
484 |
startup="yes||no"> |
485 |
|
486 |
<createForPack name="MyApplication Binaries"/> |
487 |
<createForPack name="MyApplication Batchfiles"/> |
488 |
</shortcut> |
489 |
</shortcuts> |
490 |
\end{verbatim} |
491 |
\normalsize |
492 |
|
493 |
\textbf{A sample Specification File for Unix is at the end of this chapter} |
494 |
|
495 |
\section{Shortcut Tips} |
496 |
|
497 |
I wrote this section to provide additional information about issues |
498 |
surrounding the creation of shortcuts. Reading this section is not |
499 |
necessary to successfully create shortcuts, but it might help you |
500 |
creating an installation that works more smoothly. In addition, it might |
501 |
give you some knowledge about operating systems that you don't know so |
502 |
well. In fact most of the issues described in this section are focused |
503 |
on differences in operating system specifics.\\ |
504 |
|
505 |
\subsection{The Desktop} |
506 |
|
507 |
You should recognize that the desktop is precious real estate for many |
508 |
people. They like to keep it uncluttered and keep only the things there |
509 |
that they use on a regular basis. This is not true for everybody and you |
510 |
might personally think different about this. Still, the fact remains |
511 |
that a lot of people might have different feelings about it, so you |
512 |
should not automatically assume that it is ok to place all of your |
513 |
shortcuts on the desktop proper. While your application is certainly one |
514 |
of the most important things for you, for your customers it is probably |
515 |
one of many applications they use and maybe not even the most important |
516 |
one. Accordingly, placing more shortcut icons there than they feel they |
517 |
will use on a regular basis and especially doing this without asking for |
518 |
permission might trigger some bad temper.\\ |
519 |
|
520 |
Annotation: But even the experienced user should be able to organize their Desktop. |
521 |
On Linux the users desktop is the only place, which supports any kind of shortcuts.\\ |
522 |
|
523 |
It is common practice to create a program group in the application menu |
524 |
system of the OS and place all shortcuts that go with an application in |
525 |
that program group. In addition, only one shortcut to the key access |
526 |
point of the application is placed directly on the desktop. Many |
527 |
installers first ask for permission to do so, as does the ShortcutPanel |
528 |
in IzPack.\\ |
529 |
|
530 |
I would like to recommend that you always create a shortcut in the menu |
531 |
system, even if your application has only one access point and you are |
532 |
placing this on the desktop. Note that shortcuts can also be placed directly |
533 |
in the menu, they don't need to be in a program group. There are two |
534 |
reasons for doing so.\\ |
535 |
|
536 |
\begin{itemize} |
537 |
\item If the user elects not to create shortcuts on the desktop, they |
538 |
will end up with no access point to your application |
539 |
\item Even if this works fine, occasionally people 'clean up' their |
540 |
desktop. They might later find that they accidentally deleted the |
541 |
only access point to your application. For the less technology |
542 |
savvy users, recreating the shortcut might be a rough experience. |
543 |
\end{itemize} |
544 |
|
545 |
\subsection{Icons} |
546 |
|
547 |
Icons are supplied in image files, usually in some kind of bitmap |
548 |
format. Unfortunately there is no format that is universally recognized |
549 |
by all operating systems. If you would like to create shortcuts on a |
550 |
variety of operating systems that use your own icons, you must supply |
551 |
each icon in a number of different formats. This chapter discusses icon |
552 |
file formats used on various operating systems. Fortunately there are |
553 |
good programs available that allow you to convert between these formats, |
554 |
so that creating the different files is not much of a problem once the |
555 |
icons themselves are created.\\ |
556 |
|
557 |
\textbf{Microsoft Windows}\\ |
558 |
|
559 |
Windows prefers to use its native icon file format. Files of this type |
560 |
usually use the extension *.ico. These so called ICO files can hold |
561 |
multiple icons in one file, which can be useful if the same icon is |
562 |
to be provided in a number of sizes and color-depths. |
563 |
|
564 |
Windows itself selects the icon with the most matching dimensions and displays it. |
565 |
While the Start menu displays the icon with 16x16 pixel if available, the desktop displays |
566 |
the 32x32 pixel resolution of the same ICO if this is in. |
567 |
|
568 |
In other words, a ICO file has embedded one or more dimensions of the same Icon. |
569 |
We recommend to play with \href{http://www.microangelo.us}{microangelo}. |
570 |
|
571 |
Dlls and Exe files on the other side, can store, amongst other things, a collection of different Icons. |
572 |
You can select your desired Icon by its index. The lowest index is 0. |
573 |
Use the iconIndex attribute in the spec file to specify this index.\\ |
574 |
|
575 |
As a sample look into |
576 |
\begin{verbatim} |
577 |
%SystemRoot%\system32\shell32.dll |
578 |
\end{verbatim} |
579 |
These contains a lot of Windows own icons. |
580 |
You can use the \href{http://www.heaventools.com}{PE Explorer} |
581 |
or another Resource Editor to extract or modify |
582 |
Icons in dlls or exe files. But be warned. You can also destroy a working |
583 |
application with these kind of tools. |
584 |
|
585 |
At least Windows also supports the use of bitmap files in the *.bmp format as |
586 |
icons. Note that this format does not support multiple icons.\\ |
587 |
|
588 |
We might have overlooked other file formats that are supported by Windows. |
589 |
However, we suggest to test other formats for compatibility as they |
590 |
might not work all the way back to Windows 95 or on the NT/non-NT strain. |
591 |
Sticking with one of these two formats should keep you out of trouble.\\ |
592 |
|
593 |
\textbf{Apple}\\ |
594 |
|
595 |
Apple Macintosh systems use the Macintosh PICT format, extension *.pct. |
596 |
If you are working with an apple system you know a whole lot more about |
597 |
this format than I do. If you don't but would like to be able to install |
598 |
your application on a Mac, simply start with any bitmap format that you |
599 |
feel comfortable to work with. Then find an application that is capable |
600 |
of converting this format into a *.pct file. I like to use Paint Shop |
601 |
Pro (PC based), because it provides conversion capabilities among |
602 |
several dozen different file formats.\\ |
603 |
|
604 |
\textbf{UNIX flavors}\\ |
605 |
|
606 |
by Marc Eppelmann\\ |
607 |
|
608 |
As my knowledge, all X based Unix Window systems supports |
609 |
the (ASCII-) XBM (X-Bitmap ) and the better XPM (X-PixMap) format. |
610 |
The modern GUI systems like KDE and Gnome can display additionally |
611 |
a lot of other ImageIcon formats, such as GIF, JPG, and PNG.\\ |
612 |
|
613 |
I suggest to use PNG, because this can lossless compress like the GIF format, |
614 |
however this format is absolutely free. And not least, this can store true |
615 |
transparency informations (It has an alpha channel). |
616 |
|
617 |
\subsection{Targets} |
618 |
|
619 |
So, you thought you could escape the ugly mess of operating system |
620 |
dependencies at least with the way how your Java application is started? |
621 |
Sorry but I have just another bad message. The one positive thing is |
622 |
that here you have a way of escaping, even if doing so has a few less |
623 |
pretty side effects. At first, I would like to discuss various launching |
624 |
options you have available on different operating systems. At the end of |
625 |
the chapter I write about a way to make launching your application OS |
626 |
independent.\\ |
627 |
|
628 |
\textbf{Microsoft Windows}\\ |
629 |
|
630 |
On Microsoft Windows you have a variety of options for launching your |
631 |
application. Probably the most simple case is directly starting the Java |
632 |
VM from the command line and typing out all parameters, such as class |
633 |
path, the class name etc. In principle, this can be placed right in a |
634 |
shortcut and should work.\\ |
635 |
|
636 |
A little more elegant solution is to place this in a batch file and have |
637 |
the shortcut point to this batch file. This will also make it more |
638 |
likely that users can repair or recreate shortcuts. Recreating shortcuts |
639 |
with sophisticated command lines is practically impossible.\\ |
640 |
|
641 |
Another method is less commonly used but just as possible. Implement a |
642 |
native executable that launches the VM with your Java application. The |
643 |
VM comes as DLL and is used by java.exe in just the same way. |
644 |
As a sample look at the exlipse.exe provided by the \href{http://www.eclipse.org}{Eclipse-IDE}\\ |
645 |
|
646 |
Clearly, even though the first option is a bit ugly and has some |
647 |
restrictionss, it is the most portable solution among the three.\\ |
648 |
|
649 |
\textbf{Apple}\\ |
650 |
|
651 |
We hope, there is a IzPack developer currently researching |
652 |
for the details for the Mac environment. We expect |
653 |
an updated chapter in one of the next releases.\\ |
654 |
|
655 |
\textbf{UNIX}\\ |
656 |
|
657 |
UNIX provides essentially the same options as Windows. You can simply |
658 |
use the command line option, you can write a shell script and you can |
659 |
write a native launcher. Naturally this stuff is in no way compatible |
660 |
with the equivalent Windows implementations. The native option is even |
661 |
more problematic in this environment, since the code can not even be |
662 |
moved from one UNIX platform to another, without recompilation.\\ |
663 |
|
664 |
\textbf{OS Independent Launching}\\ |
665 |
|
666 |
So, after all this rather discouraging news, there is actually a |
667 |
portable way to launch Java applications? You bet! although I have to |
668 |
admit that it is not necessarily the most pretty way of doing things.\\ |
669 |
|
670 |
This approach is currently used by IzPack. Package your application in a |
671 |
*.jar file if you don't already do so and make it executable by including the |
672 |
necessary METAINF/MANIFEST.MF information file. I am not |
673 |
going into all the details on how exactly to do this, the Java |
674 |
documentation will have to do. You might have noticed that even though |
675 |
the instructions to install IzPack say to type : |
676 |
\begin{verbatim} |
677 |
java -jar IzPack-install.jar |
678 |
\end{verbatim} |
679 |
|
680 |
You can just as well double click on IzPack-install.jar and it will |
681 |
start up. This procedure will work on all GUI based Java supported operating |
682 |
systems -though you might have to replace double clicking with dropping |
683 |
the file on the VM. In just the same way, you can make the *.jar file |
684 |
itself the target of a shortcut. Note: This works only, if jars are registered |
685 |
as files, which have to launch by the installed JRE (with: javaw.exe -jar *)\\ |
686 |
|
687 |
The one restriction with this approach is that a *.jar file can only have |
688 |
one main file. So, if you have multiple targets, they need to be |
689 |
packaged each into a different *.jar file. They can be in one *.jar file |
690 |
but then you have to start them explicitly, which gets you back to the |
691 |
problems that I mentioned before. This brings me to the ugly part. If |
692 |
you have just one target, then you are all set. If you have multiple |
693 |
targets, you need to create a *.jar file for each of them. In addition, |
694 |
you have a much harder time setting the classpath, because each of the |
695 |
*.jar files that contain supporting code must be listed. In fact, at |
696 |
present there is no way of setting this during the installation, because |
697 |
IzPack does not yet (version 3.0) support the setting and modification |
698 |
of environment variables.\\ |
699 |
|
700 |
\subsection{Command Line} |
701 |
|
702 |
Before I start to write a lot about the use of command line arguments |
703 |
let me state this: If you can avoid using them, do it! Not that there |
704 |
is anything wrong with command line arguments as such. The issue is |
705 |
simply that if you want your application to be usable cross platform |
706 |
(the big Java promise) you should shy away from using command line |
707 |
arguments. The problem here is that not all operating systems actually |
708 |
support command line arguments. To be more precise, to my knowledge only |
709 |
Apple operating systems do not support command line parameters. If you |
710 |
don't care for running your application on a Mac, then you might not |
711 |
worry about his at all. If you are interested to support the Mac as |
712 |
well, read on.\\ |
713 |
|
714 |
In fact the Mac lower than MacOSX supports command line parameters in a way. |
715 |
More to the point, it supports a single parameter that your application should |
716 |
interpret as the name of a data file to open. You have no way of |
717 |
supplying this to your application through the command line attribute. |
718 |
The operating system generates this when the user drops the file on your |
719 |
application and then passes it as command line argument. That's it. This |
720 |
same behavior will probably fly well on pretty much any system and |
721 |
should therefore be an ok implementation.\\ |
722 |
|
723 |
So what to do if you want to modify program behavior based on runtime |
724 |
switches? For one thing, you could set system properties accordingly. |
725 |
The disadvantage here is the same as with the command line parameters: the |
726 |
way of setting these might vary between operating systems. The best way |
727 |
seems to be using a property file that contains the configuration |
728 |
data.\\ |
729 |
|
730 |
\section{Trouble Shooting} |
731 |
|
732 |
by Elmar |
733 |
|
734 |
It has been some time since I wrote this chapter during which a good |
735 |
number of users had a chance to gather experience. Unfortunately I |
736 |
never know how many have used it successfully without much difficulty. I |
737 |
only hear from those that have encountered one problem or another. The |
738 |
type of problems that I have seen prompted me to write this section, |
739 |
because I think it will help you in locating most problems that you might |
740 |
encounter or at least give you some idea where the problem might be |
741 |
located.\\ |
742 |
|
743 |
\subsection{Problems You Can Solve} |
744 |
|
745 |
If you see an exception that essentially says that a library can not be |
746 |
loaded (ShellLink.dll) you have an easy problem to deal with. Your |
747 |
installer file is probably missing the native tag that adds the Windows |
748 |
dll to the installer or something with this tag is no quite right. Read |
749 |
'What to Add to the Installer' for all details on this topic.\\ |
750 |
|
751 |
Most other problems cause the ShortcutPanel not to show at all during |
752 |
the installation process. The reason is simply that the ShortcutPanel |
753 |
skips if it does not know what to do or if it has nothing to do (no |
754 |
point showing then and confusing the user). The problem is that this is |
755 |
not always what you intended. The most simple but not so uncommon |
756 |
case is, that the ShortcutPanel cannot find their spec file. This can be caused by |
757 |
a number of reasons. The associated resource tag might be missing in the |
758 |
installer specification file, the target file name might be misspelled (the |
759 |
name you specify for the \texttt{id} attribute) or the target file name |
760 |
has a path or package name pre-pended. You have only to use |
761 |
\texttt{shortcutSpec.xml} or \texttt{Unix\_shortcutSpec.xml} and nothing else, |
762 |
just as described in 'What to Add to the Installer'. |
763 |
You can always verify if this part is ok by |
764 |
inspecting the content of the installer *.jar file. The file |
765 |
shortcutSpec.xml should be located in the directory \texttt{res}. This |
766 |
inspection can be performed with any zip tool. If the file is not there, |
767 |
first correct this before proceeding.\\ |
768 |
|
769 |
If the file is there and the panel does not appear, you have a problem |
770 |
within the specification file. In most cases that I have seen, it comes |
771 |
down to a spelling mistake of an attribute or tag name. You just have to |
772 |
carefully make sure that everything is spelled correctly. Don't forget |
773 |
that all names are case sensitive! In a few cases it is also happend, |
774 |
that required or semi-optional attributes are omitted, so you might want |
775 |
to verify if all attributes that you need are actually supplied.\\ |
776 |
|
777 |
If everything is correct up to this point the problem becomes more |
778 |
elusive. Most likely the panel will not be displayed, because it is instructed |
779 |
not to show. There are be several reasons for this. The simple |
780 |
case is that no location has been specified for the shortcuts in your |
781 |
installation. This can happen if all five location attributes are |
782 |
omitted or if all the ones that are listed are set to \texttt{no}. |
783 |
Remember, you have to specify at least one location for every shortcut. If |
784 |
this is also correct, you might have used the \texttt{<createForPack>} tag. Review |
785 |
the details in 'Selective Creation of Shortcuts'. One possibility for |
786 |
the panel not to show is that based on the packs that are currently |
787 |
selected for installation no shortcut qualifies for creation. In this |
788 |
case the panel will not show, this is perfectly normal behavior. More |
789 |
likely this condition is true because of some accident and not because |
790 |
it's intended. Make sure the packs that you list for the shortcut are |
791 |
actually defined in your installation and verify that they are all |
792 |
spelled correctly. Remember: case matters! Did the ShortcutPanel use to |
793 |
work in your installation and all of a sudden stopped working? Very |
794 |
likely you are dealing with the last problem. A package name might have |
795 |
been modified and the shortcut spec was not adjusted to stay in sync.\\ |
796 |
|
797 |
\subsection{Problems That Have No Solution (yet)} |
798 |
|
799 |
Unfortunately one problem has been very persistent and only recently one |
800 |
user found the reason. The problem occurs when installing on some target |
801 |
systems where non-English characters are used in the storage path for |
802 |
the shortcuts. The problem is that these characters don't seem to be |
803 |
properly translated across the Java Native Interface. This leads to a |
804 |
situation where the proper path can not be located and the shortcut |
805 |
creation fails. I write 'some target systems' because it does not fail |
806 |
everywhere. After much agonizing over this problem, one user found the |
807 |
solution: The shortcut creation works fine if a Sun virtual machine is |
808 |
installed, but fails if a version from IBM happens to be installed. So |
809 |
far I have no solution for this problem but I am trying to find a |
810 |
workaround the problem.\\ |
811 |
|
812 |
\subsection{A sample shortcut specification file for Unix} |
813 |
|
814 |
\footnotesize |
815 |
\begin{verbatim} |
816 |
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> |
817 |
|
818 |
<shortcuts> |
819 |
|
820 |
<programGroup defaultName="IzForge/IzPack" location="applications"/> |
821 |
|
822 |
<!-- Disabled since there is no Frontend |
823 |
shortcut |
824 |
name="IzPack" |
825 |
programGroup="yes" |
826 |
desktop="yes" |
827 |
applications="no" |
828 |
startMenu="yes" |
829 |
startup="no" |
830 |
target="$INSTALL_PATH/bin/izpack-fe.sh" |
831 |
commandLine="" |
832 |
workingDirectory="$INSTALL_PATH/bin" |
833 |
description="Front-End for IzPack installation tool" |
834 |
iconFile="$INSTALL_PATH/bin/icons/izpack.png" |
835 |
iconIndex="0" |
836 |
type="Application" |
837 |
encoding="UTF-8" |
838 |
terminal="true" |
839 |
KdeSubstUID="false" |
840 |
initialState="normal"> |
841 |
<createForPack name="Core"/> |
842 |
</shortcut --> |
843 |
|
844 |
<shortcut |
845 |
name="IzPack Documentation" |
846 |
programGroup="yes" |
847 |
desktop="yes" |
848 |
applications="no" |
849 |
startMenu="yes" |
850 |
startup="no" |
851 |
target="konqueror" |
852 |
workingDirectory="" |
853 |
commandLine="" |
854 |
initialState="noShow" |
855 |
iconFile="help" |
856 |
iconIndex="0" |
857 |
url="$INSTALL_PATH/doc/izpack/html/izpack-doc.html" |
858 |
type="Link" |
859 |
encoding="UTF-8" |
860 |
description="IzPack user documentation (HTML format)"> |
861 |
|
862 |
<createForPack name="Documentation-HTML"/> |
863 |
</shortcut> |
864 |
|
865 |
<shortcut |
866 |
name="Documentation" |
867 |
programGroup="yes" |
868 |
desktop="yes" |
869 |
applications="no" |
870 |
startMenu="yes" |
871 |
startup="no" |
872 |
target="acroread" |
873 |
workingDirectory="" |
874 |
commandLine="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf" |
875 |
initialState="noShow" |
876 |
iconFile="acroread" |
877 |
iconIndex="0" |
878 |
url="$INSTALL_PATH/doc/izpack/pdf/izpack-doc.pdf" |
879 |
type="Application" |
880 |
encoding="UTF-8" |
881 |
description="IzPack user documentation (PDF format)"> |
882 |
|
883 |
<createForPack name="Documentation-PDF"/> |
884 |
</shortcut> |
885 |
|
886 |
<shortcut |
887 |
name="Uninstaller" |
888 |
programGroup="yes" |
889 |
desktop="yes" |
890 |
applications="no" |
891 |
startMenu="no" |
892 |
startup="no" |
893 |
target="/usr/lib/java/bin/java" |
894 |
commandLine="-jar "$INSTALL_PATH/Uninstaller/uninstaller.jar"" |
895 |
initialState="noShow" |
896 |
iconFile="trashcan_full" |
897 |
iconIndex="0" |
898 |
workingDirectory="" |
899 |
type="Application" |
900 |
encoding="UTF-8" |
901 |
description="IzPack uninstaller"> |
902 |
<createForPack name="Core" /> |
903 |
</shortcut> |
904 |
|
905 |
</shortcuts> |
906 |
|
907 |
\end{verbatim} |
908 |
\normalsize |