doc/faq-build.xml - xerces-c - Git at Google

 <?xml version="1.0" encoding = "iso-8859-1" standalone="no"?>
 <!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">

 <faqs title="Building / Running FAQs">

   <faq title="Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?">
     <q>Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?</q>
     <a>
       <p>This is a compiler problem.  Try turning off optimization to bypass the problem.</p>
     </a>
   </faq>


   <faq title="Why do I get compilation error when compiling &XercesCName; on FreeBSD with native transcoder?">

     <q>Why do I get compilation error when compiling &XercesCName; on FreeBSD with native transcoder?</q>

     <a>
        <p>Please make sure you configure with "-t IconvFBSD" to use FreeBSD specific native transcoder.
        </p>

        <p>Or you can use ICU transcoder (configure with -t icu) instead of the native transcoder.
        </p>

     </a>
   </faq>

   <faq title="Building &XercesCName; with compiler GCC 2.7.x or 2.8.x gives problem, what's wrong?">

     <q>Building &XercesCName; with compiler GCC 2.7.x or 2.8.x gives problem, what's wrong?</q>

     <a>
        <p>Users using GCC 2.7.x or 2.8.x may have unsuccessful compile/link/run experience with
           &XercesCName;.  There were issues related to templates and multi threaded exception
           handling with this old version GCC compiler.
        </p>

        <p>Please upgrade to at least GCC 2.95.2.
        </p>

     </a>
   </faq>

   <faq title="Why does my application gives unresolved linking errors on Solaris?">

     <q>Why does my application gives unresolved linking errors on Solaris?</q>

     <a>

       <p>On Solaris there are a few things that need to be done before you
         execute your application using &XercesCName;. In case you're using the
         binary build of &XercesCName; make sure that the OS and compiler are
         the same version as the ones used to build the binary (please refer to
         <jump href="faq-distrib.html#faq-1">FAQ: What compilers are being used
         on the supported platforms?</jump>).  Different OS and
         compiler versions might cause unresolved linking problems or compilation
         errors. If the versions are different, rebuild the &XercesCName; library on
         your system before building your application. If you're using ICU (which is
         packaged with XML4C) you need to rebuild the compatible version of ICU
         first.</p>

       <p>Also check that the library path is set properly and that the correct
         versions of <code>gmake</code> and <code>autoconf</code> are on your system.</p>

     </a>
   </faq>

   <faq title="Why does my application gives unresolved linking errors on AIX?">

     <q>Why does my application gives unresolved linking errors on AIX?</q>

     <a>

       <p>In case you're using the binary build of &XercesCName; make sure that the
         OS and compiler are the same version as the ones used to build the binary
         (please refer to <jump href="faq-distrib.html#faq-1">FAQ: What compilers are
         being used on the supported platforms?</jump>).  Different OS and
         compiler versions might cause unresolved linking problems or compilation
         errors. If the versions are different, rebuild the &XercesCName; library on
         your system before building your application. If you're using ICU (which is
         packaged with XML4C) you need to rebuild the compatible version of ICU
         first.</p>

       <p>Also check that the library path is set properly and that the correct
         versions of <code>gmake</code> and <code>autoconf</code> are on your system.</p>

     </a>
   </faq>

   <faq title="Why do I get link error saying icudata library not found when building with ICU?">

     <q>Why do I get link error saying icudata library not found when building with ICU?</q>

     <a>
        <p>There is a bug in the Makefile of ICU 1.7, 1.8 and 1.8.1.  The link created during
           ICU installation in $ICUROOT is, for example,
        </p>

        <p>icudata.so@ -> icudt17l.so
        </p>

        <p>instead of
        </p>

        <p>libicudata.so@ -> libicudt17l.so <br/>
        </p>

        <p>Therefore the -licudata doesn't work.  To bypass the problem, please manually create the
           following link:
        </p>

        <p>libicudata.so@ -> libicudt17l.so
        </p>

        <p>This problem has been fixed in ICU 2.0.
        </p>


     </a>
   </faq>

   <faq title="I cannot run the sample applications. What is wrong?">

     <q>I cannot run the sample applications. What is wrong?</q>

     <a>

       <p>In order to run an application built using &XercesCProjectName; you must
         set up your path and library search path properly. In the stand-alone version
         from Apache, you must have the &XercesCName; runtime library available from
         your path settings. On Windows this library is called <code>&XercesCWindowsDLL;.dll</code> which must be available from your <code>PATH</code> settings. (Note that now there are separate debug and release dlls for
         Windows. If the release dll is named <code>&XercesCWindowsDLL;.dll</code> then the debug dll is named <code>&XercesCWindowsDLL;d.dll)</code>. On UNIX platforms the library is called <code>&XercesCUnixLib;.so</code> (or <code>.a</code> or <code>.sl</code>) which must be available from your <code>LD_LIBRARY_PATH</code> (or <code>LIBPATH</code> or <code>SHLIB_PATH</code>) environment variable.</p>

       <p>Thus, if you installed your binaries under <code>$HOME/fastxmlparser</code>, you need to point your library path to that directory.</p>

 <source>export LIBPATH=$LIBPATH:$HOME/fastxmlparser/lib # (AIX)
 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/fastxmlparser/lib # (Solaris, Linux)
 export SHLIB_PATH=$SHLIB_PATH:$HOME/fastxmlparser/lib # (HP-UX)</source>

       <p>If you are using the enhanced version of this parser from IBM, you will
         need to put in two additional DLLs. In the Windows build these are <code>icuuc.dll</code> and <code>icudata.dll</code> which must be available from your PATH settings. On UNIX, these
         libraries are called <code>libicuuc.so</code> and <code>libicudata.so</code> (or <code>.sl</code> for HP-UX or <code>.a</code> for AIX) which must be available from your library search path.</p>

     </a>
   </faq>

   <faq title="Why does my application crash on AIX when I run it under a
          multi-threaded environment?">

     <q>Why does my application crash on AIX when I run it under a
       multi-threaded environment?</q>

     <a>

       <p>AIX maintains two kinds of libraries on the system, thread-safe and
         non-thread safe. Multi-threaded libraries on AIX follow a different naming
         convention, Usually the multi-threaded library names are followed with "_r".
         For example, libc.a is single threaded whereas libc_r.a is multi-threaded.</p>

       <p>To make your multi-threaded application run on AIX, you <em>must</em>
         ensure that you do not have a "system library path" in your <code>LIBPATH</code>
         environment variable when you run the application. The appropriate
         libraries (threaded or non-threaded) are automatically picked up at runtime. An
         application usually crashes when you build your application for multi-threaded
         operation but don't point to the thread-safe version of the system libraries.
         For example, LIBPATH can be simply set as:</p>

 <source>LIBPATH=$HOME/&lt;&XercesCProjectName;&gt;/lib</source>

       <p>Where &lt;&XercesCProjectName;&gt; points to the directory where the
         &XercesCProjectName; application resides.</p>

       <p>If, for any reason unrelated to &XercesCProjectName;, you need to keep a
         "system library path" in your LIBPATH environment variable, you must make sure
         that you have placed the thread-safe path before you specify the normal system
         path. For example, you must place <ref>/lib/threads</ref> before
         <ref>/lib</ref> in your LIBPATH variable. That is to say your LIBPATH may look
         like this:</p>

 <source>export LIBPATH=$HOME/&lt;&XercesCProjectName;&gt;/lib:/usr/lib/threads:/usr/lib</source>

       <p>Where /usr/lib is where your system libraries are.</p>

     </a>
   </faq>

   <faq title="Why does my multi-threaded application crash on Solaris?">

     <q>Why does my multi-threaded application crash on Solaris?</q>

     <a>

       <p>The problem appears because the throw call on Solaris 2.6 is not
         multi-thread safe. Sun Microsystems provides a patch to solve this problem. To
         get the latest patch for solving this problem, go to
         <jump href="http://sunsolve.sun.com">SunSolve.sun.com</jump> and get the
         appropriate patch for your operating system. For Intel machines running
         Solaris, you need to get Patch ID 104678. For SPARC machines you need to get
         Patch ID #105591.</p>

     </a>
   </faq>

   <faq title="I just built my own application using the &XercesCName; parser. Why does it crash?">

     <q>I just built my own application using the &XercesCName; parser. Why does
       it crash?</q>

     <a>

       <p>In order to work with the &XercesCName; parser, you have to first
         initialize the XML subsystem. The most common mistake is to forget this
         initialization. Before you make any calls to &XercesCName; APIs, you must
         call XMLPlatformUtils::Initialize(): </p>

 <source>
 try {
    XMLPlatformUtils::Initialize();
 }
 catch (const XMLException&amp; toCatch) {
    // Do your failure processing here
 }</source>

       <p>This initializes the &XercesCProjectName; system and sets its internal
         variables. Note that you must the include <code>xercesc/util/PlatformUtils.hpp</code> file for this to work.</p>

     </a>
   </faq>

   <faq title="Why does deleting a transcoded string result in assertion on windows?">
     <q>Why does deleting a transcoded string result in assertion on windows?</q>
     <a>
       <p>Both your application program and the Xerces DLL must use the same *DLL* version of the
          runtime library.  If either statically links to the runtime library, the
 		 problem will still occur.

          For example, for a Win32/VC6 build, the runtime library build setting MUST
 		 be "Multithreaded DLL" for release builds and "Debug Multithreaded DLL" for
 		 debug builds.</p>
     </a>
   </faq>

   <faq title="Can't debug into the &XercesCName; DLL with the MSVC debugger">

     <q> The libs/dll's I downloaded keep me from using the debugger in VC6.0. I
       am using the 'D', debug versions of them. "no symbolic information found" is
       what it says. Do I have to compile everything from source to make it work?</q>

     <a>

       <p>Unless you have the .pdb files, all you are getting with the debug
         library is that it uses the debug heap manager, so that you can compile your
         stuff in debug mode and not be dangerous. If you want full symbolic info for
         the &XercesCName; library, you'll need the .pdb files, and to get those, you'll
         need to rebuild the &XercesCName; library.</p>

     </a>
   </faq>

   <faq title="First-chance exception in Microsoft debugger">

     <q>"First-chance exception in DOMPrint.exe (KERNEL32.DLL): 0xE06D7363:
       Microsoft C++ Exception." I am always getting this message when I am using the
       parser. My programs are terminating abnormally. Even the samples are giving
       this exception. I am using Visual C++ 6.0 with latest service pack
       installed.</q>

     <a>

       <p>&XercesCName; uses C++ exceptions internally, as part of its normal
         operation. By default, the MSVC debugger will stop on each of these with the
         "First-chance exception ..." message.</p>

       <p>To stop this from happening do this:</p>

       <ul>
         <li>start debugging (so the debug menu appears)</li>
         <li>from the debug menu select "Exceptions"</li>
         <li>from the box that opens select "Microsoft C++ Exception" and set it
           to "Stop if not handled" instead of "stop always".</li>
       </ul>

       <p>You'll still land in the debugger if your program is terminating
         abnormally, but it will be at your problem, not from the internal &XercesCName;
         exceptions.</p>

     </a>
   </faq>

   <faq title="Fatal Error: Cannot open include file: XXX: No such file or directory">
     <q>"Fatal Error: Cannot open include file: XXX: No such file or directory"?</q>
     <a>
       <p>
 	      Due to the recent directory change, you may need to either update your
 		  project file, makefile, or your source/header file, for details,
           please refer to <jump href="migrate.html#DirChange">Directory Change. </jump></p>
     </a>
   </faq>

 </faqs>
	<?xml version="1.0" encoding = "iso-8859-1" standalone="no"?>
	<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">

	<faqs title="Building / Running FAQs">

	<faq title="Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?">
	<q>Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?</q>
	<a>
	<p>This is a compiler problem. Try turning off optimization to bypass the problem.</p>
	</a>
	</faq>


	<faq title="Why do I get compilation error when compiling &XercesCName; on FreeBSD with native transcoder?">

	<q>Why do I get compilation error when compiling &XercesCName; on FreeBSD with native transcoder?</q>

	<a>
	<p>Please make sure you configure with "-t IconvFBSD" to use FreeBSD specific native transcoder.
	</p>

	<p>Or you can use ICU transcoder (configure with -t icu) instead of the native transcoder.
	</p>

	</a>
	</faq>

	<faq title="Building &XercesCName; with compiler GCC 2.7.x or 2.8.x gives problem, what's wrong?">

	<q>Building &XercesCName; with compiler GCC 2.7.x or 2.8.x gives problem, what's wrong?</q>

	<a>
	<p>Users using GCC 2.7.x or 2.8.x may have unsuccessful compile/link/run experience with
	&XercesCName;. There were issues related to templates and multi threaded exception
	handling with this old version GCC compiler.
	</p>

	<p>Please upgrade to at least GCC 2.95.2.
	</p>

	</a>
	</faq>

	<faq title="Why does my application gives unresolved linking errors on Solaris?">

	<q>Why does my application gives unresolved linking errors on Solaris?</q>

	<a>

	<p>On Solaris there are a few things that need to be done before you
	execute your application using &XercesCName;. In case you're using the
	binary build of &XercesCName; make sure that the OS and compiler are
	the same version as the ones used to build the binary (please refer to
	<jump href="faq-distrib.html#faq-1">FAQ: What compilers are being used
	on the supported platforms?</jump>). Different OS and
	compiler versions might cause unresolved linking problems or compilation
	errors. If the versions are different, rebuild the &XercesCName; library on
	your system before building your application. If you're using ICU (which is
	packaged with XML4C) you need to rebuild the compatible version of ICU
	first.</p>

	<p>Also check that the library path is set properly and that the correct
	versions of <code>gmake</code> and <code>autoconf</code> are on your system.</p>

	</a>
	</faq>

	<faq title="Why does my application gives unresolved linking errors on AIX?">

	<q>Why does my application gives unresolved linking errors on AIX?</q>

	<a>

	<p>In case you're using the binary build of &XercesCName; make sure that the
	OS and compiler are the same version as the ones used to build the binary
	(please refer to <jump href="faq-distrib.html#faq-1">FAQ: What compilers are
	being used on the supported platforms?</jump>). Different OS and
	compiler versions might cause unresolved linking problems or compilation
	errors. If the versions are different, rebuild the &XercesCName; library on
	your system before building your application. If you're using ICU (which is
	packaged with XML4C) you need to rebuild the compatible version of ICU
	first.</p>

	<p>Also check that the library path is set properly and that the correct
	versions of <code>gmake</code> and <code>autoconf</code> are on your system.</p>

	</a>
	</faq>

	<faq title="Why do I get link error saying icudata library not found when building with ICU?">

	<q>Why do I get link error saying icudata library not found when building with ICU?</q>

	<a>
	<p>There is a bug in the Makefile of ICU 1.7, 1.8 and 1.8.1. The link created during
	ICU installation in $ICUROOT is, for example,
	</p>

	<p>icudata.so@ -> icudt17l.so
	</p>

	<p>instead of
	</p>

	<p>libicudata.so@ -> libicudt17l.so <br/>
	</p>

	<p>Therefore the -licudata doesn't work. To bypass the problem, please manually create the
	following link:
	</p>

	<p>libicudata.so@ -> libicudt17l.so
	</p>

	<p>This problem has been fixed in ICU 2.0.
	</p>


	</a>
	</faq>

	<faq title="I cannot run the sample applications. What is wrong?">

	<q>I cannot run the sample applications. What is wrong?</q>

	<a>

	<p>In order to run an application built using &XercesCProjectName; you must
	set up your path and library search path properly. In the stand-alone version
	from Apache, you must have the &XercesCName; runtime library available from
	your path settings. On Windows this library is called <code>&XercesCWindowsDLL;.dll</code> which must be available from your <code>PATH</code> settings. (Note that now there are separate debug and release dlls for
	Windows. If the release dll is named <code>&XercesCWindowsDLL;.dll</code> then the debug dll is named <code>&XercesCWindowsDLL;d.dll)</code>. On UNIX platforms the library is called <code>&XercesCUnixLib;.so</code> (or <code>.a</code> or <code>.sl</code>) which must be available from your <code>LD_LIBRARY_PATH</code> (or <code>LIBPATH</code> or <code>SHLIB_PATH</code>) environment variable.</p>

	<p>Thus, if you installed your binaries under <code>$HOME/fastxmlparser</code>, you need to point your library path to that directory.</p>

	<source>export LIBPATH=$LIBPATH:$HOME/fastxmlparser/lib # (AIX)
	export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/fastxmlparser/lib # (Solaris, Linux)
	export SHLIB_PATH=$SHLIB_PATH:$HOME/fastxmlparser/lib # (HP-UX)</source>

	<p>If you are using the enhanced version of this parser from IBM, you will
	need to put in two additional DLLs. In the Windows build these are <code>icuuc.dll</code> and <code>icudata.dll</code> which must be available from your PATH settings. On UNIX, these
	libraries are called <code>libicuuc.so</code> and <code>libicudata.so</code> (or <code>.sl</code> for HP-UX or <code>.a</code> for AIX) which must be available from your library search path.</p>

	</a>
	</faq>

	<faq title="Why does my application crash on AIX when I run it under a
	multi-threaded environment?">

	<q>Why does my application crash on AIX when I run it under a
	multi-threaded environment?</q>

	<a>

	<p>AIX maintains two kinds of libraries on the system, thread-safe and
	non-thread safe. Multi-threaded libraries on AIX follow a different naming
	convention, Usually the multi-threaded library names are followed with "_r".
	For example, libc.a is single threaded whereas libc_r.a is multi-threaded.</p>

	<p>To make your multi-threaded application run on AIX, you <em>must</em>
	ensure that you do not have a "system library path" in your <code>LIBPATH</code>
	environment variable when you run the application. The appropriate
	libraries (threaded or non-threaded) are automatically picked up at runtime. An
	application usually crashes when you build your application for multi-threaded
	operation but don't point to the thread-safe version of the system libraries.
	For example, LIBPATH can be simply set as:</p>

	<source>LIBPATH=$HOME/<&XercesCProjectName;>/lib</source>

	<p>Where <&XercesCProjectName;> points to the directory where the
	&XercesCProjectName; application resides.</p>

	<p>If, for any reason unrelated to &XercesCProjectName;, you need to keep a
	"system library path" in your LIBPATH environment variable, you must make sure
	that you have placed the thread-safe path before you specify the normal system
	path. For example, you must place <ref>/lib/threads</ref> before
	<ref>/lib</ref> in your LIBPATH variable. That is to say your LIBPATH may look
	like this:</p>

	<source>export LIBPATH=$HOME/<&XercesCProjectName;>/lib:/usr/lib/threads:/usr/lib</source>

	<p>Where /usr/lib is where your system libraries are.</p>

	</a>
	</faq>

	<faq title="Why does my multi-threaded application crash on Solaris?">

	<q>Why does my multi-threaded application crash on Solaris?</q>

	<a>

	<p>The problem appears because the throw call on Solaris 2.6 is not
	multi-thread safe. Sun Microsystems provides a patch to solve this problem. To
	get the latest patch for solving this problem, go to
	<jump href="http://sunsolve.sun.com">SunSolve.sun.com</jump> and get the
	appropriate patch for your operating system. For Intel machines running
	Solaris, you need to get Patch ID 104678. For SPARC machines you need to get
	Patch ID #105591.</p>

	</a>
	</faq>

	<faq title="I just built my own application using the &XercesCName; parser. Why does it crash?">

	<q>I just built my own application using the &XercesCName; parser. Why does
	it crash?</q>

	<a>

	<p>In order to work with the &XercesCName; parser, you have to first
	initialize the XML subsystem. The most common mistake is to forget this
	initialization. Before you make any calls to &XercesCName; APIs, you must
	call XMLPlatformUtils::Initialize(): </p>

	<source>
	try {
	XMLPlatformUtils::Initialize();
	}
	catch (const XMLException& toCatch) {
	// Do your failure processing here
	}</source>

	<p>This initializes the &XercesCProjectName; system and sets its internal
	variables. Note that you must the include <code>xercesc/util/PlatformUtils.hpp</code> file for this to work.</p>

	</a>
	</faq>

	<faq title="Why does deleting a transcoded string result in assertion on windows?">
	<q>Why does deleting a transcoded string result in assertion on windows?</q>
	<a>
	<p>Both your application program and the Xerces DLL must use the same DLL version of the
	runtime library. If either statically links to the runtime library, the
	problem will still occur.

	For example, for a Win32/VC6 build, the runtime library build setting MUST
	be "Multithreaded DLL" for release builds and "Debug Multithreaded DLL" for
	debug builds.</p>
	</a>
	</faq>

	<faq title="Can't debug into the &XercesCName; DLL with the MSVC debugger">

	<q> The libs/dll's I downloaded keep me from using the debugger in VC6.0. I
	am using the 'D', debug versions of them. "no symbolic information found" is
	what it says. Do I have to compile everything from source to make it work?</q>

	<a>

	<p>Unless you have the .pdb files, all you are getting with the debug
	library is that it uses the debug heap manager, so that you can compile your
	stuff in debug mode and not be dangerous. If you want full symbolic info for
	the &XercesCName; library, you'll need the .pdb files, and to get those, you'll
	need to rebuild the &XercesCName; library.</p>

	</a>
	</faq>

	<faq title="First-chance exception in Microsoft debugger">

	<q>"First-chance exception in DOMPrint.exe (KERNEL32.DLL): 0xE06D7363:
	Microsoft C++ Exception." I am always getting this message when I am using the
	parser. My programs are terminating abnormally. Even the samples are giving
	this exception. I am using Visual C++ 6.0 with latest service pack
	installed.</q>

	<a>

	<p>&XercesCName; uses C++ exceptions internally, as part of its normal
	operation. By default, the MSVC debugger will stop on each of these with the
	"First-chance exception ..." message.</p>

	<p>To stop this from happening do this:</p>

	<ul>
	<li>start debugging (so the debug menu appears)</li>
	<li>from the debug menu select "Exceptions"</li>
	<li>from the box that opens select "Microsoft C++ Exception" and set it
	to "Stop if not handled" instead of "stop always".</li>
	</ul>

	<p>You'll still land in the debugger if your program is terminating
	abnormally, but it will be at your problem, not from the internal &XercesCName;
	exceptions.</p>

	</a>
	</faq>

	<faq title="Fatal Error: Cannot open include file: XXX: No such file or directory">
	<q>"Fatal Error: Cannot open include file: XXX: No such file or directory"?</q>
	<a>
	<p>
	Due to the recent directory change, you may need to either update your
	project file, makefile, or your source/header file, for details,
	please refer to <jump href="migrate.html#DirChange">Directory Change. </jump></p>
	</a>
	</faq>

	</faqs>