| <?xml version="1.0" standalone="no"?> |
| <!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd"> |
| <!-- |
| * 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. |
| --> |
| <!-- $Id$ --> |
| <s1 title="Download/Build & Dependencies"> |
| <ul> |
| <li><link anchor="latest-release">Downloading the latest release</link></li> |
| <li><link anchor="download">Downloading what else you might need</link></li> |
| <li><link anchor="whereis_xml4j">Where do I get &xml4j;? </link></li> |
| <li><link anchor="viewcode">How do I view Xalan code in a browser?</link></li> |
| <li><link anchor="buildmyself">How do I download the latest development code to build myself?</link></li> |
| <li><link anchor="using-ant">Using ant</link></li> |
| <li><link anchor="samples">Rebuilding a sample application</link></li> |
| <li><link anchor="previous-releases">Where do I download previous releases?</link></li> |
| </ul> |
| <anchor name="latest-release"/> |
| <s2 title="Downloading the latest release"> |
| <p> You can download the pre-built binary distributions from one of the |
| mirror sites at <resource-ref idref="xslt4j-distdir"/>. |
| </p> |
| |
| <p>Xalan-J has two processors, |
| an interpretive one, Xalan Interpretive, and a compiled one, Xalan Compiled (XSLTC). |
| Your choice of which binary distribution to download depends on which |
| of the processors you want to use. |
| There are 2 binary distributions available; you only need to choose one of them. |
| Both binary distributions contain <code>xml-apis.jar</code> and <code>&xml4j-jar;</code> from <resource-ref idref="xml4j-used"/>.</p> |
| <ul> |
| <li>The first binary distribution, <code>&xslt4j-dist-bin;.zip</code> or |
| <code>&xslt4j-dist-bin;.tar.gz</code>, |
| contains the Xalan Interpretive processor, the Xalan Compiled processor (XSLTC) and the |
| runtime support packages in a single jar, called <code>xalan.jar</code>. |
| The reason to use this distribution would be that you don't know |
| which processor you are going to use, or might be using both. |
| </li><br/><br/> |
| <li>The second binary distribution, <code>&xslt4j-dist-bin;-2jars.zip</code> or |
| <code>&xslt4j-dist-bin;-2jars.tar.gz</code> |
| contains the Xalan Interpretive processor in <code>xalan.jar</code>, and the Xalan Compiled |
| processor (XSLTC) and the runtime support packages in <code>xsltc.jar</code>. |
| The reason to using this distribution is that you want more control. |
| If you are using just XSLTC you can put <code>xsltc.jar</code> on the classpath |
| and not <code>xalan.jar</code>. If you are using just the interpretive processor |
| you can put xalan <code>xalan.jar</code> on the classpath and not <code>xsltc.jar</code>. Of course |
| you can put both <code>xalan.jar</code> and <code>xsltc.jar</code> from this distribution |
| on your classpath if you want to use both. |
| </li> |
| </ul> |
| |
| |
| <p> |
| We provide two distributions: a binary distribution, and a source distribution. |
| You can also download a source distribution from one of the same |
| mirror sites at <resource-ref idref="xslt4j-distdir"/>. The difference |
| is that a binary distribution contains <em>-bin</em> in its name, |
| whereas a source distribution contain <em>-src</em> in its name. |
| </p> |
| |
| <p>To use &xslt4j;, you need the following which are available from |
| either a binary or source distribution:</p> |
| <ul> |
| <li><code>xml-apis.jar</code> JAXP APIs</li> |
| <li><code>&xml4j-jar;</code> (or another <link idref="usagepatterns" anchor="plug">XML Parser</link>)</li> |
| <li><code>xalan.jar</code></li> |
| <li><code>xsltc.jar</code> the XSLTC processor, if you choose a 2jars distribution</li> |
| <li><code>serializer.jar</code> which are the serializer classes of |
| &xslt4j;</li> |
| </ul> |
| <p> |
| If you have downloaded a binary distribution, you already have a build |
| (you have the jars). This is also true for a source distribution, however |
| if you downloaded a source distribution, |
| you have the option to use Ant to build &xslt4j;, |
| including <code>xalan.jar</code>, <code>xsltc.jar</code>, <code>serializer.jar</code> |
| and other things, see <link anchor="using-ant">Using Ant</link> for more |
| details. |
| </p> |
| |
| |
| </s2> |
| <anchor name="download"/> |
| <s2 title="Downloading what else you might need"> |
| <p>To use &xslt4j;, you need the following:</p> |
| <ul> |
| <li>The JDK or JRE 1.3.x, 1.4.x, or 5.x</li> |
| </ul> |
| <p> |
| You can get the JDK or JRE from <jump href="http://www-128.ibm.com/developerworks/java/jdk/index.html"> |
| IBM developerWorks</jump> or <jump href="http://www.java.sun.com">java.sun.com</jump>. |
| </p> |
| <p>If you plan to run <link idref="extensions">XSLT extensions</link> |
| through extension functions or elements, and you want to implement |
| that support in languages |
| other than Java, then you will need an implementation of the Bean Scripting Framework (BSF). |
| An open source implementation is available for download from Apache. See the |
| <jump href="http://jakarta.apache.org/bsf/index.html">Apache Jakarta |
| BSF project</jump>. If you plan to run XSLT extensions implemented in scripting |
| languages, you will need <code>bsf.jar</code> and one or more additional files as indicated in |
| <link idref="extensions" anchor="supported-lang">extensions language requirements</link>. |
| </p> |
| </s2> |
| |
| <anchor name="whereis_xml4j"/> |
| <s2 title="Where do I get &xml4j;?"> |
| <p> |
| The &xslt4j-current; has been tested with &xml4j-used;. |
| </p> |
| <p><em>Important:</em> You may experience unpredictable anomalies |
| if your &xslt4j; and &xml4j; builds are not in synch. |
| If you download an update to &xslt4j;, check the |
| <link idref="readme">release notes</link> |
| to determine which version of &xml4j; you should use. |
| </p> |
| <note> |
| You can use &xslt4j; with other XML parsers that implement |
| the <resource-ref idref="jaxp13-longname-withacronym"/>. |
| See <link idref="usagepatterns" anchor="plug">Plugging in the Transformer and XML parser</link>. |
| </note> |
| <p> |
| The &xslt4j; download includes <code>&xml4j-jar;</code> from &xml4j-used;. In conjunction with <code>xml-apis.jar</code>, |
| this is all you need to run &xslt4j; with the &xml4j; XML parser. You can, however, download the |
| complete &xml4j; binary or source distribution from the <resource-ref idref="xml4j-distdir"/>. |
| If you cannot find &xml4j-used; at that location, have a look at the |
| <jump href="http://archive.apache.org/dist/xml/xerces-j/">Apache archive location for |
| Xerces Java</jump>. |
| </p> |
| <note> |
| If you plan to use a different XML parser, see <link idref="usagepatterns" anchor="plug">Plugging |
| in a Transformer and XML parser</link>. |
| </note> |
| </s2> |
| |
| <anchor name="viewcode"/> |
| <s2 title="How do I view Xalan code in a browser?"> |
| <p> |
| If you wish to view some of Xalan's files in a browser without downloading the |
| whole project you can view it at |
| <jump href="http://svn.apache.org/viewvc/xalan/">http://svn.apache.org/viewvc/xalan/</jump> |
| or at |
| <jump href="http://svn.apache.org/repos/asf/xalan/">http://svn.apache.org/repos/asf/xalan/</jump>. |
| The link with "viewvc" in it is slightly prettier. |
| </p> |
| <p> |
| The java/trunk and test/trunk subdirectories are the ones with the latest development code. |
| </p> |
| </s2> |
| |
| |
| <anchor name="buildmyself"/> |
| <s2 title="How do I download the latest development code to build myself?"> |
| <p> |
| If you have downloaded a source distribution, or obtained source code |
| using subversion, this section may be of interest to you. |
| </p> |
| <p> |
| If you wish to download Xalan and build it yourself, perhaps because you want to |
| apply a patch and test it, you will need a subversion client and anonymous access |
| to the repository. |
| Don't worry, everyone has anonymous access. |
| You can find pre-built binaries of subversion clients for different |
| operating systems here: |
| <jump href="http://subversion.tigris.org/project_packages.html#binary-packages"> |
| http://subversion.tigris.org/project_packages.html#binary-packages</jump>. |
| See |
| <jump href="http://www.apache.org/dev/version-control.html"> |
| http://www.apache.org/dev/version-control.html |
| </jump> for more information on Apache and subversion. |
| </p> |
| <p> |
| Once the subverion client is installed on your local machine you |
| can use the command line client program <em>svn</em> |
| to get the latest Xalan-J using a command line something like this: |
| <source> |
| svn checkout http://svn.apache.org/repos/asf/xalan/java/trunk java |
| </source> |
| where the argument after <em>checkout</em> is the Subversion repository location, |
| in this case the location of the latest development code, and the last argument, |
| in this case <em>java</em> is the location of the local directory that the repository is |
| copied to. |
| </p> |
| <p> |
| Similarly for the test harness, you can download the latest test harness with a Subversion command |
| something like this: |
| <source> |
| svn checkout http://svn.apache.org/repos/asf/xalan/test/trunk test |
| </source> |
| </p> |
| <p> |
| Those two commands will put a copy of the latest parts in the local |
| directories <em>java</em> and <em>test</em>, |
| which are sibling directories. If you |
| want to test your build with |
| the test harness provided with Xalan then it is easiest if you keep the |
| local directory names |
| as suggested. With your paths set up to compile Java code, go into the local <em>java</em> |
| directory and issue these two commands: |
| <source> |
| build clean |
| build |
| </source> |
| </p> |
| <p> |
| The <em>build.bat</em> batch file, or <em>build.sh</em> shell script (depending on |
| your operating system use <em>ant</em> and the buildfile <em>build.xml</em>. See |
| the section <link anchor="jar">Using ant</link> for more information. |
| </p> |
| <p> |
| Other useful targets may be <code>xsltc.jar</code> or <code>serializer.jar</code>. |
| If you want to test the jars you just built in the directory <em>java/build</em>, change to |
| directory <em>test</em> and issue this command: |
| <source> |
| build jar |
| build smoketest |
| </source> |
| The first target, <em>jar</em> builds the test harness and only needs to be done |
| once after the <em>test</em> repository is checked out. The second target, <em>smoketest</em>, |
| runs the Xalan-J intepretive smoketest. |
| Running the <em>build smoketest</em> or other targets in the <em>test</em> directory |
| automatically looks for the jars in the directory <em>../java/build</em> |
| and that is why it is easiest to download the projects into suggested sibling |
| directories with the given names. |
| </p> |
| <p> |
| Towards the end of the console output you will see <em>two CONGRATULATIONS!</em> messages if all |
| goes well. The end of the console output should look like this: |
| <source> |
| . |
| . |
| . |
| minitest-pass: |
| [echo] [minitest] CONGRATULATIONS! The Minitest passed! |
| [echo] [minitest] See details in smoketest/Minitest.xml |
| |
| smoketest-notpass: |
| |
| smoketest-pass: |
| [echo] [minitest] CONGRATULATIONS! The Smoketest passed! |
| [echo] [minitest] Details are in smoketest/results-conf.xml, smoketest/results-api.xml, smoketest/extensions/results-extensions.xml |
| |
| smoketest: |
| |
| BUILD SUCCESSFUL |
| Total time: 2 minutes 4 seconds |
| build completed! |
| </source> |
| </p> |
| <p> |
| Don't be fooled by the <em>BUILD SUCCESSFUL</em> messages, look for the two CONGRATULATIONS! |
| messages. If you run the smoketest for XSLTC with <em>build smoketest.xsltc</em> you wil |
| only get one CONGRATULATIONS! message if all goes well. |
| </p> |
| </s2> |
| |
| <anchor name="using-ant"/> |
| <s2 title="Using Ant To Build"> |
| <p> |
| If you have downloaded a source distribution, or obtained source code |
| using subversion, this section may be of interest to you. |
| </p> |
| |
| <p>Apache <resource-ref idref="ant"/> is a flexible, powerful, and easy-to-use Java build tool that we include with the |
| &xslt4j; distribution. The Ant JAR file is in the tools directory, and the cross-platform XML build file (build.xml) is in |
| the root directory along with a Windows32 batch file (build.bat) and a UNIX shell file (build.sh). The build file defines |
| the "targets" that you can use Ant to build. The batch and shell files set up the classpath and launch Ant with the target |
| (and any other arguments) you provide.</p> |
| <p><em>Instructions for using Ant</em></p> |
| <ol> |
| <li>Set the JAVA_HOME environment variable to the JDK root directory.<br/><br/> |
| JDK 1.3.1 or higher is required to build &xslt4j;. You must put <code>tools.jar</code> from the JDK |
| bin directory on the classpath.<br/><br/></li> |
| <li>Depending on your environment, run the batch file (build.bat) or shell file (build.sh) |
| from the &xslt4j; root directory, optionally with arguments (see the table of targets below).<br/><br/> |
| The batch/shell file adds several JAR files to the classpath and launches Ant with any arguments |
| you provide. If you provide no target, Ant compiles the source files and rebuilds <code>xalan.jar</code> |
| (the "jar" target).</li> |
| </ol> |
| |
| <p>The &xslt4j; source code tree is in the src directory. |
| </p> |
| <p> |
| If you are using Ant, the target is jar (the default). |
| </p> |
| |
| <p>You can also set up your classpath manually (see build.bat or build.sh for the details), and |
| then run Ant as follows:<br/><br/> |
| <code>java org.apache.tools.ant.Main <ref>target</ref></code><br/><br/> |
| where <ref>target</ref> is nothing (for the default target) or one of the following.</p> |
| <table> |
| <tr><td><em>Ant Target</em></td><td><em>What Ant does</em></td></tr> |
| <tr><td>compile</td><td>compiles &xslt4j; in build/classes.</td></tr> |
| <tr><td>jar (the default)</td><td>creates xalan.jar and serializer.jar in the build directory</td></tr> |
| <tr><td>serializer.jar</td><td>creates serializer.jar in the build directory</td></tr> |
| <tr><td>xsltc.jar</td><td>creates xsltc.jar in the build directory</td></tr> |
| <tr><td>samples</td><td>compiles and jars the sample apps in build/xalansamples.jar</td></tr> |
| <tr><td>servlet</td><td>compiles and jars the sample servlet in build/xalanservlet.jar</td></tr> |
| <tr><td>docs</td><td>creates the HTML User's Guide in build/docs</td></tr> |
| <tr><td>javadocs</td><td>generates the API documentation in ./build/docs/apidocs</td></tr> |
| <tr><td>fulldist</td><td>generates a complete distribution tree with zip and tar.gz distribution files in build</td></tr> |
| <tr><td>clean</td><td>purges the build and distribution</td></tr> |
| </table> |
| <p>If you build a target that depends on other targets, Ant creates those other targets in the correct order. |
| </p> |
| <p><em>Building without Ant</em></p> |
| <p>If you want to do the build without Ant, keep the following in mind: |
| </p> |
| <ul> |
| <li>Set the classpath to include the src directory, <code>&xml4j-jar;</code>, and <code>xml-apis.jar</code>.</li> |
| <li>Use a Java compiler (such as the IBM Just-In-Time compiler or the Sun javac) to compile all the .java files in the src |
| tree. </li> |
| <li>Use the <code>jar</code> utility to store the resulting .class files in <code>xalan.jar</code></li> |
| </ul> |
| |
| </s2> |
| |
| <anchor name="samples"/> |
| <s2 title="Rebuilding a sample application"> |
| <p>If you modify a sample and want to recompile it, you can run the Java compiler in the directory containing the |
| example. Be sure <code>xalan.jar</code>, <code>serializer.jar</code>, <code>xml-apis.jar</code>, and <code>&xml4j-jar;</code> are on the classpath. </p> |
| <p>To recompile and run the class files in the servlet subdirectory, the javax.servlet and |
| javax.servlet.http packages must also be on the classpath. These packages are available via |
| the <code>servlet.jar</code> file found in Apache Tomcat ( see <resource-ref idref="tomcat"/> ).</p> |
| <p>After recompiling a sample, you can use the jar utility to place your new .class files in |
| <code>xalansamples.jar</code>.</p> |
| <p>You can use Ant with the samples target to recompile the samples and place the unpackaged class files in <code>xalansamples.jar</code>. |
| For more information, see <link anchor="ant">Using Ant</link>.</p> |
| <note>To rebuild (and to run) the sample servlet, the javax.servlet and javax.servlet.http packages must be on your |
| classpath.</note> |
| </s2> |
| |
| <anchor name="previous-releases"/> |
| <s2 title="Where do I download previous releases?"> |
| <p> |
| To access previous releases, see the <resource-ref idref="xslt4j-distdir-previous"/>. |
| </p> |
| </s2> |
| |
| </s1> |