Application: gvSIG desktop

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

<!--

  IzPack native launcher manual.

  Copyright (c) 2004 Julien PONGE. All Rights Reserved.

  http://www.izforge.com/

  <julien@izforge.com>

  <julien_ponge@yahoo.fr>

-->

<!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</year><holder>Julien PONGE</holder></copyright>

  <legalnotice>

    <title>Legal notice</title>

    <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 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.wxwidgets.org/">wxWidgets</ulink> toolkit. Thus, the IzPack

  launcher can be run on several platforms (*nix, MacOS, Win32). It has been successfully

  tested on the following platforms configurations:

  <itemizedlist>

    <listitem><para>Linux / wxGTK / GCC</para></listitem>

    <listitem><para>FreeBSD / wxGTK / GCC</para></listitem>

    <listitem><para>Win32 / MSW / MinGW</para></listitem>

  </itemizedlist></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>

</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. You can also pick the

  manifest file that will make the launcher GUI use the XP look and feel. Then you can also pick

  the translations that you need by copying the related directories. 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>linux</para></listitem>

    <listitem><para>solaris</para></listitem>

    <listitem><para>bsd</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>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>