build-winunix.xml

<?xml version="1.0" standalone="no"?>
<!--
 * 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.
-->

<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">

<s1 title="Building on Windows and UNIX">
    <anchor name="WinNT"/>
    <s2 title="Building &XercesCName; on Windows using Microsoft Visual C++">
        <p>&XercesCName; source distribution comes with Microsoft Visual C++ projects and workspaces to
        help you build &XercesCName;. The following describes the steps you need
        to build &XercesCName;.</p>

        <s3 title="Building &XercesCName; library">
            <p>To build &XercesCName; from the source distribution (using MSVC), you will
            need to open the workspace containing the project. If you are
            building your application, you may want to add the &XercesCName;
            project inside your application's workspace.</p>
            <p>The workspace containing the &XercesCName; project file and
            all other samples is in:</p>
            <p>For MSVC Version 6:</p>
<source>&XercesCSrcInstallDir;\Projects\Win32\VC6\xerces-all\xerces-all.dsw</source>
            <p>For MSVC Version 7.1 (Visual C++ .NET 2003):</p>
<source>&XercesCSrcInstallDir;\Projects\Win32\VC7.1\xerces-all\xerces-all.sln</source>
            <p>For MSVC Version 8.0 (Visual C++ .NET 2005):</p>
<source>&XercesCSrcInstallDir;\Projects\Win32\VC8\xerces-all\xerces-all.sln</source>

            <p>Once you are inside MSVC, you need to build the project marked
            <em>XercesLib</em>.</p>
            <p>If you want to include the &XercesCName; project separately,
            you need to pick up:</p>
<source>(For MSVC V6) &XercesCSrcInstallDir;\Projects\Win32\VC6\xerces-all\XercesLib\XercesLib.dsp
(For MSVC V7.1) &XercesCSrcInstallDir;\Projects\Win32\VC7.1\xerces-all\XercesLib\XercesLib.vcproj
(For MSVC V8) &XercesCSrcInstallDir;\Projects\Win32\VC8\xerces-all\XercesLib\XercesLib.vcproj</source>
            <p>You must make sure that you are linking your application with
            the &XercesCWindowsLib;.lib library and also make sure that
            the associated DLL is somewhere in your path.</p>
            <note>If you are working on the AlphaWorks version which uses ICU,
            you must have the ICU data DLL named <code>icudata.dll</code> available from your path
            setting. For finding out where you can
            get ICU from and build it, look at the <jump href="build-misc.html#faq-1">How to Build ICU</jump>.</note>

        </s3>
        <s3 title="Building samples">
            <p>If you are using the source package, inside the same workspace (xerces-all.dsw), you'll find several other
            projects. These are for the samples. Select all the samples and right click
            on the selection. Then choose "Build (selection only)" to build all the
            samples in one shot.</p>

            <p>If you are using the binary package, load the &XercesCInstallDir;-win32\samples\Projects\Win32\VC6\samples.dsw
              Microsoft Visual C++ workspace inside your MSVC IDE. Then select all the samples and right click
              on the selection. Then choose "Build (selection only)" to build all the
              samples in one shot.</p>
        </s3>
    </s2>

    <anchor name="WinIntel"/>
    <s2 title="Building &XercesCName; 64 bit binary on Windows XP using Intel C++ Compiler">
        <p>&XercesCName; source distribution comes with Microsoft Visual C++ NMake Files which
        work with Intel C++ Compiler. The following describes the steps you need
        to build &XercesCName; 64 bit binary using Intel C++ Compiler.</p>

        <s3 title="Building &XercesCName; library">
            <p>&XercesCName; source distribution provides a makefile <code>all.mak</code>
            which will build everything including samples, tests and the parser library.</p>
<source>
cd &XercesCSrcInstallDir;\Projects\Win32\VC6\xerces-all\all
nmake -f all.mak "CFG=all - Win64 Release" CPP=ecl.exe
</source>

            <p>If you want to just build the &XercesCName; parser library alone, then</p>
