Saxonica: Saxon/C product information

Saxon/C

Saxon/C is currently on beta release: offering the Saxon-HE product for the C/C++ programming platform. APIs are offered currently to run XSLT 2.0 and XQuery 1.0 from C/C++ or PHP applications.

Saxon/C is built from the Java product Saxon-HE 9.5.1.5 using the Excelsior JET tool (version 9.0 MP2).

The current release is Saxon-HE/C 0.3.1.

License

The product is open-source. The primary license is the Mozilla Public License version 2.0. In most cases, the source files are marked as being "incompatible with secondary licenses", which means that the code cannot be combined with code issued under a GPL license (the reason for this is the difficulty of contacting all past contributors to gain their assent).

Some components are licensed under the Apache version 2.0 license or under BSD-style licenses. For more information see Licenses.

Return to top of page

Download

Please use the links below to download the Saxon-C installer (Linux or Windows).

Linux binary

(32-bit and 64-bit versions)

libsaxon-HEC-setup-v0.3.1.zip 32-bit version (13 MB)

libsaxon-HEC-setup64-v0.3.1.zip 64-bit version (39 MB)

The 64-bit linux version is a self-contained zip file which must be unpacked in the same way as in the 32-bit version. Some 64-bit Linux flavors do not run the 32-bit JET libraries by default. You need to install the ia32-libs on Ubuntu/Debian, the procedure is as simple as:
sudo apt-get install ia32-libs

Windows

(32-bit version)

libsaxon-HEC-setup-v0.3.1.exe (9.17 MB)

The Saxon/C dll library is a 32-bit version. The PHP extension dll was compiled for PHP version 5.4 (TS/NTS).

Mac OS X

Saxon-HEC-v0.3.1.1-Mac-native.zip (38 MB)

The Saxon/C dylib library is currently running with Excelsior Jet 10 evaluation version therefore is available for testing purposes.

By downloading the software, you agree to the terms and conditions of the Mozilla Public License version 2.0.

Return to top of page

Archive

Alpha release 0.2:

Linux

libsaxon-HEC-setup-v0.2.zip (12 MB)
libsaxon-HEC-setup64-v0.2.zip (31 MB)

Windows

libsaxon-HEC-setup-v0.2.exe 32-bit (8 MB)

Return to top of page

Documentation

Saxon/C beta version 0.3.1

Saxon/C alpha version 0.2

Saxon/C alpha version 0.1

PHP API

Release notes

Return to top of page

Installation (Linux)

Prerequisites

Please have the following packages on your machine to build the Saxon/C PHP extension: make, php-devel, (php5-dev/php55-dev/php55w-devel), apache2 or httpd, gcc-c++ or g++, gcj-jdk (or just link the jni.h file).

Saxon-HE/C

To install the Saxon-HE/C release unzip the file libsaxon-HEC-setup.zip and execute the command ./libsaxon-HEC-setup

The first step is to select the destination where the product files will be installed. The product files are unpacked in the directory 'Saxon-HEC'.

You need to set up the environment for the jet jvm. The jvm is in the directory 'JET-home=Saxonica-HEC/rt'. The directory 'JET-home/lib/i386' must be listed in the LD_LIBRARY_PATH environment variable. For instance, if you are using a bash or Bourne shell, use the following command:

export LD_LIBRARY_PATH=/usr/lib/rt/lib/i386:/usr/lib64/rt/lib/i386/jetvm:$LD_LIBRARY_PATH

Or on a 64-bit machine:

export LD_LIBRARY_PATH=/usr/lib64/rt/lib/amd64:/usr/lib64/rt/lib/amd64/jetvm:$LD_LIBRARY_PATH

So, for Ubuntu, you can create '/etc/ld.so.conf.d/jetvm.conf', with content (change amd64 to i386 for a 32-bit machine) -

        # JetVM env path (requierd for Saxon)
        /usr/lib/rt/lib/amd64
        /usr/lib/rt/lib/amd64/jetvm
            

And then run -

$ sudo ldconfig

When working with PHP the export command above should be added to apache environment variables. The apache2 config file is located in one of the following locations depending on your linux distribution:

  • Ubuntu server: /etc/apache2/envvars
  • Centos server: /etc/sysconfig/httpd
  • SUSE server: /etc/sysconfig/apache2

