# SaxonC-PE 12.10.0 download:
SaxonC-PE is a compiled variant of Saxon from the Java
platform to the C/C++ platform using GraalVM `native-image`.

SaxonC-PE provides processing in XSLT 3.0, XQuery 3.1 and XPath 3.1, and,
in SaxonC-EE, Schema validation 1.0/1.1.

## What's included in this download?
In this download, the binary shared libraries (.dylib files) for the
core part of Saxon, compiled with `native-image`, which we call
`libsaxonc-core-pe`, along with the sources for the C/C++-specific API,
which we call `libsaxonc-pe`, and its binary shared libraries, along with
the Transform and Query binaries for running XSLT and XQuery from the
command line.

## Installation
If you're intending to use the pre-compiled binaries, like Transform and Query,
then installation on your system is a matter of copying the libraries, and 
binaries to your preferred install location, ensuring the libraries can be found 
at runtime, and the binaries are on your PATH.

If you're intending to also use the C API, then you need to ensure the header 
files are also installed somewhere your build system can find them. We do not
currently recommend using the C++ API with the pre-compiled `libsaxonc-pe` in
case of ABI conflict, for that you can compile `libsaxonc-pe` yourself.

If you're intending to compile `libsaxonc-pe` yourself, then what you need to do
will depend on your project and its build system. We provide out-of-the-box 
compatibility with CMake, but using other systems should be straightforward.

### Installing the files
We recommend unpacking the release `.zip` under
`/opt/saxonica/SaxonCPE-macos-arm64-12-10-0`, and then adding the relevant
folders to your PATH and DYLD_LIBRARY_PATH environment variables. This allows
you to install more than one version, or edition, side-by-side,
should you need it.

For example:

	mkdir -p /opt/saxonica
    cd /opt/saxonica
    unzip /path/to/SaxonCPE-macos-arm64-12-10-0.zip

### Set the DYLD_LIBRARY_PATH and PATH environment variables
The DYLD_LIBRARY_PATH variable must include the locations of the lib
directories containing the SaxonC libraries. For instance:

	export DYLD_LIBRARY_PATH="/opt/saxonica/SaxonCPE-macos-arm64-12-10-0/SaxonCCorePE/lib:/opt/saxonica/SaxonCPE-macos-arm64-12-10-0/SaxonCPE/lib:$DYLD_LIBRARY_PATH"

If you're only going to use the pre-compiled `libsaxonc-core-pe`, and compile
`libsaxonc-pe` yourself, you only need to add the `SaxonCCorePE` lib path to
`DYLD_LIBRARY_PATH`.

To run the  binaries without referencing their full
path, the PATH variable can be set. For instance:

	export PATH="/opt/saxonica/SaxonCPE-macos-arm64-12-10-0/SaxonCPE/bin:$PATH"

## Running the binaries
Once you have the binaries on your path, you should be able to run the binaries
directly, for example:

	Transform -s:input.xml -xsl:stylesheet.xsl

See https://www.saxonica.com/documentation12/index.html#!using-xsl/commandline 
for information about `Transform`, and
https://www.saxonica.com/documentation12/index.html#!using-xquery/commandline 
for information about `Query`.

## Integrating with a CMake-using project

If you're planning to use both the provided `libsaxonc-core-pe` and
`libsaxonc-pe` `.dylib` files, then the `samples`
directory provides a fully working example, which you can boil down to the
following snippet for a `CMakeLists.txt`:

    list(APPEND CMAKE_PREFIX_PATH "/opt/saxonica/SaxonCPE-macos-arm64-12-10-0")
    find_package(SaxonCPE 12.10.0 EXACT REQUIRED)
    target_link_libraries(YourTarget PRIVATE SaxonCPE::saxonc-pe)

(Where `/opt/saxonica` is where you installed the libraries.)

If you're planning to compile `libsaxonc-pe` yourself, to use the C++
API, then you can use CMake's `FetchContent` in your `CMakeLists.txt` to
integrate it into your project:

    include(FetchContent)
    FetchContent_Declare(
        SaxonCPE
        URL "/opt/saxonica/SaxonCPE-macos-arm64-12-10-0"
        SOURCE_SUBDIR src
    )
    FetchContent_MakeAvailable(SaxonCPE)

That will automatically use the `SaxonCCorePE` bundled as
part of the `.zip` (which we assumed you unzipped to
`/opt/saxonica` in the example). If you need to use a different
`SaxonCCorePE`, for example, if you're cross-compiling, then you
need to specify where CMake can find that version, and prevent it from using
the bundled version. To do that, you can set the `NO_BUNDLED_SAXONC_CORE` CMake
variable to `TRUE` and then you have to manually make a version of
`SaxonCCorePE` available to CMake.

Here's a minimal example that assumes you have already made a `SaxonCCorePE`
package visible to CMake:

    # We have a non-standard libsaxonc-core-pe on CMake's search path,
    # but are using the C/C++ sources from the release version

    include(FetchContent)
    FetchContent_Declare(
        SaxonCHE
        URL "/opt/saxonica/SaxonCPE-macos-arm64-12-10-0"
        SOURCE_SUBDIR src
    )
    set(NO_BUNDLED_SAXONC_CORE TRUE)
    FetchContent_MakeAvailable(SaxonCPE)

And this is a more complete example showing cross-compilation on Linux:

    # Assume we are compiling on a Linux x86_64 host and have downloaded an Arm64
    # version of SaxonCCore to /opt/saxonica/SaxonCPE-linux-arm64-12-10-0,
    # and x86_64 version to /opt/saxonica/SaxonCPE-linux-x86_64-12-10-0
    include(FetchContent)
    FetchContent_Declare(
        SaxonCHE
        URL "/opt/saxonica/SaxonCPE-linux-x86_64-12-10-0"
        SOURCE_SUBDIR src
    )

    if(CMAKE_SYSTEM_PROCESSOR STREQUALS "aarch64")
        set(NO_BUNDLED_SAXONC_CORE TRUE)
        list(APPEND CMAKE_PREFIX_PATH "/opt/saxonica/SaxonCPE-linux-arm64-12-10-0")
    endif()
    FetchContent_MakeAvailable(SaxonCPE)

## Other resources
SaxonC-specific samples can be found at the [saxonc-resources][] GitHub
repository.

[saxonc-resources]: https://github.com/Saxonica/saxonc-resources

Full documentation for SaxonC-PE 12 is available. The [SaxonC 12 documentation][]
contains information specific to SaxonC - including instructions for installing
and configuring the product, details of the SaxonC C/C++ API, PHP API and
Python3 API, and sample code. Meanwhile, the main [Saxon 12 documentation][]
contains further information relevant to SaxonC.

[SaxonC 12 documentation]: https://www.saxonica.com/saxon-c/documentation12/index.html
[Saxon 12 documentation]: https://www.saxonica.com/documentation12/index.html
For further information, see the [SaxonC web page][]. For bug reporting,
lists of known bugs, and help forums, please visit
[https://saxonica.plan.io/] (https://saxonica.plan.io/).

[SaxonC web page]: https://www.saxonica.com/saxon-c/index.xml
