svn-gvsig-desktop / tags / v1_1_2_Build_1042 / install / IzPack / src / doc / chapter2.tex @ 42158
History | View | Annotate | Download (43.1 KB)
1 |
% Chapter 2 |
---|---|
2 |
\chapter{Writing Installation XML Files} |
3 |
|
4 |
% What you need |
5 |
\section{What You Need} |
6 |
|
7 |
\subsection{Your editor} |
8 |
|
9 |
In order to write your XML installation files, you just need a plain |
10 |
text editor. Of course it's always easier to work with color coded text, |
11 |
so you might rather want to work with a text editor having such a |
12 |
feature. Here is a list of free editors that work well : |
13 |
\begin{itemize} |
14 |
\item Jext : \url{http://www.jext.org/} |
15 |
\item JEdit : \url{http://www.jedit.org/} |
16 |
\item classics like Vim and (X)Emacs. |
17 |
\end{itemize}\ |
18 |
|
19 |
\subsection{Writing XML} |
20 |
|
21 |
Though you might not know much about XML, you have certainly heard about |
22 |
it. If you know XML you can skip this subsection as we will briefly |
23 |
present how to use XML.\\ |
24 |
|
25 |
XML is a markup language, really close to HTML. If you've ever worked |
26 |
with HTML the transition will be fast. However there are a few little |
27 |
things to know. The markups used in XML have the following form : |
28 |
\texttt{<markup>}. Each markup has to be closed somewhere with its |
29 |
ending tag : \texttt{</markup>}. Each tag can contain text and other |
30 |
markups. If a markup does not contain anything, it is just reported once |
31 |
: \texttt{<markup/>}. A markup can contain attributes like : |
32 |
\texttt{<markup attr1="123" attr2="hello !"/>}. Here is a sample of a |
33 |
valid XML structure : |
34 |
\footnotesize |
35 |
\begin{verbatim} |
36 |
<chapter title="Chapter 1"> |
37 |
<section name="Introduction"> |
38 |
<paragraph> |
39 |
This is the text of the paragraph number 1. It is available for the very low |
40 |
price of <price currency="dollar">1 000 000</price>. |
41 |
</paragraph> |
42 |
</section> |
43 |
<section name="xxx"> |
44 |
xxx |
45 |
</section> |
46 |
</chapter> |
47 |
\end{verbatim} |
48 |
\normalsize |
49 |
|
50 |
You should be aware of the following common mistakes : |
51 |
\begin{itemize} |
52 |
|
53 |
\item markups \textbf{are} case sensitive : \texttt{<markup>} is different |
54 |
from \texttt{<Markup>}. |
55 |
|
56 |
\item you \textbf{must} close the markups in the same order as you create them |
57 |
: \texttt{<m1><m2>(...)</m2></m1>} is right but |
58 |
\texttt{<m1><m2>(...)</m1></m2>} is not. |
59 |
|
60 |
\end{itemize} |
61 |
|
62 |
Also, an XML file must start with the following header :\\ |
63 |
\texttt{<?xml version="1.0" encoding="iso-8859-1 standalone="yes" ?>}. The only |
64 |
thing you should modify is the encoding (put here the one your text editor saves |
65 |
your files to). The \texttt{standalone} attribute is not very important for |
66 |
us.\\ |
67 |
|
68 |
This (brief !) introduction to XML was just meant to enable you to write |
69 |
your installation specification. For a better introduction there are |
70 |
plenty of books and articles/tutorials dealing with XML on the Internet, |
71 |
in book stores, in magazines and so on.\\ |
72 |
|
73 |
% Built-in variables |
74 |
\section{Variable Substitution} |
75 |
|
76 |
During the installation process IzPack can substitute variables in |
77 |
various places with real values. Obvious targets for variable |
78 |
substitution are resource files and launch scripts, however you will |
79 |
notice many more places where it is more powerful to use variables |
80 |
rather then hard coded values. Wherever variables can be used it will |
81 |
be explained in the documentation.\\ |
82 |
|
83 |
There are three types of variables: |
84 |
\begin{itemize} |
85 |
\item Built-In variables. These are implemented in IzPack and are |
86 |
all dynamic in nature. This means that the value of each |
87 |
variable depends on local conditions on the target system. |
88 |
\item Environment variables. These are provided by the operating system the |
89 |
installer is run on. |
90 |
\item Variables that you can define. You also define the value, |
91 |
which is fixed for a given installation file. |
92 |
\end{itemize} |
93 |
|
94 |
You define your own variables in the installation XML file with the |
95 |
\texttt{<variable>} tag. How to do this is explained in detail later in |
96 |
this chapter.\\ |
97 |
|
98 |
\textbf{Please note} that when using variables they must always appear |
99 |
with a '\texttt{\$}' sign as the first character, even though they are |
100 |
not defined this way.\\ |
101 |
|
102 |
\subsection{The Built-In Variables} |
103 |
The following variables are built-in : |
104 |
\begin{itemize} |
105 |
\item \texttt{\$INSTALL\_PATH} : the installation path on the |
106 |
target system, as chosen by the user |
107 |
\item \texttt{\$JAVA\_HOME} : the \Java virtual machine home path |
108 |
\item \texttt{\$USER\_HOME} : the user's home directory path |
109 |
\item \texttt{\$USER\_NAME} : the user name |
110 |
\item \texttt{\$APP\_NAME} : the application name |
111 |
\item \texttt{\$APP\_URL} : the application URL |
112 |
\item \texttt{\$APP\_VER} : the application version |
113 |
\item \texttt{\$ISO3\_LANG} : the ISO3 language code of the selected langpack. |
114 |
\item \texttt{\$FILE\_SEPARATOR} : the file separator on the installation system |
115 |
\end{itemize}\ |
116 |
|
117 |
\subsection{Environment Variables} |
118 |
Environment variables can be accessed via the syntax \texttt{\$\{ENV[variable]\}}. |
119 |
The curly braces are mandatory. |
120 |
Note that variable names are case-sensitive and usually in UPPER CASE. |
121 |
|
122 |
Example: To get the value of the OS environment variable "CATALINA\_HOME", use \texttt{\$\{ENV[CATALINA\_HOME]\}}. |
123 |
|
124 |
\subsection{Parse Types} |
125 |
Parse types apply only when replacing variables in text files. At places |
126 |
where it might be necessary to specify a parse type, the documentation |
127 |
will mention this. Depending on the parse type, IzPack will handle |
128 |
special cases -such as escaping control characters- correctly. The |
129 |
following parse types are available: |
130 |
\begin{itemize} |
131 |
\item \texttt{plain} - use this type for plain text files, where no |
132 |
special substitution rules apply. All variables will be |
133 |
replaced with their respective values as is. |
134 |
\item \texttt{javaprop} - use this type if the substitution happens |
135 |
in a Java properties file. Individual variables might be |
136 |
modified to function properly within the context of Java |
137 |
property files. |
138 |
\item \texttt{xml} - use this type if the substitution happens in |
139 |
a XML file. Individual variables might be modified to function |
140 |
properly within the context of XML files. |
141 |
\item \texttt{shell} - use this type if the substitution happens in |
142 |
a shell script. Because shell scripts use \texttt{\$variable} |
143 |
themselves, an alternative variable marker is used: |
144 |
\texttt{\%variable} or \texttt{\%\{variable\}}. |
145 |
\end{itemize} |
146 |
|
147 |
% The IzPack elements |
148 |
\section{The \IzPack Elements} |
149 |
|
150 |
\noindent |
151 |
\textit{When writing your installer XML files, it's a good idea to have a look |
152 |
at the \IzPack installation DTD}.\\ |
153 |
|
154 |
\subsection{The Root Element \texttt{<installation>}} |
155 |
\label{root-element} |
156 |
|
157 |
The root element of an installation is \texttt{<installation>}. It takes |
158 |
one required attribute : \texttt{version}. The attribute defines the |
159 |
version of the XML file layout and is used by the compiler to identify |
160 |
if it is compatible with the XML file. This should be set to $1.0$ for |
161 |
the moment.\\ |
162 |
|
163 |
\subsection{The Information Element \texttt{<info>}} |
164 |
\label{info-element} |
165 |
|
166 |
This element is used to specify some general information for the installer. It |
167 |
contains the following elements : |
168 |
\begin{itemize} |
169 |
|
170 |
\item \texttt{<appname>} : the application name |
171 |
\item \texttt{<appversion>} : the application version |
172 |
\item \texttt{<appsubpath>} : the subpath for the default of the installation path. |
173 |
A variable substitution and a maskable slash-backslash conversion will be done. If this |
174 |
tag is not defined, the application name will be used instead. |
175 |
\item \texttt{<url>} : the application official website url |
176 |
\item \texttt{<authors>} : specifies the author(s) of the application. It must contain |
177 |
at least one \texttt{<author>} element whose attributes are : |
178 |
\begin{itemize} |
179 |
\item \texttt{name} : the author's name |
180 |
\item \texttt{email} : the author's email |
181 |
\end{itemize} |
182 |
\item \texttt{<uninstaller>} : specifies whether to create an uninstaller after installation, it has only the \texttt{write} attribute, with default value \texttt{yes}. If this tag is not specified, the uninstaller will still be written. |
183 |
\item \texttt{<javaversion>} : specifies the minimum version of Java required to install your program. Values can be \texttt{1.2}, \texttt{1.2.2}, \texttt{1.4}, etc. The test is a lexical comparison against the \texttt{java.version} System property on the install machine. |
184 |
\item \texttt{<webdir>} : Causes a ``web installer'' to be created, and specifies the URL packages are retrieved from at install time. The content of the tag must be a properly formed URL. See section~\ref{webinstaller} for more details. |
185 |
|
186 |
\end{itemize}\ |
187 |
|
188 |
Here is an example of a typical \texttt{<info>} section :\\ |
189 |
\footnotesize |
190 |
\begin{verbatim} |
191 |
<info> |
192 |
<appname>Super extractor</appname> |
193 |
<appversion>2.1 beta 6</appversion> |
194 |
<appsubpath>myCompany/SExtractor</appsubpath> |
195 |
<url>http://www.superextractor.com/</url> |
196 |
<authors> |
197 |
<author name="John John Doo" email="jjd@jjd-mail.com"/> |
198 |
<author name="El Goyo" email="goyoman@mymail.org"/> |
199 |
</authors> |
200 |
<javaversion>1.2</javaversion> |
201 |
</info> |
202 |
\end{verbatim} |
203 |
\normalsize |
204 |
|
205 |
\subsection{The Variables Element \texttt{<variables>}} |
206 |
\label{variables-element} |
207 |
|
208 |
This element allows you to define variables for the variables |
209 |
substitution system. Some variables are built-in, such as |
210 |
\texttt{\$INSTALL\_PATH} (which is the installation path chosen by the |
211 |
user). When you define a set of variables, you just have to place as |
212 |
many \texttt{<variable>} tags in the file as needed. If you define a |
213 |
variable named \texttt{VERSION} you need to type \$VERSION in the files |
214 |
to parse. The variable substitutor will then replace it with the correct |
215 |
value. One \texttt{<variable>} tag take the following attributes : |
216 |
\begin{itemize} |
217 |
|
218 |
\item \texttt{name} : the variable name |
219 |
\item \texttt{value} : the variable value |
220 |
|
221 |
\end{itemize}\ |
222 |
|
223 |
Here's a sample \texttt{<variables>} section :\\ |
224 |
\footnotesize |
225 |
\begin{verbatim} |
226 |
<variables> |
227 |
<variable name="app-version" value="1.4"/> |
228 |
<variable name="released-on" value="08/03/2002"/> |
229 |
</variables> |
230 |
\end{verbatim} |
231 |
\normalsize |
232 |
|
233 |
\subsection{The GUI Preferences Element \texttt{<guiprefs>}} |
234 |
\label{guiprefs-element} |
235 |
|
236 |
This element allows you to set the behavior of your installer GUI. This |
237 |
information will not have any effect on the command-line installers that will be |
238 |
available in future versions of \IzPack. The arguments to specify are : |
239 |
\begin{itemize} |
240 |
|
241 |
\item \texttt{resizable} : takes \texttt{yes} or \texttt{no} and indicates |
242 |
whether the window size can be changed or not. |
243 |
\item \texttt{width} : sets the initial window width |
244 |
\item \texttt{height} : sets the initial window height. |
245 |
|
246 |
\end{itemize}\ |
247 |
|
248 |
Here's a sample : |
249 |
\footnotesize |
250 |
\begin{verbatim} |
251 |
<guiprefs resizable="no" width="800" height="600"/> |
252 |
\end{verbatim} |
253 |
\normalsize |
254 |
|
255 |
Starting from IzPack 3.6, the look and feel can be specified in this section on |
256 |
a per-OS basis. For instance you can use the native look and feels on Win32 and |
257 |
OS X but use a third-party one on Unix-like platforms. To do that, you have to |
258 |
add some children to the \texttt{guiprefs} tag: |
259 |
\begin{itemize} |
260 |
|
261 |
\item \texttt{laf}: the tag that specifies a look and feel. It has a |
262 |
\texttt{name} parameter that defines the look and feel name. |
263 |
\item Each \texttt{laf} element needs at least one \texttt{os} tag, specified |
264 |
like in the other parts of the specification that support this tag. |
265 |
\item Like you can add \texttt{os} elements, you can add any number of |
266 |
\texttt{param} elements to customize a look and feel. A \texttt{param} |
267 |
elements has two attribues: \texttt{name} and \texttt{value}. |
268 |
|
269 |
\end{itemize}\ |
270 |
|
271 |
The available look and feels are: |
272 |
\begin{itemize} |
273 |
|
274 |
\item Kunststoff: \texttt{kunststoff} |
275 |
\item Liquid: \texttt{liquid} |
276 |
\item Metouia: \texttt{metouia} |
277 |
\item JGoodies Looks: \texttt{looks} |
278 |
|
279 |
\end{itemize}\ |
280 |
|
281 |
If you don't specify a look and feel for a particular operating system, then the |
282 |
default native one will be used: Windows on Windows, Aqua on Mac OS X and Metal |
283 |
on the Unix-like variants.\\ |
284 |
|
285 |
The \textit{Liquid Look and Feel} supports the following parameters: |
286 |
\begin{itemize} |
287 |
|
288 |
\item \texttt{decorate.frames}: \texttt{yes} means that it will render the |
289 |
frames in Liquid style |
290 |
\item \texttt{decorate.dialogs}: \texttt{yes} means that it will render the |
291 |
dialogs in Liquid style |
292 |
|
293 |
\end{itemize}\ |
294 |
|
295 |
The \textit{JGoodies Looks} look and feel can be specified by using the |
296 |
\texttt{variant} parameters. The values can be one of: |
297 |
\begin{itemize} |
298 |
|
299 |
\item \texttt{extwin}: use the Windows Extension look |
300 |
\item \texttt{plastic}: use the basic Plastic look |
301 |
\item \texttt{plastic3D}: use the Plastic 3D look |
302 |
\item \texttt{plasticXP}: use the Plastic XP look (default). |
303 |
|
304 |
\end{itemize}\ |
305 |
|
306 |
Here is a small sample: |
307 |
\begin{verbatim} |
308 |
<guiprefs height="600" resizable="yes" width="800"> |
309 |
<laf name="metouia"> |
310 |
<os family="unix" /> |
311 |
</laf> |
312 |
<laf name="looks"> |
313 |
<os family="windows" /> |
314 |
<param name="variant" value="extwin" /> |
315 |
</laf> |
316 |
</guiprefs> |
317 |
\end{verbatim} |
318 |
|
319 |
Starting from IzPack 3.7, some characteristics can be customized with the |
320 |
\texttt{<modifier>} tag which contains following attributes: |
321 |
\begin{itemize} |
322 |
|
323 |
\item \texttt{key}: a well defined key of the characteristic which should |
324 |
be changed. |
325 |
\item \texttt{value} the value for the key. |
326 |
\end{itemize}\ |
327 |
Following key value pairs are defined: |
328 |
\begin{itemize} |
329 |
\item \texttt{useButtonIcons}: possible are "yes" or "no". Default is "yes". |
330 |
If it is set to "no", all buttons which are created via the ButtonFactory |
331 |
contains no icon also a icon id was submitted. Directly created buttons are |
332 |
not affected. |
333 |
\item \texttt{useLabelIcons}: possible are "yes" or "no". Default is "yes". |
334 |
If it is set to "no", all labels which are created via the LabelFactory |
335 |
contains no icon also a icon id was submitted. Directly created labels are |
336 |
not affected. |
337 |
\end{itemize}\ |
338 |
|
339 |
|
340 |
\subsection{The Localization Element \texttt{<locale>}} |
341 |
\label{localization-element} |
342 |
|
343 |
This element is used to specify the language packs (langpacks) that you want to |
344 |
use for your installer. You must set one \texttt{<langpack>} markup per |
345 |
language. This markup takes the \texttt{iso3} parameter which specifies the iso3 |
346 |
language code.\\ |
347 |
|
348 |
Here's a sample :\\ |
349 |
\footnotesize |
350 |
\begin{verbatim} |
351 |
<locale> |
352 |
<langpack iso3="eng"/> |
353 |
<langpack iso3="fra"/> |
354 |
<langpack iso3="spa"/> |
355 |
</locale> |
356 |
\end{verbatim}\ |
357 |
\normalsize |
358 |
|
359 |
The supported ISO3 codes are : |
360 |
\begin{center} |
361 |
\begin{tabular}{|l|l|} |
362 |
\hline |
363 |
\textit{ISO3 code} & \textit{Language} \\ \hline |
364 |
cat & Catalunyan \\ \hline |
365 |
chn & Chinese \\ \hline |
366 |
cze & Czech \\ \hline |
367 |
dan & Danish \\ \hline |
368 |
deu & German \\ \hline |
369 |
eng & English \\ \hline |
370 |
fin & Finnish \\ \hline |
371 |
fra & French \\ \hline |
372 |
hun & Hungarian \\ \hline |
373 |
ita & Italian \\ \hline |
374 |
jpn & Japanese \\ \hline |
375 |
mys & Malaysian \\ \hline |
376 |
ned & Nederlands \\ \hline |
377 |
nor & Norwegian \\ \hline |
378 |
pol & Polnish \\ \hline |
379 |
por & Portuguese (Brazilian) \\ \hline |
380 |
rom & Romanian \\ \hline |
381 |
rus & Russian \\ \hline |
382 |
scg & Serbian \\ \hline |
383 |
spa & Spanish \\ \hline |
384 |
svk & Slovakian \\ \hline |
385 |
swe & Swedish \\ \hline |
386 |
ukr & Ukrainian \\ \hline |
387 |
\end{tabular}\ |
388 |
\end{center} |
389 |
|
390 |
\subsection{The Resources Element \texttt{<resources>}} |
391 |
\label{resources-element} |
392 |
|
393 |
Several panels, such as the license panel and the shortcut panel, |
394 |
require additional data to perform their task. This data is supplied |
395 |
in the form of resources. This section describes how to specify |
396 |
them. Take a look at each panel description to see if it might need |
397 |
any resources. Currently, no checks are made to ensure resources |
398 |
needed by any panel have been included. The \texttt{<resources>} |
399 |
element is not required, and no \texttt{<res>} elements are required |
400 |
within.\\ |
401 |
|
402 |
You have to set one \texttt{<res>} markup for each resource. Here are |
403 |
the attributes to specify : |
404 |
\begin{itemize} |
405 |
|
406 |
\item \texttt{src} : the path to the resource file which can be named freely |
407 |
of course (for instance \texttt{my-picture.jpg}). |
408 |
\item \texttt{id} : the resource id, depending on the needs of a particular panel |
409 |
\item \texttt{parse} : takes \texttt{yes} or \texttt{no} (default is |
410 |
\texttt{no}) - used to specify whether the resource must be parsed at the |
411 |
installer compilation time. For instance you could set the application version |
412 |
in a readme file used by \texttt{InfoPanel}. |
413 |
\item \texttt{type} : specifies the parse type. This makes sense only for a text |
414 |
resource - the default is \texttt{plain}, other values are \texttt{javaprop, |
415 |
xml} (Java properties file and XML files) |
416 |
\item \texttt{encoding} : specifies the resource encoding if the receiver needs |
417 |
to know. This makes sense only for a text resource. |
418 |
|
419 |
\end{itemize}\ |
420 |
|
421 |
Here's a sample : |
422 |
\footnotesize |
423 |
\begin{verbatim} |
424 |
<resources> |
425 |
<res id="InfoPanel.info" src="doc/readme.txt" parse="yes"/> |
426 |
<res id="LicencePanel.licence" src="legal/License.txt"/> |
427 |
</resources> |
428 |
\end{verbatim} |
429 |
\normalsize |
430 |
|
431 |
\subsection{The Panels Element \texttt{<panels>}} |
432 |
\label{panels-element} |
433 |
|
434 |
Here you tell the compiler which panels you want to use. They will |
435 |
appear in the installer in the order in which they are listed in your |
436 |
XML installation file. Take a look at the different panels in order to |
437 |
find the ones you need. The \texttt{<panel>} markup takes a single |
438 |
attribute \texttt{classname} which is the classname of the panel.\\ |
439 |
|
440 |
Here's a sample : |
441 |
\footnotesize |
442 |
\begin{verbatim} |
443 |
<panels> |
444 |
<panel classname="HelloPanel"/> |
445 |
<panel classname="LicencePanel"/> |
446 |
<panel classname="TargetPanel"/> |
447 |
<panel classname="InstallPanel"/> |
448 |
<panel classname="FinishPanel"/> |
449 |
</panels> |
450 |
\end{verbatim} |
451 |
\normalsize |
452 |
|
453 |
\subsection{The Packs Element \texttt{<packs>}} |
454 |
\label{packs-element} |
455 |
|
456 |
This is a crucial section as it is used to specify the files that need |
457 |
to be installed. The \texttt{<packs>} section consists of several |
458 |
\texttt{<pack>} tags. |
459 |
|
460 |
The \texttt{<pack>} takes the following attributes : |
461 |
\begin{itemize} |
462 |
\item \texttt{name}: the pack name |
463 |
\item \texttt{required}: takes \texttt{yes} or \texttt{no} and specifies |
464 |
whether the pack is optional or not. |
465 |
\item \texttt{os}: optional attribute that lets you make the pack targeted |
466 |
to a specific \textsl{operating system}, for instance \texttt{unix}, |
467 |
\texttt{mac} and so on. |
468 |
\item \texttt{preselected}: optional attribute that lets you choose whether |
469 |
the pack is by default selected for installation or not. Possible values |
470 |
are \texttt{yes} and \texttt{no}. A pack which is not preselected needs to |
471 |
be explicitly selected by the user during installation to get installed. |
472 |
\item \texttt{loose}: can be used so that the files are not located in the |
473 |
installer Jar. The possible values are \texttt{true} or \texttt{false}, the |
474 |
default beeing \texttt{false}. The author of this feature needed to put his |
475 |
application on a CD so that the users could run it directly from this media. |
476 |
However, he also wanted to offer them the possibility to install the |
477 |
software localy. Enabling this feature will make IzPack take the files on |
478 |
disk instead of from the installer. \textit{Please make sure that your relative |
479 |
files paths are correct !} |
480 |
\item \texttt{id}: this attribute is used to give a unique id to the pack to |
481 |
be used for internationalization. |
482 |
\end{itemize} |
483 |
|
484 |
\subsubsection{Internationalization of the PacksPanel} |
485 |
In order to provide internationalization for the PacksPanel, so that your users can |
486 |
be presented with a different name and description for each language you support, |
487 |
you have to create a file named \texttt{packsLang.xml\_xyz} where \texttt{xyz} |
488 |
is the ISO3 code of the language in lowercase. Please be aware that case is significant. |
489 |
This file has to be inserted in the resources section of \texttt{install.xml} with the |
490 |
\texttt{id} and \texttt{src} attributes set at the name of the file. The format of |
491 |
these files is identical with the distribution langpack files located at |
492 |
\texttt{\$IZPACK\_HOME/install/langpacks/installer}. For the name of the panel you just |
493 |
use the pack \texttt{id} as the txt \texttt{id}. For the description you use the pack |
494 |
\texttt{id} suffixed with \texttt{'.description'}. |
495 |
|
496 |
The following sections describe the tags available for a \texttt{<pack>} section. |
497 |
|
498 |
\subsubsection{\texttt{<description>} - pack description} |
499 |
|
500 |
The contents of the \texttt{<description>} tag describe the pack contents. |
501 |
This description is displayed if the user highlights the pack during |
502 |
installation. |
503 |
|
504 |
\subsubsection{\texttt{<depends>} - pack dependencies} |
505 |
This can be used to make this pack selectable only to be installed only if some other is |
506 |
selected to be installed. The pack can depend on more than one by specifying more than one |
507 |
\texttt{<depends>} elements.\\ |
508 |
Circular depedencies are not supported and the compiler reports an error if one occurs. |
509 |
|
510 |
This tag takes the following attribute: |
511 |
\begin{itemize} |
512 |
\item \texttt{packname}: The name of the pack that it depends on |
513 |
\end{itemize} |
514 |
|
515 |
\subsubsection{\texttt{<os>} - OS restrictions} |
516 |
|
517 |
It is possible to restrict a panel to a certain list of operating systems. This |
518 |
tag takes the following attributes: |
519 |
\begin{itemize} |
520 |
\item \texttt{family}: unix, windows or mac |
521 |
\item \texttt{name}: the exact OS name (ie Windows, Linux, ...) |
522 |
\item \texttt{version}: the exact OS version (see the JVM \texttt{os.version} property) |
523 |
\item \texttt{arch}: the machine architecture (see the JVM \texttt{os.arch} property). |
524 |
\end{itemize} |
525 |
|
526 |
\subsubsection{\texttt{<updatecheck>}} |
527 |
|
528 |
This feature can update an already installed package, therefore removing |
529 |
superfluous files after installation. Here's how this feature author (Tino Schwarze) |
530 |
described it on the IzPack development mailing-list: |
531 |
\begin{quote} |
532 |
Each pack can now |
533 |
specify an \texttt{<updatecheck>} tag. It supports a subset of ant fileset |
534 |
syntax, e.g.: |
535 |
\begin{verbatim} |
536 |
<updatecheck> |
537 |
<include name="lib/**" /> |
538 |
<exclude name="config/local/** /> |
539 |
</updatecheck> |
540 |
\end{verbatim}\ |
541 |
|
542 |
If the paths are relative, they will be matched relative to |
543 |
\texttt{\$INSTALL\_PATH}. Update checks are only enabled if at least one |
544 |
\texttt{<include>} is specified. See |
545 |
\texttt{com.izforge.izpack.installer.Unpacker} for details. |
546 |
\end{quote} |
547 |
|
548 |
\subsubsection{\label{tag:file}\texttt{<file>} - add files or directories} |
549 |
|
550 |
The \texttt{<file>} tag specifies a file (a directory is a file too) to |
551 |
include into the pack. It takes the following attributes: |
552 |
|
553 |
\begin{itemize} |
554 |
|
555 |
\item \texttt{src}: the file location (relative path) - if this is a |
556 |
directory its content will be added recursively |
557 |
|
558 |
\item \texttt{targetdir}: the destination directory, could be something like |
559 |
\texttt{\$INSTALL\_PATH/subdirX} |
560 |
|
561 |
\item \texttt{os}: can optionally specify a target operating system |
562 |
(\texttt{unix, windows, mac}) - this means that the file will only be |
563 |
installed on its target operating system |
564 |
|
565 |
\item \texttt{override}: if \texttt{true} then if the file is already |
566 |
installed, it will be overwritten. Alternative values: \texttt{asktrue} and |
567 |
\texttt{askfalse} -- ask the user what to do and supply default value for |
568 |
non-interactive use. Another possible values is \texttt{update}. It means |
569 |
that the new file is only installed if it's modification time is newer than |
570 |
the modification time of the already existing file (note that this is not a |
571 |
reliable mechanism for updates - you cannot detect whether a file was |
572 |
altered after installation this way.) By default it is set to \texttt{update}. |
573 |
|
574 |
\end{itemize} |
575 |
\paragraph{\label{tag:additionaldata}\texttt{<additionaldata>}} |
576 |
|
577 |
This tag can also be specified in order to pass additional data |
578 |
related to a file tag for customizing. |
579 |
|
580 |
\begin{itemize} |
581 |
|
582 |
\item \texttt{<key>}: key to identify the data |
583 |
\item \texttt{<value>}: value which can be used by a custom |
584 |
action |
585 |
|
586 |
\end{itemize} |
587 |
|
588 |
\subsubsection{\label{tag:singlefile}\texttt{<singlefile>} - add a single file} |
589 |
|
590 |
Specifies a single file to include. The difference to \texttt{<file>} is that |
591 |
this tag allows the file to be renamed, therefore it has a |
592 |
\texttt{target} attribute instead of \texttt{targetdir}. |
593 |
|
594 |
\begin{itemize} |
595 |
|
596 |
\item \texttt{src}: the file location (relative path) |
597 |
|
598 |
\item \texttt{target}: the destination file name, could be something |
599 |
like \texttt{\$INSTALL\_PATH/subdirX/fileY} |
600 |
|
601 |
\item \texttt{os}: can optionally specify a target operating system |
602 |
(\texttt{unix, windows, mac}) - this means that the file will only be |
603 |
installed on its target operating system |
604 |
|
605 |
\item \texttt{override}: see \texttt{<file>} (\ref{tag:file}) for description |
606 |
|
607 |
\end{itemize} |
608 |
A \texttt{<additionaldata>} (\ref{tag:additionaldata}) tag can |
609 |
also be specified for customizing. |
610 |
|
611 |
\subsubsection{\label{tag:fileset}\texttt{<fileset>}: add a fileset} |
612 |
|
613 |
The \texttt{<fileset>} tag allows files to be specified using the powerful |
614 |
Jakarta Ant set syntax. It takes the following parameters: |
615 |
|
616 |
\begin{itemize} |
617 |
|
618 |
\item \texttt{dir}: the base directory for the fileset (relative path) |
619 |
|
620 |
\item \texttt{targetdir}: the destination path, works like for |
621 |
\texttt{<file>} |
622 |
|
623 |
\item \texttt{casesensitive}: optionally lets you specify if the names |
624 |
are case-sensitive or not - takes \texttt{yes} or \texttt{no} |
625 |
|
626 |
\item \texttt{defaultexcludes}: optionally lets you specify if the default |
627 |
excludes will be used - takes \texttt{yes} or \texttt{no}. |
628 |
|
629 |
\item \texttt{os}: specifies the operating system, works like for |
630 |
\texttt{<file>} |
631 |
|
632 |
\item \texttt{override}: see \texttt{<file>} for description |
633 |
|
634 |
\item \texttt{includes}: comma- or space-separated list of patterns of |
635 |
files that must be included; all files are included when omitted. |
636 |
This is an alternative for multiple include tags. |
637 |
|
638 |
\item \texttt{excludes}: comma- or space-separated list of patterns of |
639 |
files that must be excluded; no files (except default excludes) are |
640 |
excluded when omitted. This is an alternative for multiple exclude tags. |
641 |
|
642 |
\end{itemize} |
643 |
|
644 |
You specify the files with \texttt{<include>} and \texttt{<exclude>} tags |
645 |
that take the \texttt{name} parameter to specify the Ant-like pattern : |
646 |
\begin{itemize} |
647 |
\item \texttt{**} : means any subdirectory |
648 |
\item \texttt{*} : used as a wildcard. |
649 |
\end{itemize} |
650 |
Here are some examples of Ant patterns : |
651 |
\begin{itemize} |
652 |
|
653 |
\item \texttt{<include name="lib"/>} : will include \texttt{lib} and the |
654 |
subdirectories of \texttt{lib} |
655 |
|
656 |
\item \texttt{<exclude name="**/*.java"/>} : will exclude any file in any |
657 |
directory starting from the base path ending by \texttt{.java} |
658 |
|
659 |
\item \texttt{<include name="lib/*.jar"/>} : will include all the files |
660 |
ending by \texttt{.jar} in \texttt{lib} |
661 |
|
662 |
\item \texttt{<exclude name="lib/**/*FOO*"/>} : will exclude any file in |
663 |
any subdirectory starting from \texttt{lib} whose name contains |
664 |
\texttt{FOO}. |
665 |
|
666 |
\end{itemize} |
667 |
|
668 |
There area set of definitions that are excluded by default file-sets, |
669 |
just as in Ant. IzPack defaults to the Ant list of default |
670 |
excludes. There is currently no equivalent to the <defaultexcludes> |
671 |
task. Default excludes are: |
672 |
\footnotesize |
673 |
\begin{verbatim} |
674 |
**/*\~{} |
675 |
**/\#*\# |
676 |
**/.\#* |
677 |
**/%*% |
678 |
**/.\_* |
679 |
**/CVS |
680 |
**/CVS/** |
681 |
**/.cvsignore |
682 |
**/SCCS |
683 |
**/SCCS/** |
684 |
**/vssver.scc |
685 |
**/.svn |
686 |
**/.svn/** |
687 |
**/.DS\_Store |
688 |
\end{verbatim} |
689 |
\normalsize |
690 |
A \texttt{<additionaldata>} (\ref{tag:additionaldata}) |
691 |
tag can also be specified for customizing. |
692 |
|
693 |
\subsubsection{\texttt{<parsable>} - parse a file after installation} |
694 |
|
695 |
Files specified by \texttt{<parsable>} are parsed after installation and may |
696 |
have variables substituted. |
697 |
|
698 |
\begin{itemize} |
699 |
|
700 |
\item \texttt{targetfile} : the file to parse, could be something like\\ |
701 |
\texttt{\$INSTALL\_PATH/bin/launch-script.sh}\\ |
702 |
\label{tag:slashMasking}A slash will be changed to the system dependant path separator (e.g. to |
703 |
a backslash on Windows) only if no backslash masks the slash. |
704 |
|
705 |
\item \texttt{type} : specifies the type (same as for the resources) - |
706 |
the default is \texttt{plain} |
707 |
|
708 |
\item \texttt{encoding} : specifies the file encoding |
709 |
|
710 |
\item \texttt{os}: specifies the operating system, works like for |
711 |
\texttt{<file>} |
712 |
|
713 |
\end{itemize}\ |
714 |
|
715 |
\subsubsection{\texttt{<executable>} - mark file executable or execute it} |
716 |
|
717 |
The \texttt{<executable>} tag is a very useful thing if you need to execute |
718 |
something during the installation process. It can also be used to set the |
719 |
executable flag on Unix-like systems. Here are the attributes : |
720 |
|
721 |
\begin{itemize} |
722 |
|
723 |
\item \texttt{targetfile} : the file to run, could be something like\\ |
724 |
\texttt{\$INSTALL\_PATH/bin/launch-script.sh}\\ |
725 |
Slashes are handled special (see attribute |
726 |
\texttt{targetfile} of tag \texttt{<parsable>}\ref{tag:slashMasking}). |
727 |
|
728 |
\item \texttt{class} : If the executable is a jar file, this is the |
729 |
class to run for a \Java program |
730 |
|
731 |
\item \texttt{type} : \texttt{bin} or \texttt{jar} (the default is |
732 |
\texttt{bin}) |
733 |
|
734 |
\item \texttt{stage} : specifies when to launch : \texttt{postinstall} |
735 |
is just after the installation is done and the default value, |
736 |
\texttt{never} will never launch it (useful to set the +x flag on Unix). |
737 |
\texttt{uninstall} will launch the executable when the application |
738 |
is uninstalled. The executable is executed before any files are deleted. |
739 |
|
740 |
\item \texttt{failure} : specifies what to do when an error occurs : |
741 |
\texttt{abort} will abort the installation process, \texttt{ask} (default) |
742 |
will ask the user what to do and \texttt{warn} will just tell the user |
743 |
that something is wrong |
744 |
|
745 |
\item \texttt{os}: specifies the operating system, works like for |
746 |
\texttt{<file>} |
747 |
|
748 |
\item \texttt{keep} : specifies whether the file will be kept after |
749 |
execution. The default is to delete the file after is has been executed. |
750 |
This can be changed by specifying \texttt{keep="true"}. |
751 |
|
752 |
\end{itemize} |
753 |
A \texttt{<args>} tag can also be specified in order to pass |
754 |
arguments to the executable: |
755 |
\begin{itemize} |
756 |
|
757 |
\item \texttt{<arg>}: passes the argument specified in the |
758 |
\texttt{value} attribute. Slashes are handled special (see attribute |
759 |
\texttt{targetfile} of tag \texttt{<parsable>}\ref{tag:slashMasking}). |
760 |
|
761 |
\end{itemize} |
762 |
|
763 |
\subsubsection{\label{tag:os}\texttt{<os>} - make a file OS-dependent} |
764 |
|
765 |
The \texttt{<os>} tag can be used inside the \texttt{<file>}, |
766 |
\texttt{<fileset>}, \texttt{<singlefile>}, \texttt{<parsable>}, |
767 |
\texttt{<executable>} tags to restrict it's effect to a specific |
768 |
operating system family, architecture or version: |
769 |
|
770 |
\begin{itemize} |
771 |
|
772 |
\item \texttt{family}: \texttt{unix, windows, mac} to specify the |
773 |
operating system family |
774 |
\item \texttt{name}: the operating system name |
775 |
\item \texttt{version}: the operating system version |
776 |
\item \texttt{arch}: the operating system architecture (for instance the |
777 |
Linux kernel can run on i386, sparc, and so on) |
778 |
|
779 |
\end{itemize} |
780 |
|
781 |
|
782 |
Here's an example installation file : |
783 |
\footnotesize |
784 |
\begin{verbatim} |
785 |
<packs> |
786 |
<!-- The core files --> |
787 |
<pack name="Core" required="yes"> |
788 |
<description>The IzPack core files.</description> |
789 |
<file targetdir="$INSTALL_PATH" src="bin"/> |
790 |
<file targetdir="$INSTALL_PATH" src="lib"/> |
791 |
<file targetdir="$INSTALL_PATH" src="legal"/> |
792 |
<file targetdir="$INSTALL_PATH" src="Readme.txt"/> |
793 |
<file targetdir="$INSTALL_PATH" src="Versions.txt"/> |
794 |
<file targetdir="$INSTALL_PATH" src="Thanks.txt"/> |
795 |
<parsable targetfile="$INSTALL_PATH/bin/izpack-fe"/> |
796 |
<parsable targetfile="$INSTALL_PATH/bin/izpack-fe.bat"/> |
797 |
<parsable targetfile="$INSTALL_PATH/bin/compile"/> |
798 |
<parsable targetfile="$INSTALL_PATH/bin/compile.bat"/> |
799 |
<executable targetfile="$INSTALL_PATH/bin/compile" stage="never"/> |
800 |
<executable targetfile="$INSTALL_PATH/bin/izpack-fe" stage="never"/> |
801 |
</pack> |
802 |
|
803 |
<!-- The documentation (1 directory) --> |
804 |
<pack name="Documentation" required="no"> |
805 |
<description>The IzPack documentation (HTML and PDF).</description> |
806 |
<file targetdir="$INSTALL_PATH" src="doc"/> |
807 |
</pack> |
808 |
</packs> |
809 |
\end{verbatim} |
810 |
\normalsize |
811 |
|
812 |
\subsection{The Native Element \texttt{<native>}} |
813 |
\label{native-element} |
814 |
|
815 |
Use this if you want to use a feature that requires a native library. |
816 |
The native libraries are placed under \texttt{bin/native/..}. There are 2 |
817 |
kinds of native libraries : the \IzPack libraries and the third-party |
818 |
ones. The IzPack libraries are located at \texttt{bin/native/izpack}, |
819 |
you can place your own libraries at \texttt{bin/native/3rdparty}. |
820 |
It is possible to place a native library also into the uninstaller. |
821 |
It is useable from CustomActions (\ref{cha:customactions}). If one or |
822 |
more are referenced for it, the needed support classes are automatically |
823 |
placed into the uninstaller. To place it only on operating systems |
824 |
for which they are build, it is possible to define an OS |
825 |
restriction. This restriction will only be performed for the |
826 |
uninstaller. The markup takes the following attributes :\begin{itemize} |
827 |
|
828 |
\item \texttt{type} : \texttt{izpack} or \texttt{3rdparty} |
829 |
\item \texttt{name} : the library filename |
830 |
\item \texttt{stage}: stage where to use the library |
831 |
(install|uninstall|both) |
832 |
|
833 |
\end{itemize}\ |
834 |
\subsubsection{\texttt{<os>} - make a library OS-dependent} |
835 |
|
836 |
The \texttt{<os>} tag can be used to restrict the inclusion into |
837 |
the uninstaller to a specific operating system family, |
838 |
architecture or version. The inclusion into the installer will be |
839 |
always done. For more information see \ref{tag:os}. |
840 |
|
841 |
Here's a sample : |
842 |
\footnotesize |
843 |
\begin{verbatim} |
844 |
<native type="izpack" name="ShellLink.dll"/> |
845 |
\end{verbatim} |
846 |
\normalsize |
847 |
|
848 |
\subsection{The Jar Merging Element \texttt{<jar>}} |
849 |
\label{jar-element} |
850 |
|
851 |
If you adapt \IzPack for your own needs, you might need to merge the |
852 |
content of another jar file into the jar installer. For instance, this |
853 |
could be a library that you need to merge. The \texttt{<jar>} markup |
854 |
allows you to merge the raw content of another jar file into the |
855 |
installer and the uninstaller. It is necessary that the paths in the |
856 |
jars are unique because only the contained files of the jar are added |
857 |
to the installer jar, not the jar file self. |
858 |
The attributes are:\begin{itemize} |
859 |
\item \texttt{src} : the path at compile time |
860 |
\item \texttt{stage}: stage where to use the contents of the additional jar file |
861 |
(install|uninstall|both) |
862 |
|
863 |
\end{itemize}\ |
864 |
|
865 |
|
866 |
A sample : |
867 |
\footnotesize |
868 |
\begin{verbatim} |
869 |
<jar src="../nicelibrary.jar"/> |
870 |
\end{verbatim} |
871 |
\normalsize |
872 |
|
873 |
% The panels |
874 |
\section{The Available Panels} |
875 |
|
876 |
In this section I will introduce the various panels available in IzPack. |
877 |
The usage for most is pretty simple and described right here. The more |
878 |
elaborate ones are explained in more detail in the \textit{Advanced |
879 |
Features} chapter or in their own chapter. The panels are listed by |
880 |
their class name. This is the name that must be used with the |
881 |
\texttt{classname} attribute (case-sensitive).\\ |
882 |
|
883 |
\subsection{HelloPanel} |
884 |
|
885 |
This panel welcomes the user by displaying the project name, the |
886 |
version, the URL as well as the authors.\\ |
887 |
|
888 |
\subsection{InfoPanel and HTMLInfoPanel} |
889 |
|
890 |
This is a kind of 'README' panel. It presents text of any length. The |
891 |
text is specified by the \texttt{(HTML)InfoPanel.info} resource. Starting from |
892 |
IzPack 3.7.0, variables substitution is allowed.\\ |
893 |
|
894 |
\subsection{LicencePanel and HTMLLicencePanel} |
895 |
|
896 |
\noindent |
897 |
\textit{\underline{Note :} there is a mistake in the name - it should be |
898 |
LicensePanel. In France the word is Licence ... and one of my diploma is a |
899 |
'Licence' so ...} :-)\\ |
900 |
|
901 |
These panels can prompt the user to acknowledge a license agreement. They block |
902 |
unless the user selects the 'agree' option. To specify the license agreement |
903 |
text you have to use the \texttt{(HTML)LicencePanel.licence} resource.\\ |
904 |
|
905 |
\subsection{PacksPanel} |
906 |
|
907 |
Allows the user to select the packs he wants to install.\\ |
908 |
|
909 |
\subsection{ImgPacksPanel} |
910 |
|
911 |
This is the same as above, but for each panel a different picture is |
912 |
shown to the user. The pictures are specified with the resources |
913 |
\texttt{ImgPacksPanel.img.x} where x stands for the pack number, the |
914 |
numbers start from 0. Of course it's up to you to specify as many images |
915 |
as needed and with correct numbers. For instance if you have 2 packs |
916 |
\texttt{core} and \texttt{documentation} (in this order), then the resource for |
917 |
\texttt{core} will be \texttt{ImgPacksPanel.img.0} and the resource for |
918 |
\texttt{doc} will be \texttt{ImgPacksPanel.img.1}. The supported image formats |
919 |
depend on what you JVM supports, but starting from J2SE 1.3, \textsl{GIF}, |
920 |
\textsl{JPEG} and \textsl{PNG} are supported.\\ |
921 |
|
922 |
\subsection{TargetPanel} |
923 |
|
924 |
This panel allows the user to select the installation path. It can be customized with |
925 |
the following resources (they are text files containing the path) : |
926 |
\begin{itemize} |
927 |
|
928 |
\item \texttt{TargetPanel.dir.f} where f stands for the family (\texttt{mac, |
929 |
macosx, windows, unix}) |
930 |
\item \texttt{TargetPanel.dir} : the directory name, instead of the software |
931 |
to install name |
932 |
\item \texttt{TargetPanel.dir.d} where d is a "dynamic" name, as returned by |
933 |
the \Java virtual machine. You should write the name in lowercase and replace the |
934 |
spaces with underscores. For instance, you might want a different setting for |
935 |
Solaris and GNU/Linux which are both Unix-like systems. The resources would be |
936 |
\texttt{TargetPanel.dir.sunos, TargetPanel.dir.linux}. You should have a |
937 |
Unix-resource in case it wouldn't work though. |
938 |
|
939 |
\end{itemize}\ |
940 |
|
941 |
\subsection{InstallPanel} |
942 |
|
943 |
You should always have this one as it launches the installation process !\\ |
944 |
|
945 |
\subsection{XInfoPanel} |
946 |
|
947 |
A panel showing text parsed by the variable substitutor. The text can be |
948 |
specified through the \texttt{XInfoPanel.info} resource. This panel can |
949 |
be useful when you have to show information after the installation |
950 |
process is completed (for instance if the text contains the target |
951 |
path).\\ |
952 |
|
953 |
\subsection{FinishPanel} |
954 |
|
955 |
A ending panel, able to write automated installer information. For |
956 |
details see the chapter on 'Advanced Features'.\\ |
957 |
|
958 |
\subsection{SimpleFinishPanel} |
959 |
|
960 |
Same as \texttt{FinishPanel}, but without the automated installer features. It |
961 |
is aimed at making the life easier for end-users who will never encounter the |
962 |
automated installer extra feature.\\ |
963 |
|
964 |
\subsection{ShortcutPanel} |
965 |
|
966 |
This panel is used to create desktop shortcuts. For details on using the |
967 |
ShortcutPanel see the chapter 'Desktop Shortcuts'. |
968 |
|
969 |
\subsection{UserInputPanel} |
970 |
|
971 |
This panel allows you to prompt the user for data. What the user is prompted |
972 |
for is specified using an XML file which is included as a resource to the |
973 |
installer. See chapter \ref{chap:userinput} on page \pageref{chap:userinput} |
974 |
for a detailed explanation. |
975 |
|
976 |
\subsection{CompilePanel} |
977 |
|
978 |
This panel allows you to compile just installed Java sourcecode. |
979 |
The details for the compilation are specified using the resource \texttt{CompilePanel.Spec.xml}. |
980 |
The XML file has the following format: |
981 |
\begin{verbatim} |
982 |
<compilation> |
983 |
<global> |
984 |
<compiler> |
985 |
<choice value="$JAVA_HOME/bin/javac" /> |
986 |
<choice value="jikes" /> |
987 |
</compiler> |
988 |
<arguments> |
989 |
<choice value="-O -g:none" /> |
990 |
<choice value="-O" /> |
991 |
<choice value="-g" /> |
992 |
<choice value="" /> |
993 |
</arguments> |
994 |
</global> |
995 |
<jobs> |
996 |
<classpath add="$INSTALL_PATH/src/classes/" /> |
997 |
<job name="optional name"> |
998 |
<directory name="$INSTALL_PATH/src/classes/xyz" /> |
999 |
</job> |
1000 |
<job name="another job"> |
1001 |
<packdepency name="some package name" /> |
1002 |
<classpath sub="$INSTALL_PATH/" /> |
1003 |
<directory name="$INSTALL_PATH/src/classes/abc" /> |
1004 |
<file name="$INSTALL_PATH/some/file.java" /> |
1005 |
</job> |
1006 |
</jobs> |
1007 |
</compilation> |
1008 |
\end{verbatim} |
1009 |
|
1010 |
In theory, jobs can be nested but this has not been tested at all. A change to |
1011 |
the classpath within a job only affects this job and nested jobs. The classpath |
1012 |
should be specified before any files or directories. |
1013 |
|
1014 |
The user can change the compiler to use and choose from some default |
1015 |
compilation options before compilation is started. |
1016 |
|
1017 |
\includegraphics[width=\linewidth]{img/compilePanel} |
1018 |
|
1019 |
\subsection{ProcessPanel} |
1020 |
|
1021 |
This panel allows you to execute arbitrary files after installation. |
1022 |
The details for the compilation are specified using the resource \texttt{ProcessPanel.Spec.xml}. |
1023 |
|
1024 |
The XML file has the following format: |
1025 |
\begin{verbatim} |
1026 |
<processing> |
1027 |
<job name="do xyz"> |
1028 |
<os family="windows" /> |
1029 |
<executefile name="$INSTALL_PATH/scripts/xyz.bat"> |
1030 |
<arg>doit</arg><arg>$variable</arg> |
1031 |
</executefile> |
1032 |
</job> |
1033 |
<job name="do xyz"> |
1034 |
<os family="unix" /> |
1035 |
<executefile name="$INSTALL_PATH/scripts/xyz.sh"> |
1036 |
<arg>doit</arg><arg>$variable</arg> |
1037 |
</executefile> |
1038 |
</job> |
1039 |
</processing> |
1040 |
\end{verbatim} |
1041 |
|
1042 |
Each job may have an \texttt{<os>} attribute -- see \ref{tag:os} for details.\\ |
1043 |
|
1044 |
It is also possible to execute Java classes from this panel. Here's what this |
1045 |
feature author (Alex Bradley) says: |
1046 |
\begin{quotation} |
1047 |
I've been able to work around my requirements by extending the |
1048 |
\texttt{ProcessPanelWorker} functionality to run user-specified classes. I've |
1049 |
extended the DTD of the \texttt{ProcessPanel.Spec.xml} to include a new element: |
1050 |
\begin{verbatim} |
1051 |
<executeclass name="classname"> |
1052 |
<args..../> |
1053 |
</executeclass> |
1054 |
\end{verbatim} |
1055 |
I've also added a new sub-class of \texttt{Processable} called |
1056 |
\texttt{executeclass}. This will run a user-specified class in the context of |
1057 |
the installer JVM with a single method : |
1058 |
\begin{verbatim}run( AbstractUIProcessHandler handler, String[] args]);\end{verbatim} |
1059 |
|
1060 |
It can do everything I need and more. In particular, it allows me to write a |
1061 |
process extension and still be able to provide feedback to the user through |
1062 |
the feedback panel, and to add new functionality to the installer, after its |
1063 |
been built. |
1064 |
\end{quotation} |
1065 |
|
1066 |
New with version 3.7 is the possibility to tee output that is written to |
1067 |
the ProcessPanel's textarea into an optional logfile. Using this feature is |
1068 |
pretty much straightforward, you only have to add a line in \texttt{ProcessPanel.Spec.xml} |
1069 |
that will tell IzPack the location, where the logfile should be stored. |
1070 |
|
1071 |
Variable substitution is performed, so you can use \texttt{\$INSTALL\_PATH} as example. |
1072 |
|
1073 |
The name of the logfile is not (yet) configurable but should fit in most cases. It will |
1074 |
be named |
1075 |
\begin{verbatim} |
1076 |
Install_V<$APP_VER>_<YYYY>-<MM>-<DD>_<hh>-<mm>-<ss>_<RandomId>.log |
1077 |
\end{verbatim} |
1078 |
|
1079 |
Here's an example: |
1080 |
|
1081 |
\begin{verbatim} |
1082 |
<processing> |
1083 |
<logfiledir>$INSTALL_PATH</logfiledir> |
1084 |
<job name="do xyz"> |
1085 |
<os family="windows" /> |
1086 |
<executefile name="$INSTALL_PATH/scripts/xyz.bat"> |
1087 |
<arg>doit</arg><arg>$variable</arg> |
1088 |
</executefile> |
1089 |
</processing> |
1090 |
\end{verbatim} |
1091 |
|
1092 |
This will generate a logfile named e.g. \texttt{Install\_V1.3\_2004-11-08\_19-22-20\_43423.log} |
1093 |
located in \texttt{\$INSTALL\_PATH}. |
1094 |
|
1095 |
\texttt{ProcessPanelWorker} will write all output that is directed to \texttt{stdout} and \texttt{stderr} to this file |
1096 |
if \texttt{ProcessPanel.Spec.xml} contains the \texttt{logfiledir} entry. |
1097 |
|
1098 |
Please note that this one file is used for storing the complete output of all jobs and not |
1099 |
a file for each job that is run. |
1100 |
|
1101 |
\subsection{JDKPathPanel} |
1102 |
This panel allows the user to select a JDK path. The variable JAVA\_HOME does |
1103 |
not point to a JDK, else to a JRE also the environment variable points to a JDK. |
1104 |
This is not a bug, this is the behavior of the VM. But some products needs a JDK, |
1105 |
for that this panel can be used. There is not only a selection of the path else |
1106 |
a validation. The validation will be done with the file JDKPath/lib/tools.jar. |
1107 |
If JAVA\_HOME points to the VM which is placed in the JDK, the directory will |
1108 |
be used as default (JAVA\_HOME/..). If there is the variable |
1109 |
\begin{verbatim} |
1110 |
JDKPathPanel.skipIfValid |
1111 |
\end{verbatim} |
1112 |
defined with the value "yes", the panel will be skiped if the path is valid. |
1113 |
Additional it is possible to make a version control. If one or both variables |
1114 |
\begin{verbatim} |
1115 |
JDKPathPanel.minVersion |
1116 |
JDKPathPanel.maxVersion |
1117 |
\end{verbatim} |
1118 |
are defined, only a JDK will be accepted which has a version in the |
1119 |
range of it. The detection is a little bit pragmatically, therefor it is |
1120 |
possible, that the detection can fail at some VMs. |
1121 |
The values in the install.xml should be like |
1122 |
\begin{verbatim} |
1123 |
<variables> |
1124 |
<variable name="JDKPathPanel.minVersion" value="1.4.1" /> |
1125 |
<variable name="JDKPathPanel.maxVersion" value="1.4.99" /> |
1126 |
<variable name="JDKPathPanel.skipIfValid" value="yes" /> |
1127 |
</variables> |
1128 |
\end{verbatim} |
1129 |
|
1130 |
If all is valid, the panels isValidated method sets the variable |
1131 |
\begin{verbatim} |
1132 |
JDKPath |
1133 |
\end{verbatim} |
1134 |
to the chosen path. Be aware, this variable exist not until the JDKPanel |
1135 |
was quitted once. At a secound activation, the default will be the |
1136 |
last selection. |