<?xml version="1.0"?>

<!--

   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

-->

<!-- ====================================================================== -->
<!-- version $Id$ -->
<!-- ====================================================================== -->

<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
  <header>
    <title>Installing Batik</title>
  </header>

  <body>
    <section id="systemRequirements">
      <title>System requirements</title>

      <p>
        Batik requires the following to be already installed in your system:
      </p>
      <dl>
        <dt>Java Runtime Environment</dt>
        <dd>
          <p>
            A Java 1.4 or above compatible runtime environment must be present.
          </p>
        </dd>
      </dl>
    </section>

    <section id="distributions">
      <title>Choosing a distribution to download</title>

      <p>
        To install Batik, you will need to go to the
        <a href="site:download">download page</a> and download one or more ZIP
        file containing the distribution of your choice. It is good practice to
        <a href="#verify">verify the integrity</a> of the distribution files,
        especially if you are using one of our mirror sites. Here are the
        various components you will find in the download area and their intended
        use:
      </p>
      <ul>
        <li>
          <p>
            <strong>batik-</strong><em>version</em><strong>.zip</strong> (e.g.,
            <code>batik-1.6.zip</code>)
          </p>
          <p>
            The <em>binary distribution</em> contains compiled executable JAR
            files that let you get started with Batik easily. This is the
            recommended distribution if you want to look at Batik’s features,
            or you want to experiment with SVG and see the fun things you can
            do with Batik. The binary distribution comes with a set of sample
            SVG files.
          </p>
        </li>

        <li>
          <p>
            <strong>batik-src-</strong><em>version</em><strong>.zip</strong> 
            (e.g., <code>batik-src-1.6.zip</code>)
          </p>
          <p>
            The <em>source distribution</em> contains a complete snapshot of the
            Batik source code, documentation, regression tools and utilities as
            well as the script for building Batik. That distribution is a
            snapshot of the SVN repository. This is the recommended distribution
            for developers who want to dive into the code and understand how
            Batik can be integrated in their applications or how Batik can be
            extended.
          </p>
        </li>

        <li>
          <p>
            <strong>batik-docs-</strong><em>version</em><strong>.zip</strong>
            (e.g., <code>batik-docs-1.6.zip</code>)
          </p>
          <p>
            The <em>documentation bundle</em> contains a copy of 
            the Javadoc for the Batik source code.
          </p>
        </li>
      </ul>

      <p>
        We make nightly copies of the source tree available from the
        <a href="http://svn.apache.org/builds/xml-batik">Apache
          build</a> server. These builds represent the current state of
        development and may or may not be as stable as releases.
        There are two types of distributions provided:
      </p>
      <ul>
        <li>
          <p>
            <strong>batik-svn-</strong><em>date</em><strong>.zip</strong>
            (e.g., <code>batik-svn-06-03-29.zip</code>)
          </p>
          <p>
            This contains a complete copy of the Subversion repository trunk,
            including support for running <a href="site:test">regard</a>,
            Batik’s regression testing utility.  In particular this includes all
            the reference images for testing.  Developers are encouraged to get
            these or better use <a href="download.html#svn">Subversion</a>
            directly.
          </p>
        </li>
        <li>
          <p>
            <strong>batik-src-</strong><em>date</em><strong>.zip</strong>
            (e.g., <code>batik-src-06-03-29.zip</code>)
          </p>
          <p>
            This contains all the source code and libraries needed to
            build and run Batik from source, but does not include the
            testing facilities.
          </p>
        </li>
      </ul>

      <!--p>
        <a href="http://arc.mcc.id.au/batik-nightly/">Unofficial nightly
          builds</a> of the latest code from the Subversion repository trunk
        are also available.
      </p-->

      <p>
        Older releases are available from the
        <a href="http://archive.apache.org/dist/xmlgraphics/batik">Apache archives</a>.
        However, we strongly recommend using the current release of Batik.
      </p>

      <p>In all cases, the user should:</p>

      <ul>
        <li>
          Make sure a Java Development Kit (JDK) is installed on the computer
          where Batik will be installed. See the
          <a href="#systemRequirements">system requirements</a>.  Make sure
          that the <code>java</code> runtime is in the <code>PATH</code>
          environment variable.
        </li>
        <li>
          Select the directory where he/she wants to download the distribution.
        </li>
        <li>
          Download the desired distribution from the
          <a href="site:download">download page</a>.
        </li> 
        <li>
          Download the associated PGP signature (.asc) and KEYS file
          (preferable) or MD5 hash (.md5).  This must be done directly from the
          <a href="http://www.apache.org/dist/xmlgraphics/batik">Apache
            download</a> area to mean anything.
        </li>
        <li>
          Open a console and go to the directory where the distribution was
          downloaded.
        </li>
        <li>
          <a href="#verify">Verify the integrity</a> of the distribution.
        </li>
        <li>
          <p>
            Unpack the distribution with Java’s JAR utility:
          </p>
          <source>jar xvf &lt;distribution&gt;</source>
          <p>
            For example, if you have downloaded batik-1.6.zip into
            /home/IamHere, type the following at the command prompt:
          </p>
          <source>cd /home/IamHere