<source>
cd &XercesCSrcInstallDir;\Projects\Win32\VC6\xerces-all\XercesLib
nmake -f XercesLib.mak "CFG=XercesLib - Win64 Release" CPP=ecl.exe
</source>

            <p>You must make sure that you are linking your application with
            the &XercesCWindowsLib;.lib library and also make sure that
            the associated DLL is somewhere in your path.</p>
        </s3>
    </s2>

    <anchor name="WinBorlandBuilder"/>
    <s2 title="Building &XercesCName; on Windows using Borland C++Builder">
        <p>&XercesCName; source distribution comes with Borland C++Builder6 projects to help you
		build &XercesCName;. The following describes the steps you need to build
		&XercesCName;.</p>

        <s3 title="Building &XercesCName; library">
		   <p> The library and demo projects are all contained in the Xerces-all project group:
		   </p>

           <ul>
		       <li> &XercesCSrcInstallDir;\Projects\Win32\BCB6\Xerces-all\Xerces-all.bpg </li>
    	   </ul>

		   <p> Each project in the group refers a directory below \Xerces-all.
		       For example, the XercesLib project files are contained in the directory
           </p>

           <ul>
    	       <li> &XercesCSrcInstallDir;\Projects\Win32\BCB6\Xerces-all\XercesLib </li>
		   </ul>

           <p> To build any project, open the project manager.  Double click on the project
            name.  Then select "Project|Build" from the menu.  For example, double click
            on XercesLib.dll in the manager.  Then select "Project|Build XercesLib" from
            the menu.

            Once the library has been built, include XercesLib.lib with in application's
            project and place XercesLib.dll somewhere in your path.
           </p>

        </s3>
    </s2>
    
    <anchor name="WinBorlandCC"/>
    <s2 title="Building &XercesCName; on Windows using Borland C++ Compiler">
        <p>&XercesCName; source distribution comes with Borland C++ Compiler make files to help you
		build &XercesCName;. The following describes the steps you need to build
		&XercesCName;.</p>

        <ol>
		   <li>Change directory to <code> &XercesCSrcInstallDir;\Projects\Win32\BCC.551\Xerces-all</code></li>
           <li>Run <code>MakeBuildDirs.bat</code>.</li>
		   <li>Then issue</li>
	       <li><code>make -f Xerces-all.mak</code>
               <br/>to build the dll and tests</li>
	    </ol>           
    </s2>
        
    <anchor name="CygWin"/>
    <s2 title="Building &XercesCName; on Windows using Cygwin">
        <p><em>Do not jump into the build directly before reading this.</em></p>

		<p>&XercesCName; may be built in the
		<jump href="http://www.cygwin.com">Cygwin</jump> environment for use
		by Cygwin applications.  As with the <jump href="#UNIX">UNIX</jump>
		platforms, &XercesCName; on Cygwin uses
		<jump href="http://www.gnu.org">GNU</jump> tools.  Therefore, with a
		couple of notable exceptions, &XercesCName; on Cygwin is built using
		the same instructions as the UNIX platforms.</p>
	
		<p>Note that Cygwin is different from the UNIX platforms in the way
		that it finds libraries at run time.  While UNIX platforms may use the
		environment variable LD_LIBRARY_PATH, Cygwin uses the PATH environment
		variable.</p>

		<p>There is an issue with the
		<jump href="http://www.gnu.org/software/gcc/gcc.html">gcc/g++</jump>
		compiler version 2.95, where C++ exceptions thrown from a dll will
		cause the application to crash, regardless of whether there is a "catch"
		statement.  This bug doesn't occur in tests using gcc 3.1 or 3.2, so it
		is recommended that you use gcc 3.1 or higher.</p>
    </s2>

    <anchor name="UNIX"/>
    <s2 title="Building &XercesCName; on UNIX platforms">
        <p>&XercesCName; uses
        <jump href="http://www.gnu.org">GNU</jump> tools like
        <jump href="http://www.gnu.org/software/autoconf/autoconf.html">Autoconf</jump> and
        <jump href="http://www.gnu.org/software/make/make.html">GNU Make</jump>
        to build the system. You must first make sure you
        have these tools installed on your system before proceeding.
        If you do not have required tools, ask your system administrator
        to get them for you. These tools are free under the GNU Public License
        and may be obtained from the
        <jump href="http://www.gnu.org">Free Software Foundation</jump>.</p>

        <p><em>Do not jump into the build directly before reading this.</em></p>

        <p>Spending some time reading the following instructions will save you a
        lot of wasted time and support-related e-mail communication.</p>

        <p>Besides having all necessary build tools, you also need to know what
        compilers we have tested &XercesCName; on. The following table lists the
        relevant platforms and compilers.</p>

     	&build-winunix-supported-platforms;

        <!-- note about building on untested platforms - see entities.ent -->
        &build-winunix-note;

        <p><em>Differences between the UNIX platforms:</em> The description below is
        generic, but as every programmer is aware, there are minor differences
        within the various UNIX flavors the world has been bestowed with.
        The one difference that you need to watch out in the discussion below,
        pertains to the system environment variable for finding libraries.
        On <em>Linux</em> and <em>Solaris</em>, the environment variable name is called
        <code>LD_LIBRARY_PATH</code>, on <em>AIX</em> it is <code>LIBPATH</code>,
        on <em>Mac OS X</em> it is <code>DYLD_LIBRARY_PATH</code>,
        while on <em>HP-UX</em> it is <code>SHLIB_PATH</code>. The following
        discussion assumes you are working on Linux, but it is with subtle
        understanding that you know how to interpret it for the other UNIX flavors.</p>

        <note>If you wish to build &XercesCName; with ICU,
        look at the <jump href="build-misc.html#faq-1">Building &XercesCName; with ICU</jump>.
        It tells you where you can get ICU and how to build &XercesCName; with it.</note>

        <s3 title="Setting build environment variables">
            <p>Before doing the build, you must first set your environment variables
            to pick-up the compiler.
            While the first one is probably set for you by the system administrator, just
            make sure you can invoke the compiler. You may do so by typing the
            compiler invocation command without any parameters (e.g. xlc_r, or g++, or cc)
            and check if you get a proper response back.</p>
            </s3>

        <s3 title="Building &XercesCName; library">
            <p>As mentioned earlier, to build &XercesCName; from the source distribution,
            you must be ready with the GNU tools like
            <jump href="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</jump> and
            <jump href="http://www.gnu.org/software/make/make.html">gmake</jump>
            before you attempt the build.</p>

            <p>The autoconf tool is required on only one platform and produces
            a set of portable scripts (configure) that you can run on all
            other platforms without actually having the autoconf tool installed
            everywhere. In all probability the autoconf-generated script
            (called <code>configure</code>) is already in your <code>src/xercesc</code>
            directory. If not, type:</p>

