Saxon/C Product Information
saxonica.com

Saxon/C

On this page:

  • About Saxon/C
  • License
  • Download - Release notes
  • Documentation
  • Installation of library - Linux and Windows
  • Building from Source
  • Getting Started
  • Debugging
  • Support
  • Troubleshooting


  • Saxon/C is in beta release of Saxon-HE on 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 8.0).

    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 on licensing, see license

    Although the Saxon code itself is open source, building the product requires commercial tools, specifically Excelsior JET. Excelsior offer a free-of-charge license for use in conjunction with open source software.

    Download

    Please click on the link 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 (13 MB)

    libsaxon-HEC-setup64-v0.3.1.zip Evaluation 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

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

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

    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).

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

    Documentation

    Documentation for Saxon/C beta version 0.3.1 is available here.

    Documentation for Saxon/C version 0.2 is available here.

    Documentation for Saxon/C version 0.1 here.

    Documentation on PHP API click here

    Release notes: click here

    Installation (Linux):

    Prerequesities

    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 (or just link the jni.h file)

    Saxon-HE/C:

    To install the Saxon-HE/C beta release unzip the the file libsaxon-HEC-setup.zip and execute the command './libsaxon-HEC-setup'
    First step is to select the destination of where the product files will be installed. The product files are unpacked in the directory 'Saxon-HEC'

    You need to setup 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 bash or Bourne shell, use the following commands:

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

    On the 64-bit machine set the LD_LIBRARY_PATH environment as follows:

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

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

    We assume that the 'rt' directory is in the location /usr/lib, but the directory '/usr/lib64' on a 64-bit machine is just as good. The Saxon-HEC API assumes the library is installed as follows: '/usr/lib/libsaxon.so'. You must also copy the saxon-data directory to directory '/usr/lib/'.

    PHP extension:

    To build the php extension follow the steps below:

    Run the commands:

    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

    install.sh - A useful installation script supplied by Petr Zak (written for a 64-bit machine, but can be changed for a 32-bit machine).

    Installation (Windows):

    Saxon-HE/C:

    To install the Saxon-HE/C alpha release run the executable libsaxon-HEC-setup.exe
    First step is to select the destination of where the product files will be installed [default: 'C:\Program Files (x86)\Saxonica\SaxonHEC0.2']. The default location is where the PHP extension looks for the SAxon-C DLL library, therefore we advise to use this 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:

    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. Example: i.e. $proc = new SaxonProcessor('C://www/html//trax//');

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

    Building the binary from the Java jar

    Download 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 8.0) as a prerequisite. 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 following zip file: libsaxon-HEC_jetpdb.zip. 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 above in the installation section after the first steps.

    Getting started

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

    C++

    To compile with C++ application see example below:

     g++ -g -o SaxonProcessor SaxonProcessor.cpp -ldl -lsaxon -lstdc++ -DCPP_ONLY
                
    ./SaxonProcessor

    C

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

    C++ Code:

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

    See the file SaxonProcessor.cpp

    PHP Example code:

    Example code:

    
        <?php 
                /* simple example to show transforming to 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. i.e. $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 alpha 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.

    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 execptions/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 < $errCount; $i++) {
                        $errC = $xslt->getErrorCode(intval(i));
                        $errMessage = $xslt->getErrorMessage(intval(i));
                        if($errC != NULL) {
                            echo 'Error found: '. $errC.' :'.$errMessage;	
                        }
                        $xslt->exceptionClear();
                      }
                    }
                    ...
                    ?>
                

    Support

    Please use the help forums and bug trackers at saxonica.plan.io if you need help or advice. Also email list: saxon-help@lists.sourceforge.net

    Troubleshooting

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

    Potential issues

    Solutions/Comments

    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 Create symlink to java virtual machine, it is not required to install/compile, but it's requirement to use it from 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
    It is posible 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.
    Link the jni.h on the machine or simply install gcj-jdk which should resolve this error

    Optimized and packaged with Excelsior JET

    14 March 2014