The C++ compiler requires the include path to the java header files during compilation. In most cases this is achieved simply by installing gcj-jdk. Alternatively, according to http://www.network-theory.co.uk/docs/gccintro/gccintro_23.html, add the java header file dirs in the JAVA_HOME directory to this environment variable used by compiler. The following example is for a 64-bit machine:

CPLUS_INCLUDE_PATH=/usr/lib/rt/amd64:$JAVA_HOME/include/linux:$JAVA_HOME/include
export CPLUS_INCLUDE_PATH

For a 32-bit machine the 'rt' directory and libsaxon.so library must be copied to the location '/usr/lib'.

For a 64-bit machine the 'rt' directory and the libsaxon.so library must be copied to the location '/usr/lib64'. You must also copy the saxon-data directory to a respective location based on the machine.

PHP extension

To build the PHP extension follow the steps below.

(Alternatively, you may like to use the installation script install.sh supplied by Petr Zak - written for a 64-bit machine, but can be changed for a 32-bit machine.)

Run the commands:

  • phpize
  • ./configure --enable-saxon
  • make
  • sudo make install

Update the php.ini file (if using Ubuntu it is usually in the location '/etc/php5/apache2/') to contain the PHP extension. Insert the following in the Dynamic Extensions section: extension=saxon.so, then run the command

  • sudo service apache2 restart

Return to top of page

Installation (Windows)

Saxon-HE/C

To install the Saxon-HE/C release run the executable libsaxon-HEC-setup.exe.

The first step is to select the destination where the product files will be installed - the default is 'C:\Program Files (x86)\Saxonica\SaxonHEC0.3.1'. This is the location that the PHP extension looks for the Saxon-C DLL library, so we advise using this default location.

PHP extension

The PHP extension is built using Visual Studio 2008 (VC9) with PHP 5.4 (TS). We hope to provide builds for other PHP releases soon. To install the PHP extension follow the steps below:

  • Locate where the file php_saxon.dll has been installed (e.g. 'C:\Program Files\Saxonica\SaxonHEC0.3.1\php_extension') and either copy it into the '[php_home]/ext' folder of the PHP directory or point to it in its current location in the php.ini file.

  • As mentioned in the first step, the PHP extension needs to be referenced in the php.ini file. Also within the php.ini file, locate the section 'Dynamic Extensions' and add the following at the end:
    [CustomExt]
    extension=C:\php\ext\php_saxon.dll

    The default is the ext directory, but this can be changed.

  • Restart your Apache2 server. Check that the Saxon-C PHP extension has been installed correctly (i.e. use <?php phpinfo() ?>). The extension should now be ready for use.

Note: On Windows we recommend setting the cwd using the overloaded constructor because there remains an issue with building Saxon/C with PHP when using the function VCWD_GETCWD. That is,
$proc = new SaxonProcessor('C://www/html//trax//');
should replace instances of
$proc = new SaxonProcessor();
in your PHP scripts (see the PHP example code in the Getting started section for an example).

To build the PHP extension yourself please see the Saxon-C-API Visual Studio 2008 project included in the installation (e.g. 'C:\Program Files\Saxonica\SaxonHEC0.3.1\Saxon-C-API').

Return to top of page

Building from source

Downloadable project zip file: libsaxon-HEC_jetpdb.zip

We endeavour to build the library of Saxon/C on 32/64- bit machines for both linux and windows. But in the case where the binary is not available for a particular machine we suggest building the shared binary library from the Java jar file. To do this you will need the Excelsior Jet tool (version 9.0 MP2). Excelsior JET provides an evaluation package and free licenses for non-commercial use (see their website for more details).

The project files are available in the project zip file 'libsaxon-HEC_jetpdb.zip', available above. Unzip the file and execute the command ./build_libsaxon-HEC.sh which will create the shared library file in the current directory, after which you can follow the instructions (after the first step) in the relevant installation section above (Linux installation or Windows installation).

Return to top of page

Getting started

To get started writing a C/C++ or PHP application, first browse the Saxon/C API starting with the SaxonProcessor class which acts as a factory class for generating the processors.

C

To compile with C please refer to the 'Saxonica/Saxon-HEC0.2/Saxon-C-API/c' directory. This includes handy scripts to build and run example code, e.g. build.sh and run-edit.sh

C++