<source>cd &lt;full path to &XercesCSrcInstallDir;&gt;
autoconf</source>

            <p>This generates a shell-script called <code>configure</code>. It is tempting to run
            this script directly as is normally the case, but wait a minute. 
			Even if you are using the default compilers like
            <jump href="http://www.gnu.org/software/gcc/gcc.html">gcc</jump> and
            <jump href="http://www.gnu.org/software/gcc/gcc.html">g++</jump> 
            you need to make some decisions about what components you want to 
            build into the library.</p>

            <p>You need to specify one options from each category; not specifying one
			will instruct <code>configure</code> to pick the best choice available:</p>


	<p>Net Accessor (used to read data from HTTP sources):</p>
		<ol>
			<li><code>--enable-netaccessor-curl</code> Uses curl</li>
			<li><code>--enable-netaccessor-libwww</code> Uses W3C's libWWW</li>
			<li><code>--enable-netaccessor-socket</code> Uses plain BSD sockets</li>
			<li><code>--enable-netaccessor-cfurl</code> Uses cfurl (Mac-only)</li>
			<li><code>--enable-netaccessor-winsock</code> Uses WinSock (Windows-only, either Cygwin or MinGW)</li>
		</ol>
	<p>Message Loader (used to store the strings of the error messages):</p>
		<ol>
			<li><code>--enable-msgloader-inmemory</code> Stores the messages in C++ arrays</li>
			<li><code>--enable-msgloader-icu</code> Stores the messages using ICU resource bundles</li>
			<li><code>--enable-msgloader-iconv</code> Stores the messages in a iconv message catalog</li>
		</ol>
	<p>Transcoder (used to convert strings between UTF-16 and any other supported encoding):</p>
		<ol>
			<li><code>--enable-transcoder-gnuiconv</code> Uses GNU iconv library</li>
			<li><code>--enable-transcoder-iconv</code> Uses iconv library</li>
			<li><code>--enable-transcoder-icu</code> Uses ICU library</li>
			<li><code>--enable-transcoder-macosunicodeconverter</code> Uses MacOS APIs (Mac-only)</li>
			<li><code>--enable-transcoder-windows</code> Uses Windows APIs (Windows-only, either Cygwin or MinGW)</li>
		</ol>

            <p>By default <code>configure</code> will build both shared and static libraries;
			you can use <code>--disable-shared</code> or <code>--disable-static</code> to
			suppress the version you don't need.</p>

            <p>Thread support is enabled by default too;
			you can use <code>--disable-threads</code> to remove it.</p>

            <p>If you need to specify a compiler (because more than one is found in the PATH,
			or because it has been renamed to a non-standard name), you should set the
			environment variables CXX and CC before invoking <code>configure</code>.<br/>
			If you need special compiler or linker options, define the environment variables
			CXXFLAGS and LDFLAGS.</p>

            <note>&XercesCName; can be built as either a standalone library or as a library
            dependent on International Components for Unicode (ICU). For simplicity,
            the following discussion only explains standalone builds.</note>

            <anchor name="configure-example"/>
            <p>The simplest way to build &XercesCName; is as follows:</p>

