xdocs/sources/xalan/getstarted.xml

<?xml version="1.0" standalone="no"?>  
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">

<s1 title="Getting Started with Xalan-C++">
<ul>
<li><link anchor="download">Downloading what you need</link></li>
<li><link anchor="path">Setting up the path/library path</link></li>
<li><link anchor="samples">Trying out the samples</link></li>
<li><link anchor="commandline">Performing your own transformations from the command line</link></li>
<li><link anchor="apps">Setting up your own XSLT applications</link></li>
</ul>
<anchor name="download"/>
<s2 title="Downloading what you need">
<p>For &xslt4c-current;, we are distributing a Windows32 Visual C++ build and four UNIX builds with a makefile: a Red Hat Linux GNU build, an AIX xlC build, an HP-UX 11 aCC build, and a Solaris build. 
Please contact us at <human-resource-ref idref="xalandev"/> if you would like to help provide builds for other platforms.</p>
<anchor name="xalandists"/>
<s3 title="&xslt4c; Windows Distribution">
<p><img src="xalan-c-windist.gif" alt="xalan-c-windist.gif"/></p>
</s3>
<p>For the Windows32 build, download <resource-ref idref="xslt4c-win32-download"/>. This Windows32 distribution was built with MSVC 6.0 SP3 and <jump href="http://www.dinkumware.com/vc_fixes.html">Dinkumware C++ library fixes</jump>.</p>
<s3 title="&xslt4c; UNIX Distributions">
<p><img src="xalan-c-unixdist.gif" alt="xalan-cdist.gif"/></p>
</s3>
<p>For the Linux build, download <resource-ref idref="xslt4c-linux-download"/>. This Red Hat Linux 6.1 distribution was built with egcs-2.91.66 and glibc-2.1.2-11.</p>
<p>For the AIX build, download <resource-ref idref="xslt4c-aix-download"/>. This AIX 4.3 distribution was built with IBM C and C++ for AIX 5.02.</p>
<p>For the HP-UX 11 build, download <resource-ref idref="xslt4c-hp-ux-download"/>. This HP-UX 11 distribution was built with aCC A.03.27.</p>
<p>For the Solaris build, download <resource-ref idref="xslt4c-Solaris-download"/>. This Solaris distribution was built with Sun Workshop 6 update 2.</p>
<note>Use GNU tar to untar the Solaris distribution file; see <link idref="faq" anchor="gnutar">A tar checksum error on Solaris </link>.</note>
<p>Each distribution contains all you need to run the Xalan command-line transformations utility and to build your own applications. 
If you want to take advantage of the support for number formatting, sorting, and encoding the ICU provides, you should also download and install the <resource-ref idref="icu"/>; see <link idref="usagepatterns" anchor="icu">Using the ICU</link>,</p>
<s3 title="What you need to run the Xalan command-line utility">
<p>To run the Xalan executable for performing transformations, you need the following:</p>
<p><em>Windows32</em></p>
<ul>
<li>The executable: Xalan.exe or TestXSLT.exe</li>
<li>The Xalan-C++ dynamic link libraries: &xslt4c-windlls;</li>
<li>The Xerces-C++ dynamic link library: &xml4c-windll;</li>
</ul>

<p><em>Linux</em></p>
<ul>
  <li>The executable: Xalan or testXSLT</li>
  <li>The Xalan-C++ shared library: &xslt4c-linuxlib;</li>
  <li>The Xerces-C++ shared library: &xml4c-linuxlib;</li>
</ul>
<p><em>AIX</em></p>
<ul>
  <li>The executable: Xalan or testXSLT</li>
  <li>The Xalan-C++ load library: &xslt4c-aixlib;</li>
  <li>The Xerces-C++ load library: &xml4c-aixlib;</li>
</ul>
<p><em>HP-UX 11</em></p>
<ul>
  <li>The executable: Xalan or testXSLT</li>
  <li>The Xalan-C++ shared library: &xslt4c-hplib;</li>
  <li>The Xerces-C++ shared library: &xml4c-hplib;</li>
</ul>
<p><em>Solaris</em></p>
<ul>
  <li>The executable: Xalan or testXSLT</li>
  <li>The Xalan-C++ shared library: &xslt4c-solarislib;</li>
  <li>The Xerces-C++ shared library: &xml4c-solarislib;</li>