To compile a C++ application see the example below:
g++ -g -o SaxonProcessor SaxonProcessor.cpp -ldl -lsaxon -lstdc++ -DCPP_ONLY ./SaxonProcessor

C++ example code:
SaxonProcessor *processor = new SaxonProcessor(false);
XsltProcessor * xslt = processor->newTransformer();
cout<<"Hello World"<<endl;
cout<<"Test output: "<<xslt->xsltApplyStylesheet("cat.xml","test.xsl")<<endl;

For more information, see the file 'SaxonProcessor.cpp'.

PHP

PHP example code:

<?php 
        /* simple example to show transforming to a string */
            
    function exampleSimple1($proc, $xmlfile, $xslFile){
        $proc->setSourceFile($xmlfile);
        $proc->setStylesheetFile($xslFile);
  	              
        $result = $proc->transformToString();               
        if($result != null) {               
            echo '<b/>exampleSimple1:</b/><br/>';		
            echo 'Output:'.$result;
        } else {
           echo "Result is null";
        }
        $proc->clearParameters();
        $proc->clearProperties();            
    }
                        
    $foo_xml = "xml/foo.xml";
    $foo_xsl = "xsl/foo.xsl";
            
    $proc = new SaxonProcessor();
   
//On Windows we recommend setting the cwd using the overloaded constructor 
//because there remains an issue with building Saxon/C with PHP when using 
//the function VCWD_GETCWD. So replace the line above with 
//$proc = new SaxonProcessor('C://www/html//trax//');
		
    $version = $proc->version();
    echo 'Saxon Processor version: '.$version;
    echo '<br/>';        
    exampleSimple1($proc, $foo_xml, $foo_xsl);
?>

Also available is the file xslt30TestSuite.php. This is a test driver designed to run the public W3C XSLT test suite at https://dvcs.w3.org/hg/xslt30-test/. The test driver in its current form requires Saxon-EE, which is not yet available in this Saxon/C release; nevertheless, the program may serve as a useful example of how the API can be used. Note that it is written to use libXML to read the test catalog, but to use Saxon for running the tests and assessing the results.

Return to top of page

Debugging

Exceptions and errors are captured and maintained silently in Saxon/C, but can be accessed. This is due to the restrictions in JNI: "There is no uniform and general way to throw and catch exceptions in native languages compared to Java. The JNI therefore requires you to check for possible exceptions after calling JNI functions".

Any exceptions or errors found in a Saxon/C method can be retrieved by the method call 'getErrorMessage(i)', where i is an index number referring to the ith error message. The method getErrorCount() gets the total number of errors reported, which helps to loop through the errors if there are more than one of them. Please see the following PHP code snippet:

<?php
    ...
    $result = $xslt->queryToString();
    if($result == NULL) {		
        $errCount = $xslt->getExceptionCount();
        if($errCount > 0 ){
            for ($i = 0; $i &lt; $errCount; $i++) {
                $errC = $xslt->getErrorCode(intval(i));
                $errMessage = $xslt->getErrorMessage(intval(i));
                if($errC != NULL) {
                    echo 'Error found: '. $errC.' :'.$errMessage;	
                }
                $xslt->exceptionClear();
            }
        }
    }
    ...
?>

Return to top of page

Support

Please use the help forums and bug trackers at saxonica.plan.io, or the saxon-help mailing list, if you need help or advice. For more details see Support.

Return to top of page

Troubleshooting

After installing Saxon/C, if you notice anomalies in execution then the apache log file usually has useful information on errors reported and crashes. We try to best describe some of the common errors and crashes, and their solutions, below:

  • FATAL ERROR: Unable to load /usr/lib64/rt/lib/amd64/libjava.so (libjvm.so cannot open shared object file: No such file or directory) JNI_CreateJavaVM() failed with result-1

    Solution: Create symlink to java virtual machine. This is not required to install/compile, but it is required for PHP code. The following should resolve the issue on a 64-bit machine:
    ln -s $JAVA_HOME/jre/lib/amd64/server/libjvm.so /lib64/libjvm.so
    Alternatively, it is possible to link the libjvm.so from the rt/lib/jetjvm directory.
  • /usr/lib/Saxon-C-API/SaxonProcessor.h:3:17: fatal error: jni.h: No such file or directory
    #include <jni.h> compilation terminated.

    Solution: Link the jni.h on the machine or simply install gcj-jdk which should resolve this error.

Return to top of page

14 March 2014