<source>./configure</source>

            <p>This will instruct <code>configure</code> to find out the platform, the compiler
			and the libraries installed on the system. If more than one library is available
			for a category, the most powerful will be chosen (e.g. if ICU is available, it will
			be chosen over iconv).<br/>
			So it's recommended to examine the log to check if its choices are the correct ones.</p>

<source>
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
[..snip..]
checking for g++... g++
[..snip..]
checking for gcc... gcc
[..snip..]
checking for libcurl... 
checking for libwww... 
checking whether we can support the libcurl-based NetAccessor... no
checking whether we can support the libwww-based NetAccessor... no
checking whether we can support the sockets-based NetAccessor... yes
checking for which NetAccessor to use (choices: -socket-)... socket
checking for icu... /usr/local
checking iconv.h usability... yes
checking iconv.h presence... yes
checking for iconv.h... yes
checking for wchar.h... (cached) yes
checking for string.h... (cached) yes
checking for stdlib.h... (cached) yes
checking stdio.h usability... yes
checking stdio.h presence... yes
checking for stdio.h... yes
checking ctype.h usability... yes
checking ctype.h presence... yes
checking for ctype.h... yes
checking for locale.h... (cached) yes
checking errno.h usability... yes
checking errno.h presence... yes
checking for errno.h... yes
checking endian.h usability... yes
checking endian.h presence... yes
checking for endian.h... yes
checking for iconv_open... yes
checking for iconv_close... yes
checking for iconv... yes
checking whether we can support the GNU iconv Transcoder... yes
checking for wchar.h... (cached) yes
checking for mblen... (cached) yes
checking for wcstombs... yes
checking for mbstowcs... yes
checking whether we can support the iconv Transcoder... yes
checking whether we can support the ICU Transcoder... yes
checking for which Transcoder to use (choices: -gnuiconv- -iconv- -icu-)... icu
checking whether we support the InMemory MsgLoader... yes
checking whether we support the ICU MsgLoader... yes
checking for nl_types.h... (cached) yes
checking for catopen... yes
checking for catclose... yes
checking for catgets... yes
checking whether we can support the iconv MsgLoader... yes
checking for which MsgLoader to use (choices: -inmemory- -icu- -iconv-)... icu
checking for which File Manager to use... POSIX
checking for which Mutex Manager to use... POSIX
checking for which AtomicOp Manager to use... POSIX
checking whether we are using SunPro 5.8 compiler... no
configure: creating ./config.status
config.status: creating Makefile
config.status: creating lib/Makefile
config.status: creating src/Makefile
config.status: creating src/xercesc/util/MsgLoaders/ICU/resources/Makefile
config.status: creating obj/Makefile
config.status: creating tests/Makefile
config.status: creating samples/Makefile
config.status: creating config.h
config.status: creating src/xercesc/util/Xerces_autoconf_config.hpp
config.status: executing depfiles commands
</source>

            <p>Now that the Makefiles are all created, you are ready to do the actual build.</p>

