svn-gvsig-desktop / branches / v10 / install / IzPack / src / doc / chapter2.tex @ 33743
History | View | Annotate | Download (43.1 KB)
1 | 5819 | cesar | % 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. |