jar xvf batik-1.6.zip</source>
          <p>
            <strong>IMPORTANT:</strong> UNIX users, do not use the
            <code>unzip</code> utility to unpack the various Batik zip files,
            as this would not set the directories access rights properly.
          </p>
        </li>
        <li>
          <p>
            If you are using Mac OS X, you can now generate an application
            bundle for Squiggle, Batik's SVG browser:
          </p>
          <source>sh lib/make-squiggle-app.sh</source>
          <p>
            After running this script, a Finder window will be opened where
            you can find the generated Squiggle application bundle.  Drag
            this to your Applications folder to install it.
          </p>
        </li>
        <li>
          Now you can follow the instructions specific to the application you
          want to use.  For example, see the <a href="site:browser">SVG
            Browser</a> page or the <a href="site:rasterizer">SVG
            Rasterizer</a> page for an explanation on how to use these tools.
        </li>
      </ul>
    </section>

    <section id="optionalComponents">
      <title>Optional components</title>

      <p>
        By default, the Batik source distribution comes with the
        <a href="http://www.mozilla.org/rhino/">Mozilla Rhino</a> JavaScript
        Engine (<code>js.jar</code>).
      </p>
      <p>
        To enable other scripting languages support, you will only need to
        install the correct jar files in <code>lib</code> directory of Batik and
        recompile your distribution.
      </p>
      <ul>
        <li>
          For Python, you need to download Jython distribution at
          <a href="http://www.jython.org/">http://www.jython.org/</a>.  Then
          you put the <code>jython.jar</code> file in the Batik <code>lib</code>
          directory.
        </li>
        <li>
          For Tcl, you need to download Jacl &amp; TclBlend distribution at
          <a href="http://dev.scriptics.com/software/java/">http://dev.scriptics.com/software/java/</a>.
          Then you put the <code>jacl.jar</code> and <code>tcljava.jar</code>
          files in the Batik <code>lib</code> directory.
        </li>
      </ul>
      <p>
        Conversely, you can remove the <code>js.jar</code> of the Batik
        <code>lib</code> directory to remove JavaScript support and have a
        smaller distribution.
      </p>
    </section>

    <section id="dependencyGraph">
      <title>Jar file dependency graph</title>

      <warning label="Out of date">
        <p>
          Note that the dependency graph in this section is out of date,
          and needs to be updated.
        </p>
      </warning>

      <p>
        The Batik distribution comes with many jar files.  Not all of them are
        needed in every case (although the provided applications tend to use
        most of them).  The following is a diagram showing the dependencies
        between the various jar files in the Batik binary distribution (it also
        shows the major package interdependencies for source developers).
      </p>
      <p>
        Jar files in white boxes are library jar files that Batik includes from
        external sources.  The light blue boxes correspond to library jar files
        (those found in the <code>lib</code> directory of a binary distribution)
        built from Batik source code.  The dark blue boxes represent the
        application jar files.
      </p>
      <p>
        When boxes touch, the box on top depends on the box below it (there is
        no horizontal touching).  Arrows also indicate dependencies (the source
        of the arrow depends on the destination). In some cases a thick
        underline with an arrow is used to indicate that a large number of jar
        files share a common dependency, this however does not indicate any
        dependency between the jar files underlined.
      </p>
      <div class="figure"><img src="jarDependImg.png"
          alt="Batik jar file dependency graph"/></div>
      <note>
        Some jar file names are shortened for clarity.  All <code>batik</code>
        package references are short for <code>org.apache.batik</code>.
      </note>
      <p>
        It is worth pointing out that a determined/clever programmer may be able
        to pare down some of these dependencies.  For example the
        <code>batik-dom.jar</code> depends on <code>xerces.jar</code> because of
        the <code>SAXDocumentFactory</code> class in
        <code>org.apache.batik.dom.util</code>.  If you didn’t need to parse XML
        it would be possible to ignore or break this dependency and still use
        the <code>batik-dom.jar</code> file for its DOM implementation.
      </p>
    </section>
    
    <section id="verify">
      <title>Verify releases</title>
      <p>
        It is essential that you verify the integrity of the downloaded files
        using the PGP or MD5 signatures.
      </p>
      <p>
        The PGP signatures can be verified using PGP or GPG.  First download the
        <a href="http://www.apache.org/dist/xmlgraphics/batik/KEYS">KEYS</a> as well as
        the <code>asc</code> signature file for the particular distribution you
        choose.  Make sure you get these files from the
        <a href="http://www.apache.org/dist/xmlgraphics/batik/">main distribution
          directory</a>, rather than from a mirror. Then verify the signatures
        using:
      </p>
      <source>pgpk -a KEYS
pgpv batik-1.6.zip.asc</source>
      <p><em>or</em></p>
      <source>pgp -ka KEYS
pgp batik-1.6.zip.asc</source>
        <em>or</em><br/>
      <source>gpg --import KEYS
pgp batik-1.6.zip.asc</source>
      <p><em>or</em></p>
      <source>gpg --import KEYS
gpg --verify batik-1.6.zip.asc</source>
      <p>
        Alternatively, you can verify the MD5 signature on the files.  A UNIX
        program called <code>md5</code> or <code>md5sum</code> is included in
        many UNIX distributions.  It is also available as part of
        <a href="http://www.gnu.org/software/textutils/textutils.html">GNU
          Textutils</a>.  Windows users can get binary md5 programs
        from <a href="http://www.fourmilab.ch/md5/">here</a>,
        <a href="http://www.pc-tools.net/win32/freeware/console/">here</a>,
        or <a href="http://www.slavasoft.com/fsum/">here</a>.
      </p>
      <p>
        We recommend using PGP signatures as they can provide a much higher
        level of assurance compared with MD5.
      </p>
    </section>
  </body>
</document>