<source>gmake</source>

            <p>Is that it? Yes, that's all you need to build &XercesCName; and the associated samples.</p>

            <p>If you need to build the tests, type</p>

<source>gmake check</source>

	         <p>To delete all the generated object files and executables, type:</p>

<source>gmake clean</source>

        </s3>
    </s2>

<!--    <anchor name="UNIX_SingleThread"/>
    <s2 title="Building &XercesCName; as a single-threaded library on Unix platforms">
         <p>The following steps guide you to create a single-threaded library for each platform:</p>

         <p>For Aix - </p>
         <ul>
         <li>Replace <code>xlc_r</code> and <code>xlC_r</code> libraries with
            <code>xlc</code> and <code>xlC</code> respectively</li>
         <li>Replace <code>makeC++SharedLib_r</code> with <code>makeC++SharedLib</code></li>
         <li>Remove the flag <code>-D_THREAD_SAFE</code></li>
         <li>Remove inclusion of any threaded library directories from the <code>LIBPATH</code></li>
         <li>Remove inclusion of <code>-lpthreads</code> and <code>-lpthread_compat</code></li>
         <li>Add <code>-DAPP_NO_THREADS</code> to define the variable under AIX specific options
                  in <code>Makefile.incl</code></li>
         </ul>

        <p>For Solaris -</p>
         <ul>
          <li>Add <code>-DAPP_NO_THREADS</code> to define the variable under SOLARIS
            specific options in <code>Makefile.incl</code></li>
          <li>Remove compiler switch <code>-mt</code></li>
          <li>Remove <code>-D_REENTRANT</code> flag from the 'compile' options</li>
      <li>Remove inclusion of <code>-lpthread</code></li>
    </ul>

    <p>For Linux -</p>
        <ul>
         <li>Add <code>-DAPP_NO_THREADS</code> to define the variable under LINUX
            specific options in <code>Makefile.incl</code></li>
     <li>Remove <code>-D_REENTRANT</code> flag from the 'compile' options</li>
     <li>Remove inclusion of <code>-lpthread</code></li>
    </ul>


    <p>For HPUX -</p>
        <ul>
         <li>Add <code>-DAPP_NO_THREADS</code> to define the variable under HP
            specific options in <code>Makefile.incl</code></li>
     <li>Remove inclusion of <code>-lpthread</code> and <code>-lcma</code></li>
     <li>Remove threading defines like <code>-D_PTHREADS_DRAFT4 ,
        -DXML_USE_DCE</code></li>
    </ul>
   </s2>
-->
</s1>