root / trunk / install / IzPack / src / doc / chapter1.tex @ 11445
History | View | Annotate | Download (6.91 KB)
1 | 5819 | cesar | % Chapter 1 |
---|---|---|---|
2 | \chapter{Getting started} |
||
3 | |||
4 | % Overview |
||
5 | \section{Overview} |
||
6 | |||
7 | To begin with, you should know what \IzPack is organized if you want to use |
||
8 | it. Let's go into the directory where you have installed \IzPack on your |
||
9 | machine. There are 3 text files and a set of directories. The most |
||
10 | important for the moment are \texttt{bin/ doc/ sample/}. If you are reading this, |
||
11 | you already know that \texttt{doc} contains this documentation :-)\\ |
||
12 | |||
13 | So let's go into \texttt{bin/}. The \texttt{icons/} directory contains some |
||
14 | directories for your system, in case you would like an icon to launch a |
||
15 | component of \IzPack. But the most important things you can see in \texttt{bin} |
||
16 | are the \texttt{compile} scripts (in both Unix* and Windows formats). |
||
17 | \texttt{compile} is used to compile a ready-to-go XML installation file from |
||
18 | a command-line context or from an external tool.\\ |
||
19 | |||
20 | \noindent |
||
21 | \textit{Note : these scripts can be launched from anywhere on your system as the |
||
22 | installer has customized these scripts so that they can inform \IzPack of where |
||
23 | it is located.}\\ |
||
24 | |||
25 | % First Compilation |
||
26 | \section{First Compilation} |
||
27 | |||
28 | Now you probably can't wait to build your first installer. So go on open a |
||
29 | command-line shell and navigate to \texttt{sample/}. The following should work |
||
30 | on both Unix* and Windows systems. For the latter, just change the path |
||
31 | separator (slash '/') to a backslash. So type (\$ is your shell prompt !) : |
||
32 | \begin{verbatim} |
||
33 | $ ../bin/compile install.xml -b . -o install.jar -k standard |
||
34 | (installer generation text output here) |
||
35 | $ java -jar install.jar |
||
36 | \end{verbatim} |
||
37 | |||
38 | There you are! The first command has produced the installer and the |
||
39 | second one did launch it. |
||
40 | |||
41 | % The IzPack Architecture |
||
42 | \section{The \IzPack Architecture} |
||
43 | |||
44 | Now that you have packaged your first installer, it's time for you to understand |
||
45 | how the whole thing works.\\ |
||
46 | |||
47 | \subsection{The Compilation System} |
||
48 | |||
49 | The compilation system (see figure \ref{comparch}) is quite modular. |
||
50 | Indeed, you can use the compiler in 2 ways : |
||
51 | \begin{itemize} |
||
52 | \item from a command-line |
||
53 | \item from Jakarta Ant |
||
54 | \end{itemize}\ |
||
55 | |||
56 | \begin{figure}[h] |
||
57 | \caption{\label{comparch} |
||
58 | \textit{The compiler architecture.}} |
||
59 | \begin{center} |
||
60 | \fbox{\includegraphics[scale=0.4]{img/ch1-comparch}} |
||
61 | \end{center} |
||
62 | \end{figure} |
||
63 | |||
64 | The compiler takes as its input an XML installation file that describes |
||
65 | (at a relatively high-level) the installation. This file contains |
||
66 | detailed information such as the application name, the authors, the |
||
67 | files to install, the panels to use, which resources to load and much |
||
68 | more (see figure \ref{archinstaller}).\\ |
||
69 | |||
70 | The compiler can generate different kinds of installers, but this information is |
||
71 | not located inside the XML file as it is not were it should be. On the contrary, |
||
72 | this is a compiler parameter.\\ |
||
73 | |||
74 | The compilation options for a command-line installer are the following: |
||
75 | \begin{itemize} |
||
76 | \item \texttt{-?}: gives a list of the available options. |
||
77 | \item \texttt{-b}: specifies the base path, \textsl{ie} the one that will be |
||
78 | used to resolve the relative paths. If your XML file contains absolute paths, |
||
79 | specify it to an empty string (\texttt{-b ""}). |
||
80 | \item \texttt{-k}: specifies the installer kind, for instance most users will |
||
81 | want \texttt{standard} here. |
||
82 | \item \texttt{-o}: specifies the resulting installer Jar file name. |
||
83 | \end{itemize}\ |
||
84 | |||
85 | \subsection{How an Installer Works} |
||
86 | |||
87 | An installer presents its panels to the end-user. For instance, there is |
||
88 | one to select the packages, one to prompt for the license agreement, one |
||
89 | to select the installation path and so on. You have a choice from a |
||
90 | variety of panels to place in the installer. For example, you can choose |
||
91 | between a plain text and a HTML text panel for the license agreement. |
||
92 | Also, if you don't want of the \textit{HelloPanel}, you just don't |
||
93 | include it.\\ |
||
94 | |||
95 | \begin{figure}[h] |
||
96 | \caption{\label{archinstaller} |
||
97 | \textit{The installer architecture.}} |
||
98 | \begin{center} |
||
99 | \fbox{\includegraphics[scale=0.4]{img/ch1-compinside}} |
||
100 | \end{center} |
||
101 | \end{figure} |
||
102 | |||
103 | It is very important to understand that some of the panels may need extra data. For |
||
104 | instance, the license agreement panel needs the license text. A simple approach |
||
105 | to specify such data would have been to add as many XML tags as needed for |
||
106 | each panel. However, this makes the XML file too specific and not easy to |
||
107 | maintain. The approach that has been chosen is to put the data in files and we |
||
108 | call these files \textit{resource files}. They are specified with a unique XML |
||
109 | tag. This is a much cleaner approach.\\ |
||
110 | |||
111 | You might wonder how your files are packaged. They can be grouped in |
||
112 | \textit{packs}. For instance, you can have one pack for the core files, one for |
||
113 | the documentation, one for the source code and so on. In this way, your end-users |
||
114 | will have the choice to install a pack or not (provided that the pack they don't |
||
115 | want to install is not mandatory). Inside the jar file (which is a zip file), a |
||
116 | sub directory contains the pack files. Each pack file contains the files that are |
||
117 | part of it. Could we do it simpler ? :-)\\ |
||
118 | |||
119 | \subsection{The Different Kinds of Installers} |
||
120 | |||
121 | There are 2 kinds of installers available : |
||
122 | \begin{itemize} |
||
123 | \item \texttt{standard} : a single-file ready-to-run installer |
||
124 | \item \texttt{web} : a web based installer (pack data is located on |
||
125 | an HTTP server, and the installer retrieves it at install time (see |
||
126 | section~\ref{webinstaller})) |
||
127 | \end{itemize} |
||
128 | |||
129 | \subsection{Installers for older VM Versions} |
||
130 | For default the installer will be made for the current most used version of |
||
131 | the java runtime environment. It is possible to create an installation that |
||
132 | is runable with an older VM version.\\ |
||
133 | What version is used can be detected in the Ant properties file that is used |
||
134 | to build IzPack. It is \texttt{[IzPackRoot]/src/ant.properties}. |
||
135 | The value of the property "source" determines the VM version.\\ |
||
136 | If compatibility to older versions is needed, a recompilation of the jar files |
||
137 | of the IzPack system should be done. For this the sources of IzPack and an Ant |
||
138 | installation are needed. The sources of IzPack are selectable at installation |
||
139 | time of IzPack. Before a recompilation of all can be triggered, the version of |
||
140 | byte code should be changed. This can be done simple by changing the "source" |
||
141 | entry in \texttt{[IzPackRoot]/src/ant.properties} to the needed value. The |
||
142 | recompilation should be performed with the current most used VM version |
||
143 | because there are classes of it referenced in the IzPack code. Usage of an |
||
144 | older VM version at installation time will be possible because the classes of |
||
145 | the newer VM version are only used after a VM version check. Of course, some |
||
146 | features of IzPack will be missing at using an old VM version. To recompile |
||
147 | IzPack go into \texttt{[IzPackRoot]/src}. Use a current JDK (not JRE) for this. |
||
148 | Call |
||
149 | \footnotesize |
||
150 | \begin{verbatim} |
||
151 | ant clean |
||
152 | \end{verbatim} |
||
153 | \normalsize |
||
154 | followed by |
||
155 | \footnotesize |
||
156 | \begin{verbatim} |
||
157 | ant all |
||
158 | \end{verbatim} |
||
159 | \normalsize |
||
160 | Then all jar files in \texttt{[IzPackRoot]/lib}, |
||
161 | \texttt{[IzPackRoot]/bin/panels} and \texttt{[IzPackRoot]/bin/customActions} |
||
162 | should be recompiled with the selected source version. |