<?xml version="1.0" encoding="ISO-8859-1"?>

<!--
  
  The IzPack Launcher
  http://www.izforge.com/izpack/
  http://developer.berlios.de/projects/izpack/

  Copyright (c) 2004, 2005 Julien Ponge - All rights reserved.

  Redistribution and use in source (XML DocBook) and 'compiled' forms (XML,
  (X)HTML, PDF, PostScript, RTF and so forth) with or without modification, are
  permitted provided that the following conditions are met: 

  1. Redistributions of source code (XML DocBook) must retain the above copyright
  notice, this list of conditions and the following disclaimer as the first lines
  of this file unmodified. 

  2. Redistributions in compiled form (transformed to other DTDs, converted to
  PDF, PostScript, RTF and other formats) must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

  Important: THIS DOCUMENTATION IS PROVIDED BY THE IZPACK PROJECT "AS IS" AND ANY
  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  DISCLAIMED. IN NO EVENT SHALL THE IZPACK PROJECT BE LIABLE FOR
  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

-->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
        <!ENTITY launcher-license SYSTEM "../../LICENSE">
        <!ENTITY sample-launcher-ini SYSTEM "../../src/launcher.ini">
        ]>

<book>

    <!-- Headers -->
    <bookinfo>
        <title>IzPack launcher manual</title>
        <copyright>
            <year>2004, 2005</year>
            <holder>Julien PONGE</holder>
        </copyright>
        <legalnotice>
            <title>Legal notice</title>
            <para>The IzPack Launcher</para>
            <para>
                <ulink url="http://www.izforge.com/izpack/">http://www.izforge.com/izpack/</ulink>
            </para>
            <para>
                <ulink url="http://developer.berlios.de/projects/izpack/">http://developer.berlios.de/projects/izpack/
                </ulink>
            </para>
            <para>Redistribution and use in source (XML DocBook) and 'compiled' forms (XML,
                (X)HTML, PDF, PostScript, RTF and so forth) with or without modification, are
                permitted provided that the following conditions are met:
                <orderedlist>
                    <listitem>
                        <para>Redistributions of source code (XML DocBook) must retain the above copyright
                            notice, this list of conditions and the following disclaimer as the first lines
                            of this file unmodified.
                        </para>
                    </listitem>
                    <listitem>
                        <para>Redistributions in compiled form (transformed to other DTDs, converted to
                            PDF, PostScript, RTF and other formats) must reproduce the above copyright
                            notice, this list of conditions and the following disclaimer in the
                            documentation and/or other materials provided with the distribution.
                        </para>
                    </listitem>
                </orderedlist>
                <emphasis>Important:</emphasis>
                THIS DOCUMENTATION IS PROVIDED BY THE IZPACK PROJECT "AS IS"
                AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
                WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
                DISCLAIMED. IN NO EVENT SHALL THE IZPACK PROJECT BE LIABLE FOR
                ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
                (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
                LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
                ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
                (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
                DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
            </para>
        </legalnotice>
    </bookinfo>

    <!-- Chapter 1 -->
    <chapter>
        <title>Overview</title>

        <sect1>

            <title>Introduction</title>

            <para>The
                <ulink url="http://www.izforge.com/izpack/">IzPack</ulink>
                project
                allows you to prepare some installers for your applications. Those installers
                can be used identically no matter what the target operating system is because
                it has been implemented with the Java technology. This means that the same
                installer file can be distributed to your Linux, FreeBSD, Win32 and Mac users.
                While this is already a big advantage over preparing an installer or a package
                for each platform, it still relies on the hypothesis that your users already
                have a well installed Java Runtime Environment (JRE) on their systems.
            </para>

            <para>While corporate users should be able to install a JRE by themselves,
                this might not always be the case. Worse, the average home user might not know
                what a JRE is and he might not understand why your installer can't be launched.
            </para>

        </sect1>

        <sect1>

            <title>What the native launcher solves</title>

            <para>The IzPack native launcher solves the previous problem by offering
                a native executable to your users. Thus, they will launch it instead of directly
                trying to launch the Java-based installer. What's more, Win32 users will be more
                familiar with a native executable than a Jar file.
            </para>

            <para>The IzPack launcher will do the following things when executed:
                <itemizedlist>
                    <listitem>
                        <para>check for a JVM on the system</para>
                    </listitem>
                    <listitem>
                        <para>launch the installer if a valid JVM has been found</para>
                    </listitem>
                    <listitem>
                        <para>offer the following choices in case no JVM could be found:
                            <itemizedlist>
                                <listitem>
                                    <para>manually locate a 'java' executable</para>
                                </listitem>
                                <listitem>
                                    <para>(optional) install a JVM that is provided by the package
                                        maker, for instance on a CD-ROM
                                    </para>
                                </listitem>
                                <listitem>
                                    <para>download a JVM from the internet</para>
                                </listitem>
                            </itemizedlist>
                        </para>
                    </listitem>
                </itemizedlist>
            </para>

            <figure>
                <title>The JRE detection failure and resolution dialog.</title>
                <mediaobject>
                    <imageobject>
                        <imagedata fileref="failure-dialog.png" format="PNG"/>
                    </imageobject>
                </mediaobject>
            </figure>

            <para>The IzPack launcher is implemented in C++ and makes use of the portable
                <ulink url="http://www.trolltech.com/">Trolltech Qt</ulink>
                toolkit. Thus, the IzPack
                launcher can be run on several platforms (*nix, MacOS, Win32).
            </para>

            <para>The IzPack launcher is published under a MIT-style license agreement:
                <screen>&launcher-license;</screen>
            </para>

        </sect1>

        <sect1>

            <title>Getting the IzPack launcher</title>

            <para>The IzPack launcher can be downloaded from
                <ulink url="http://developer.berlios.de/project/showfiles.php?group_id=1408">BerliOS</ulink>
                of from the<ulink url="http://www.izforge.com/izpack/">IzPack homepage</ulink>.
            </para>

            <para>IzPack makes use of<ulink url="http://subversion.tigris.org/">SubVersion</ulink>.
                You can download the development version ('trunk') by following the instructions at
                <ulink url="http://developer.berlios.de/svn/?group_id=1408">
                    http://developer.berlios.de/svn/?group_id=1408
                </ulink>
                You can also get here the various releases ('tags').
            </para>

            <para>The IzPack launcher archive comes with the full source code, the documentation as well
                as a sample configuration file. It also contains a build for the Win32 platform, so that you
                can use it directly on this platform.
            </para>

        </sect1>

        <sect1>

            <title>Building the IzPack launcher from the source code</title>

            <para>There are many reasons why you would want to build the IzPack launcher from the source code, be it to
                compile it for your specific environment, to make a few adaptations to your needs or simply because you
                would
                like to hack on it.
            </para>

        </sect1>

        <sect2>

            <title>Building with Qt/X11</title>

            <para>The X11 port of Qt includes the Linux-based distributions, the commercial Unix variants or
                the BSD systems family. These systems generally come with a complete compilation toolchain with the
                GCC compiler. All you really need is to get Qt/X11 installed properly. Once this is done, you can build
                the launcher this way:
                <screen>cd src/
                    qmake launcher.pro
                    make
                </screen>
            </para>

        </sect2>

        <sect2>

            <title>Building with Qt/Win32</title>

            <para>TO BE ADDED</para>

        </sect2>

    </chapter>

    <!-- Chapter 2 -->
    <chapter>
        <title>Using the launcher</title>

        <sect1>

            <title>Preparing the launcher directory layout</title>

            <para>First of all, you can put in a fresh directory the Win32 executable that you can find
                in the 'dist' directory of the IzPack launcher distribution. Then you can pick
                the translations that you need by copying the related files, for instance
                <filename>launcher_fr.qm</filename>. Finally, you'll need
                to create a
                <filename>launcher.ini</filename>
                configuration file in order to tweak the launcher
                behaviour.
            </para>

        </sect1>

        <sect1>

            <title>Preparing the configuration file</title>

            <para>The configuration file is quite simple. It has groups and entries. The top-level
                entries (those not belonging to a group) can be overridden by some operating system ones.
                To customize the behaviour for a specific operating system, you just have to create a group
                whose name matches the operating system identifier. Then you can simply override the entries.
            </para>

            <para>The entries are the following:
                <itemizedlist>
                    <listitem>
                        <para>jar: specifies the installer Jar file to launch</para>
                    </listitem>
                    <listitem>
                        <para>jre: the path to a JRE that the user can install if none has been found
                            on his system
                        </para>
                    </listitem>
                    <listitem>
                        <para>download: the URL to get a JVM from.</para>
                    </listitem>
                </itemizedlist>
                The 'jre' entry is not mandatory.
            </para>

            <para>The following operating systems identifiers can be used to make groups:
                <itemizedlist>
                    <listitem>
                        <para>win32</para>
                    </listitem>
                    <listitem>
                        <para>x11</para>
                    </listitem>
                    <listitem>
                        <para>mac</para>
                    </listitem>
                </itemizedlist>
            </para>

        </sect1>

        <sect1>

            <title>Sample configuration file</title>

            <programlisting linenumbering="numbered">&sample-launcher-ini;</programlisting>

        </sect1>

    </chapter>

    <!-- Appendix -->
    <appendix>
        <title>Acknowledgements</title>
        <para>
            <itemizedlist>
                <listitem>
                    <para>The BerliOS crew</para>
                </listitem>
                <listitem>
                    <para>Trolltech for making Qt so wonderful.</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>The IzPack launcher 1.x series had this acknowledgement:
            <itemizedlist>
                <listitem>
                    <para>Marcus Stursberg (German translation)</para>
                </listitem>
                <listitem>
                    <para>Frank Bille Jensen (Danish translation)</para>
                </listitem>
                <listitem>
                    <para>Elmar Grom (user feedback suggestions)</para>
                </listitem>
                <listitem>
                    <para>Alex Carlos Braga Antao (Brazilian translation)</para>
                </listitem>
                <listitem>
                    <para>David Perez Carmona (Spanish translation)</para>
                </listitem>
                <listitem>
                    <para>Dustin Sacks (Win98 fixes)</para>
                </listitem>
                <listitem>
                    <para>The BerliOS crew</para>
                </listitem>
                <listitem>
                    <para>The wxWidgets crew.</para>
                </listitem>
            </itemizedlist>
        </para>
    </appendix>

</book>
