Pathan 1 Build Documentation
Pathan 1 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 1.
Note that you will require a full source distribution of Xerces. The binary Xerces distribution is not sufficient.
Xerces may be
downloaded from its website.
Quick build instructions
In depth build instructions
Quick build instructions
Windows
The project and workspace files for Pathan 1 are stored in
{pathan root}/Win32Projects/Pathan
By default Pathan 1 compiles to a dynamic library (.dll).
In order to build Pathan 1, you will require both the Xerces-C
source and Windows binaries distribution (unless you are happy to
build Xerces-C itself).
By default Pathan 1.2 looks for a copy of the Xerces-C
source
distribution located in a directory based at the same
level as the Pathan distribution (ie. for Pathan 1.2 release 2, Xerces 2.3
should be unzipped into a directory called
xerces-c-src_2_3_0/ alongside the
libpathan-1.2/ directory).
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 1 you will need full Xerces-C source
distribution
(ie. xerces-c-src1_x_y.tar.gz). Pathan 1 also
requires built Xerces libraries. Therefore you should build Xerces
prior to building Pathan 1 or copy the prebuilt libraries from the
Xerces binary distribution into a lib/
directory created off the Pathan 1 source distribution root.
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.
Before building Pathan 1 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.).
The build procedure is therefore:
export XERCESCROOT={path to Xerces-C distribution}
./runConfigure
make
make install
In depth build instructions
UNIX build system
Pathan 1 uses the GNU autotools (GNU autoconf, GNU libtool) for
crossplatform compatibility.
Xerces-C does not come with an installer and hence Pathan 1 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.
Once XERCESCROOT is set run
./runConfigure
at the root of the Pathan 1 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 1 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 1 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 1 libraries are by default installed in /usr/local/lib and the header files in /usr/local/include/pathan.
Pathan example code
Pathan 1 includes several pieces of example code in examples/.
The example code includes
examples/basic - Heavily commented interface usage example
examples/xgrep - XGrep utility program
examples/tests - Tests of the XPath/DOM interface
On UNIX the examples may be built with
make examples
at the root of the Pathan 1 distribution after make install has been run.
Note that the examples require the Pathan 1 headers and libraries in their installed location. Therefore ensure that the paths in which Pathan 1 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 1's DOM3-XPath interface.
Pathan 1 test suite
Pathan 1 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 1 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 1 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 1 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 1 as a static library the Pathan.hpp header file included in code which uses the Pathan 1 library must be edited.
Replace the line
#define PATHAN_EXPORT __declspec(dllimport)
with
#define PATHAN_EXPORT
Problems with building Pathan 1
When building Pathan 1, two modified Xerces-C header files are used. These header files can be found in src/patches. If you are getting errors along the lines of fImpl is protected, then insure your include paths look for these headers in src/patches before looking in
the regular Xerces-C distribution. Unless the makefiles or project files have been altered this problem shouldn't occur.
|
