Pathan 2 Build Documentation
Pathan 2 has been built on Windows, Solaris 7 and Linux. The code
has been written with portability in mind and uses the GNU autotools
and hence should be portable with minimal changes to most UNIX
systems.
Xerces-C is required to build Pathan 2.
Note that you
will require a full source distribution, from CVS at 17:00 GMT on 3 September
2003 (or later). There is a copy of the required Xerces source available for
download on the Pathan 2 download page. At the time of release the source and
binary Xerces distributions (version 2.3) were not sufficient - however more recent versions (such as the current version, 2.5) should be sufficient.
Quick build instructions
In depth build instructions
Quick build instructions
Windows
The project and workspace files for Pathan 2 are stored in
{pathan root}/Win32Projects/Pathan
By default Pathan 2 compiles to a dynamic library (.dll).
In order to build Pathan 2, you will require both the Xerces-C
source and optionally the binaries provided on the
download
page. You can also obtain the required source from the Xerces CVS repository. If you do not download the binaries you must build Xerces C before proceeding.
By default Pathan 2 looks for a Xerces-C
source
distribution location in Xerces/ based at the same
level as the Pathan/ distribution (ie. Xerces source
in Xerces/src etc.).
The Xerces-C source distribution does not include prebuilt Xerces
libraries. These should be copied into {Xerces
root}/lib. These may be copied from the Windows binary
distribution of Xerces-C or built and copied from the default output location
of Xerces/Build/Win32/VC6/[Debug/Release].
If the Xerces source is located elsewhere please add the include and library paths using MS VC++ using
Tools -> Options... -> Directories [tab]
Add
{Xerces root}/src
to the include path and
{Xerces root}/lib
to the library path.
UNIX
In order to build Pathan 2, you will require both the Xerces-C
source and optionally the binaries provided on the
download
page.
To obtain the Xerces-C source from 3 September, 2003, either download it from the Pathan 2 download pages or do the following:
First, you must set the CVSROOT environment variable. This looks like:
$ CVSROOT=:pserver:anoncvs@cvs.apache.org:/home/cvspublic
$ export CVSROOT
Then login to the server:
$ cvs login
The password is "anoncvs" (without the quotes).
Finally, you checkout the module
cvs checkout -d Xerces -D '2003-09-03 17:00' xml-xerces/c
If you do have not downloaded the binaries you must build Xerces C before proceeding.
Before building Pathan 2 the XERCESCROOT environment variable must be
set to the root of the Xerces source distribution (ie. the directory containing
the src/ and tools/
subdirectories etc.).
If you are building on Solaris please download and install GCC from
Freeware for Solaris
and set the CC enviroment variable accordingly. Pathan will not compile with Sun's CC compiler.
The build procedure is therefore:
export XERCESCROOT={path to Xerces-C distribution}
./runConfigure
make
make install
In depth build instructions
UNIX build system
Pathan 2 uses the GNU autotools (GNU autoconf, GNU libtool) for
crossplatform compatibility.
You will need the Xerces source, which can be obtained from CVS using the
same procedure as described in the quick instructions. You must build this before continuing.
Xerces-C does not come with an installer and hence Pathan 2 cannot
assume the location of the Xerces-C headers. Before building the
environment variable XERCESCROOT must be set
to the root of a full Xerces-C source (src) distribution. (Assuming a Bourne shell again,
do
export XERCESCROOT={path to Xerces-C distribution}
)
Once XERCESCROOT is set run
./runConfigure
at the root of the Pathan 2 distribution.
This will run GNU configure and do a few miscellaneous prebuild
tasks. runConfigure takes several arguments which can be listed by using the --help parameter. Pathan 2 defaults to an optimised build. Any arguments not understood by runConfigure are passed on to GNU configure so you can use, for example ./runConfigure --prefix to install the Pathan 2 library and headers in somewhere other the default, /usr/local.
Make and install the library
make
make install
Both static and shared libraries are made by default. This behaviour
may be changed by passing --disable-shared or --disable-static to
runConfigure.
The Pathan 2 libraries are by default installed in /usr/local/lib and the header files in /usr/local/include/pathan.
Pathan example code
Pathan 2 includes several pieces of example code in samples/.
The example code includes
samples/basic - Heavily commented interface usage example
samples/xgrep - XGrep utility program
samples/evaluator - Eval utility program
samples/tests - Tests of the XPath/DOM interface
On UNIX the examples may be built with
make examples
at the root of the Pathan 2 distribution after make install has been run.
Note that the examples require the Pathan 2 headers and libraries in their installed location. Therefore ensure that the paths in which Pathan 2 is installed (the default is /usr/local/[include lib]) are in the compiler include and dynamic linker paths. The environment variables CPLUS_INCLUDE_PATH and LD_LIBRARY_PATH can be set to ensure this.
The examples may be built separately on Windows platforms (instructions in each subsection below).
examples/basic
The code in examples/basic provides a heavily commented example of the XPath interface is a good place to get started using the library. For more details see the
library usage instructions.
examples/xgrep
XGrep is a grep like utility for XML documents. XGrep is given an XPath expression and XML document, and returns all the matched nodes.
The source for XGrep is found in examples/xgrep. We have provided a Windows VC++ project file located at Win32Projects/XGrep/XGrep.dsw.
For more details about the XGrep utility please see the
XGrep documentation.
examples/tests
A comprehensive set of tests using the DOM3-XPath interface can
be found in examples/tests. These tests form
a set of regression tests.
On Windows systems these tests may be build using nmake /f makefile.win (remember to run vcvars32.bat to set up the command line compiler environment).
There is also a VC++ project which will build these tests, which can be found in Win32Projects/Tests/Tests.dsw.
Once built, the regression test can be performed by running checkDiffs on Unix systems or checkDiffs.bat on Windows systems (requires the program diff in the PATH).
These tests also provide useful examples of how to use Pathan 2's DOM3-XPath interface.
Pathan 2 test suite
Pathan 2 also includes a suite of source-level self-tests. After changing the source or compiling on an unsupported platform it is a good idea to build and run the testsuite.
On UNIX the testsuite may be build and run with
make test
at the Pathan root. Check that the Xerces shared library is in your linker path (LD_LIBRARY_PATH).
A Windows project file is provided in the Win32Projects/PathanTest/PathanTest.dsw directory off the root.
Rebuilding the lexer and parser with Flex and Bison
Pathan 2 uses flex and bison for lexical scanning and parsing. The
source distribution comes with premade lexer and parser source files
and hence flex and bison will only be required if you make changes to
the .lex or .y files.
Pathan 2 is a Unicode compliant program and requires a 16-bit Unicode
compliant version of flex.
flex-2.5.4a-unicode-patch
This flex unicode patch by James Laugh is against GNU flex version
2.5.4a (flex-2.5.4a.tar.gz). This version has a small change to the
flex Makefile over the original patch which removes a broken
bootstrapping test.
If you do lexer or parser development on the Windows branch,
note that the lexer and parser generating files are not included in
the Windows project files.
If you are rebuilding Pathan and get errors from flex, but you
haven't modified the .lex file then you should
be able to touch src/lexer/XPathLexer.cpp. This
should prevent make running flex, and the build
should progress normally.
Rebuilding the Windows headers
The header files necessary to build projects which link against Pathan 2 are
prepackaged in the include/ directory in the Windows source and binaries distributions (they are autogenerated on UNIX).
If you have altered code within src/dom3-xpath these headers should be regenerated. The include/pathan directory should contain all the files from src/dom3-xpath with the text of the src/config/win32/config.h copied into the top of src/dom3-xpath/Pathan.hpp, replacing #include <config.h>.
This is done to remove the dependency upon config.h which could potentially cause naming conflicts.
If perl is installed, config.h may be automatically integrated in Pathan.hpp by running
perl util/IntegrateConfigH.pl src/config/win32/config.h
at the Pathan root. This creates a new copy of Pathan.hpp in the objs/ subdirectory.
Building a Windows static library
The Pathan workspace file include a static library project.
If you are using Pathan 2 as a static library the Pathan.hpp header file included in code which uses the Pathan 2 library must be edited.
Replace the line
#define PATHAN_EXPORT __declspec(dllimport)
with
#define PATHAN_EXPORT
|
