% Chapter 1
\chapter{Getting started}

% Overview
\section{Overview}

To begin with, you should know what \IzPack is organized if you want to use
it. Let's go into the directory where you have installed \IzPack on your
machine. There are 3 text files and a set of directories. The most
important for the moment are \texttt{bin/ doc/ sample/}. If you are reading this,
you already know that \texttt{doc} contains this documentation :-)\\

So let's go into \texttt{bin/}. The \texttt{icons/} directory contains some
directories for your system, in case you would like an icon to launch a
component of \IzPack. But the most important things you can see in \texttt{bin}
are the \texttt{compile} scripts (in both Unix* and Windows formats).
\texttt{compile} is used to compile a ready-to-go XML installation file from
a command-line context or from an external tool.\\

\noindent
\textit{Note : these scripts can be launched from anywhere on your system as the
installer has customized these scripts so that they can inform \IzPack of where
it is located.}\\

% First Compilation
\section{First Compilation}

Now you probably can't wait to build your first installer. So go on open a
command-line shell and navigate to \texttt{sample/}. The following should work
on both Unix* and Windows systems. For the latter, just change the path
separator (slash '/') to a backslash. So type (\$ is your shell prompt !) :
\begin{verbatim}
$ ../bin/compile install.xml -b . -o install.jar -k standard
 (installer generation text output here)
$ java -jar install.jar
\end{verbatim}

There you are! The first command has produced the installer and the
second one did launch it.

% The IzPack Architecture
\section{The \IzPack Architecture}

Now that you have packaged your first installer, it's time for you to understand
how the whole thing works.\\

\subsection{The Compilation System}

The compilation system (see figure \ref{comparch}) is quite modular. 
Indeed, you can use the compiler in 2 ways :
\begin{itemize}
  \item from a command-line
  \item from Jakarta Ant
\end{itemize}\

\begin{figure}[h]
\caption{\label{comparch}
         \textit{The compiler architecture.}}
\begin{center}
\fbox{\includegraphics[scale=0.4]{img/ch1-comparch}}
\end{center}
\end{figure}

The compiler takes as its input an XML installation file that describes
(at a relatively high-level) the installation. This file contains
detailed information such as the application name, the authors, the
files to install, the panels to use, which resources to load and much
more (see figure \ref{archinstaller}).\\

The compiler can generate different kinds of installers, but this information is
not located inside the XML file as it is not were it should be. On the contrary,
this is a compiler parameter.\\

The compilation options for a command-line installer are the following:
\begin{itemize}
\item \texttt{-?}: gives a list of the available options.
\item \texttt{-b}: specifies the base path, \textsl{ie} the one that will be
used to resolve the relative paths. If your XML file contains absolute paths,
specify it to an empty string (\texttt{-b ""}).
\item \texttt{-k}: specifies the installer kind, for instance most users will
want \texttt{standard} here.
\item \texttt{-o}: specifies the resulting installer Jar file name.
\end{itemize}\

\subsection{How an Installer Works}

An installer presents its panels to the end-user. For instance, there is
one to select the packages, one to prompt for the license agreement, one
to select the installation path and so on. You have a choice from a
variety of panels to place in the installer. For example, you can choose
between a plain text and a HTML text panel for the license agreement.
Also, if you don't want of the \textit{HelloPanel}, you just don't
include it.\\ 

\begin{figure}[h]
\caption{\label{archinstaller}
         \textit{The installer architecture.}}
\begin{center}
\fbox{\includegraphics[scale=0.4]{img/ch1-compinside}}
\end{center}
\end{figure}

It is very important to understand that some of the panels may need extra data. For
instance, the license agreement panel needs the license text. A simple approach
to specify such data would have been to add as many XML tags as needed for
each panel. However, this makes the XML file too specific and not easy to
maintain. The approach that has been chosen is to put the data in files and we
call these files \textit{resource files}. They are specified with a unique XML
tag. This is a much cleaner approach.\\

You might wonder how your files are packaged. They can be grouped in
\textit{packs}. For instance, you can have one pack for the core files, one for
the documentation, one for the source code and so on. In this way, your end-users
will have the choice to install a pack or not (provided that the pack they don't
want to install is not mandatory). Inside the jar file (which is a zip file), a
sub directory contains the pack files. Each pack file contains the files that are
part of it. Could we do it simpler ? :-)\\

\subsection{The Different Kinds of Installers}

There are 2 kinds of installers available :
\begin{itemize}
  \item \texttt{standard} : a single-file ready-to-run installer
  \item \texttt{web} : a web based installer (pack data is located on
  an HTTP server, and the installer retrieves it at install time (see
  section~\ref{webinstaller}))
\end{itemize}

\subsection{Installers for older VM Versions}
For default the installer will be made for the current most used version of
the java runtime environment. It is possible to create an installation that
is runable with an older VM version.\\
What version is used can be detected in the Ant properties file that is used 
to build IzPack. It is \texttt{[IzPackRoot]/src/ant.properties}. 
The value of the property "source" determines the VM version.\\
If compatibility to older versions is needed, a recompilation of the jar files 
of the IzPack system should be done. For this the sources of IzPack and an Ant
installation are needed. The sources of IzPack are selectable at installation
time of IzPack. Before a recompilation of all can be triggered, the version of 
byte code should be changed. This can be done simple by changing the "source" 
entry in \texttt{[IzPackRoot]/src/ant.properties} to the needed value. The 
recompilation should be performed with the current most used VM version 
because there are classes of it referenced in the IzPack code. Usage of an 
older VM version at installation time will be possible because the classes of
the newer VM version are only used after a VM version check. Of course, some 
features of IzPack will be missing at using an old VM version. To recompile
IzPack go into \texttt{[IzPackRoot]/src}. Use a current JDK (not JRE) for this. 
Call
\footnotesize
\begin{verbatim}
ant clean
\end{verbatim}
\normalsize
followed by
\footnotesize
\begin{verbatim}
ant all
\end{verbatim}
\normalsize
Then all jar files in \texttt{[IzPackRoot]/lib}, 
\texttt{[IzPackRoot]/bin/panels} and \texttt{[IzPackRoot]/bin/customActions}
should be recompiled with the selected source version.