</ul>
<p>If you want to enable ICU support for the command-line utility, you must build the ICU and rebuild the Xalan-C++ shared/load library (Linux/AIX/HP-UX 11) and Xalan or TestXSLT (all platforms) with the ICUBridge. See <link idref="usagepatterns" anchor="icu">Using the ICU</link> and <link idref="commandline" anchor="icu">Enabling ICU support for the Xalan and/or TestXSLT executable</link>.</p>
<p>For information about using the command-line utility, see <link idref="commandline">Command-Line Utility</link>.</p>
</s3>
<s3 title="What you need to build and run applications">
<p>To build your own applications with Xalan and Xerces, you also need need the
Xalan-C++ and Xerces-C++ header (.hpp) files and (for Windows) the &xslt4c; and &xml4c; libraries (.lib files). To run your applications, you need the &xslt4c; and &xml4c; library files (.dll files for Windows, shared or load libraries for the UNIX platforms).</p>
<p>The Xalan-C++ and Xerces-C++ header files are in the src directory trees in both distributions.</p> 
<p>In the Windows32 distribution (built with Microsoft&reg; Visual C++&reg; 6.0), the .dlls and libraries are in the Build\Win32\V6 Debug and Release subdirectories.</p> 
<p>In the Linux distribution (built with a make file and the GNU C++ compiler on Red Hat Linux 6.1), the shared object libraries are in the lib subdirectories.</p>
<p>In the AIX distribution (built with the make file and xlC), the load libraries are in the lib subdirectories.</p>
<p>In the HP-UX 11 distribution (built with the make file and aCC), the shared libraries are in the lib subdirectories.</p>
<p>In the Solaris distribution (built with the make file and CC), the shared libraries are in the lib subdirectories.</p>
<note>For your convenience, both the Xalan and Xerces libraries are placed together in the pertinent xml-xalan directory, whereas the corresponding xml-xerces directory only contains Xerces libraries.</note>
<p>If you want to enable ICU support in your applications, you must rebuild the Xalan-C++ shared/load library (Linux/AIX) and include the ICUBridge headers (all platforms).</p>
<p>For the requirements for rebuilding &xslt4c;, see the <link idref="readme" anchor="build">Build notes</link>.</p>
</s3>
</s2><anchor name="path"/>
<s2 title="Setting up the path/library path">
<p>For the Xalan-C++ Windows32 distribution, place xml-xalan\c\Build\Win32\VC6\Release on the path.</p>
<p>For the Xalan-C++ Linux distribution, place xml-xalan/c/bin on the path (PATH) and xml-xalan/c/lib on the shared library path (LD_LIBRARY_PATH for Red Hat Linux 6.1), or copy &xslt4c-linuxlib; to /usr/lib.</p>
<p>For the Xalan-C++ AIX distribution, place xml-xalan/c/bin on the path (PATH) and xml-xalan/c/lib on the load library path (LIBPATH), or copy &xslt4c-aixlib; to /usr/lib.</p>
<p>For the Xalan-C++ HP-UX 11 distribution, place xml-xalan/c/bin on the path (PATH) and xml-xalan/c/lib on the shared library path (SHLIB_PATH), or copy &xslt4c-aixlib; to /usr/lib.</p>
<p>For the Xalan-C++ Solaris distribution, place xml-xalan/c/bin on the path (PATH) and xml-xalan/c/lib on the shared library path (LD_LIBRARY_PATH), or copy &xslt4c-solarislib; to /usr/lib.</p>
<p>If you do your own Xalan, ICU, and Xerces builds, be sure to include the directories that contain the libraries and the TextXSLT executable on your path.</p>
</s2><anchor name="samples"/>
<s2 title="Trying out the samples">
<p>The &xslt4c; distribution includes a number of basic sample applications. We have precompiled these samples for you so they are ready to run, and you can review the source files to see just how they work. </p>
<p>To run the samples, do the following:</p>
<ol>
<li>Set up your path (see above). In the Windows32 distribution, the sample executables are in
xml-xalan\c\Build\Win32\VC6\Release. In the UNIX distributions, the executables are in xml-xalan/c/bin.</li>
<li>Go to the samples subdirectory containing the sample.</li>
<li>Run the sample from the command line (in Windows, use the DOS shell).</li>
<li>Examine the application source files.</li>
</ol>
<p>For example, go to the SimpleTransform subdirectory and issue the following command:</p>
<p><code>SimpleTransform</code></p>
<p>SimpleTransform uses the foo.xsl stylesheet to transform foo.xml, and writes the transformation result to foo.out. To see how the example works, examine the source files: foo.xml, foo.xsl, foo.out, and SimpleTransform.cpp.</p>
<p>For more information about the samples, see <link idref="samples">&xslt4c; Samples</link>.</p>
</s2><anchor name="commandline"/>
<s2 title="Performing your own transformations from the command line">
<p>The Xalan executable lets you perform transformations from the command line. The command line for 
most standard transformations is as follows:</p>
<p><code>Xalan -o <ref>outputfile</ref> <ref>xmlSource</ref> <ref>stylesheet</ref></code></p>
<p>where <ref>xmlSource</ref> is the XML source file name, <ref>stylesheet</ref> is the XSL stylesheet file name, and <ref>outputfile</ref> is the output file name.</p>
<p>If you want the output to be displayed on the screen, simply omit the -o flag and <ref>outputfile</ref>.</p>
<p>You can use this utility to try out XSL stylesheets you have written, to make sure they do what you expect with the XML source files they are designed to transform. The utility provides useful messages if the source file or stylesheet is not well formed. If you include a DOCTYPE statement in your XML source files and include the -v flag on the command line, the utility will also let you know whether the XML document is valid (conforms to that DOCTYPE). For more information, see <link idref="commandline">Command-Line Utility</link>.</p>
</s2><anchor name="apps"/>
<s2 title="Setting up your own XSLT applications">
<p>You can start by using your own XML source files and XSL stylesheets with the sample applications, which illustrate a number of usage patterns. For more information on setting up applications, see <link idref="usagepatterns">Basic Usage Patterns</link>.</p>
</s2>
</s1>