Project

Profile

Help

How to connect?
Download (32.6 KB) Statistics
| Branch: | Tag: | Revision:

he / latest9.9 / hec / saxonc-doc / doc / starting.xml @ 34f79044

1
<?xml version="1.0" encoding="UTF-8"?>
2
<article id="starting" title="Getting Started">
3
   <h1>Getting Started</h1>
4

    
5
   <p>This section of the documentation describes how to get hold of Saxon/C and the PHP and Python
6
      extensions, how to install on the different platforms, and how to get started using it.</p>
7

    
8
   <nav>
9
      <ul/>
10
   </nav>
11

    
12
   <p>Please use the help forums ("Forums") and bug trackers ("Issues") in the <a target="_blank"
13
         href="https://saxonica.plan.io/projects/saxon-c">Saxon/C project</a> at the Saxonica
14
      community site if you need help or advice, or want to provide any other feedback.</p>
15

    
16

    
17
   <section id="installing" title="Installing Saxon/C">
18
      <h1>Installing Saxon/C</h1>
19

    
20
      <p>Saxon/C can be installed on Linux, Mac OS and Windows. In this section we provide a step by
21
         step installation guide for the three platforms.</p>
22

    
23
      <nav>
24
         <ul/>
25
      </nav>
26

    
27
      <p>For information on installing the PHP and Python extensions see the <a
28
            href="/starting/installingphp">PHP Extension</a> and <a
29
            href="/starting/installingpython">Python Extension</a> sections.</p>
30

    
31
      <section id="installingLinux" title="Linux">
32
         <h1>Installing on Linux</h1>
33

    
34
         <aside>In the following, [EDITION] means one of: HE, PE, EE; and [VERSION] is the
35
            maintenance release version number (for instance 1.2.1). </aside>
36
         
37
         <ol>
38
            <li>
39
               <p><b>Download</b></p>
40
               <p>Download the Saxon/C software from www.saxonica.com. There are different downloads
41
                  available for the Saxon-HE, Saxon-PE and Saxon-EE products, for different
42
                  operating systems.</p>
43
            </li>
44
            <li>
45
               <p><b>Unpack</b></p>
46
               <p>To install the Saxon-[EDITION]/C release on Linux, first unzip the file
47
                  <code>libsaxon-[EDITION]C-setup64-v[VERSION].zip</code> and execute the following
48
                  command to fully unpack the files:</p>
49
               <kbd>./libsaxon-[EDITION]C-setup64-v[VERSION]</kbd>
50
            </li>
51
            <li>
52
               <p><b>Copy the core Saxon/C installation files to the install location</b></p>
53
               <p>The core Saxon/C files which must be copied are:</p>
54
               <ul>
55
                  <li><code>libsaxon[EDITION].so</code> - Saxon/C library</li>
56
                  <li><code>rt</code> directory - Excelsior JET runtime which handles VM calls</li>
57
                  <li><code>saxon-data</code> directory</li>
58
               </ul>
59
               
60
               <p>On Linux, the expected install location is <code>/usr/lib</code>, and the following
61
                  commands use this default. If you choose to install to a different location, then
62
                  the SAXONC_HOME variable must be set accordingly (see the next step).</p>
63
               
64
               <p>For instance, to copy the product files from the unpacked location
65
                  <code>Saxonica/Saxon-[EDITION]C-[VERSION]</code>, to <code>/usr/lib</code>:</p>
66
               
67
               <kbd>cd Saxonica/Saxon-[EDITION]C-[VERSION]/</kbd>
68
               <kbd>sudo cp libsaxon[EDITION].so /usr/lib/.</kbd>
69
               <kbd>sudo cp -r rt /usr/lib/.</kbd>
70
               <kbd>sudo cp -r saxon-data /usr/lib/.</kbd>
71
            </li>
72
            <li>
73
               <p><b>Set the SAXONC_HOME environment variable</b></p>
74
               <p>The SAXONC_HOME variable must be set to the location where the Saxon/C files have
75
                  been installed. For instance:</p>
76
               <kbd>export SAXONC_HOME=/usr/lib</kbd>
77
               <p>If the Saxon/C files were installed to a location other than the default
78
                  <code>/usr/lib</code>, then the SAXONC_HOME variable must be set to the correct
79
                  location.</p>
80
            </li>
81
         </ol>
82
         
83
         <aside>The use of symbolic links to specify where the Saxon/C library is installed is no longer
84
            recommended. It is better to set the SAXONC_HOME environment variable directly.</aside>
85
         
86
         <!--TODO what about JET-home environment variable? If you use the same location as for saxon
87
         library, as above, then it doesn't need to be set separately???
88
            - similarly what about LD_LIBRARY_PATH ?-->
89
         
90

    
91
         <!--<ol>
92
            <li>
93
               <p>To install the Saxon-[EDITION]/C release, first unzip the file
94
                  <code>libsaxon-[EDITION]C-setupv[VERSION].zip</code> and execute the
95
                  command:</p>
96
               <kbd>./libsaxon-[EDITION]C-setup-v[VERSION]</kbd>
97
            </li>
98

99
            <li>
100
               <p>The next step is to select the destination where the product files will be
101
                  installed. The product files are unpacked in the <code>Saxon-[EDITION]C</code>
102
                  directory.</p>
103

104
               <kbd>cd Saxonica/Saxon-[EDITION]C[VERSION]/</kbd>
105
               <kbd>sudo cp libsaxon[EDITION].so /usr/lib/.</kbd>
106

107
               <p>Alternatively you can either create a symbolic link to where the saxon library is
108
                  installed so it can be found or use the SAXONC_HOME environment variable to set the location of the library. For example:</p>
109

110
               <kbd>ln -s path/Saxonica/Saxon-[EDITION]C[VERSION]/libsaxon[EDITION].so
111
                  /usr/lib/libsaxon[EDITION].so</kbd>
112

113
               <p>Or</p>
114
               <kbd>export SAXONC_HOME=path/Saxonica/Saxon-[EDITION]C[VERSION]</kbd>
115
               <p>You may also need to set the LD_LIBRARY_PATH to the same location.</p>
116
               
117
            </li>
118

119
            <li>
120
               <p>You need to set up the environment for the JET JVM. The JVM is in the
121
                     <code>Saxonica/Saxon-[EDITION]C[VERSION]/rt</code> directory.</p>
122

123
               <kbd>sudo cp -r rt /usr/lib/.</kbd>
124

125
               <p>Alternatively you can create a symbolic link to the JetVM library so it can be
126
                  found. For example:</p>
127

128
               <kbd>ln -s path/Saxonica/Saxon-[EDITION]C[VERSION]/rt /usr/lib/rt</kbd>
129
            </li>
130

131
            <li>
132
               <p>Set the JET-home environment accordingly to where it is installed, e.g.
133
                     <code>JET-home=/usr/lib/Saxon-[EDITION]C[VERSION]/rt</code>. The directory
134
                     <code>JET-home/lib/amd64</code> must be listed in the
135
                     <code>LD_LIBRARY_PATH</code> environment variable. For instance, if you are
136
                  using a bash or Bourne shell, use the following command:</p>
137
               <kbd style="word-wrap: break-word;">export JET_HOME=/usr/lib/rt</kbd>
138
               <kbd style="word-wrap: break-word;">export
139
                  LD_LIBRARY_PATH=$JET_HOME/lib/amd64/jetvm:$JET_HOME/lib/amd64:$LD_LIBRARY_PATH</kbd>
140

141
               <p>Alternatively, for Ubuntu, you can create a file <code>/etc/ld.so.conf.d/jetvm.conf</code>
142
                  with content:</p>
143

144
               <samp><![CDATA[# JetVM env path (required for Saxon)
145
      /usr/lib/rt/lib/amd64
146
      /usr/lib/rt/lib/amd64/jetvm]]></samp>
147

148
               <p>Next run: </p>
149
               <kbd>sudo ldconfig</kbd>
150
               <p>Ignore the message 'file /lib/libsaxon[EDITION].so is truncated'. The library was created using
151
               Excelsior JET. The library is loaded from within the Saxon/C application and not in the usual way of shared libraries.</p>
152
            </li>
153
            
154
            <li>
155
               <p>You must also copy the <code>saxon-data</code> directory into the same directory
156
                  as the <code>libsaxon[EDITION].so</code>.</p>
157
            </li>
158
         </ol>-->
159

    
160
         <p>Saxon/C is now installed, and ready to run. Please see <a href="../running">Running
161
               Saxon/C</a> to get started. Note that the commercial products Saxon-PE/C and
162
            Saxon-EE/C require a license, so you may also need to refer to <a href="../licensing"
163
               >Licensing</a> for details about how to get this set up.</p>
164

    
165
      </section>
166

    
167

    
168
      <section id="installingMac" title="Mac OS">
169
         <h1>Installing on Mac OS</h1>
170

    
171
         <aside>In the following, [EDITION] means one of: HE, PE, EE; and [VERSION] is the
172
            maintenance release version number (for instance 1.2.1). </aside>
173
         
174
         <ol>
175
            <li>
176
               <p><b>Download</b></p>
177
               <p>Download the Saxon/C software from www.saxonica.com. There are different downloads
178
                  available for the Saxon-HE, Saxon-PE and Saxon-EE products, for different
179
                  operating systems.</p>
180
            </li>
181
            <li>
182
               <p><b>Unpack</b></p>
183
               <p>To install the Saxon-[EDITION]/C release on Mac OS, first unpack the download by
184
                  unzipping the file <code>libsaxon-[EDITION]C-mac-setup-v[VERSION].zip</code>.</p>
185
            </li>
186
            <li>
187
               <p><b>Copy the core Saxon/C installation files to the install location</b></p>
188
               <p>The core Saxon/C files which must be copied are:</p>
189
               <ul>
190
                  <li><code>libsaxon[EDITION].dylib</code> - Saxon/C library</li>
191
                  <li><code>rt</code> directory - Excelsior JET runtime which handles VM calls</li>
192
                  <li><code>saxon-data</code> directory</li>
193
               </ul>
194
               
195
               <p>On Mac OS, the expected install location is <code>/usr/local/lib</code>, and the following
196
                  commands use this default. If you choose to install to a different location, then
197
                  the SAXONC_HOME variable must be set accordingly (see the next step).</p>
198
               
199
               <p>For instance, to copy the product files from the unpacked location
200
                  <code>Saxonica/Saxon-[EDITION]C-[VERSION]</code>, to <code>/usr/local/lib</code>:</p>
201
               
202
               <kbd>cd Saxonica/Saxon-[EDITION]C-[VERSION]/</kbd>
203
               <kbd>sudo cp libsaxon[EDITION].dylib /usr/local/lib/.</kbd>
204
               <kbd>sudo cp -r rt /usr/local/lib/.</kbd>
205
               <kbd>sudo cp -r saxon-data /usr/local/lib/.</kbd>
206
            </li>
207
            <li>
208
               <p><b>Set the SAXONC_HOME environment variable</b></p>
209
               <p>The SAXONC_HOME variable must be set to the location where the Saxon/C files have
210
                  been installed. For instance:</p>
211
               <kbd>export SAXONC_HOME=/usr/local/lib</kbd>
212
               <p>If the Saxon/C files were installed to a location other than the default
213
                  <code>/usr/local/lib</code>, then the SAXONC_HOME variable must be set to the correct
214
                  location.</p>
215
            </li>
216
         </ol>
217
         
218
         <!-- TODO Would it be useful to add the following back to step 3? 
219
               "The privileges of the folders and files may need adjusting after copying everything
220
               if you encounter permission issues." -->
221
         
222
         <!-- TODO Also note previously had info about setting DYLD_LIBRARY_PATH, is that still
223
            necessary? -->
224

    
225
         <!--<ol>
226
            <li>
227
               <p>To install any of the Saxon/C releases on the Mac OS system, first unzip the
228
                  self-contained file <code>libsaxon-[EDITION]-mac-setup-v[VERSION].zip</code>.</p>
229
            </li>
230

231
            <li>
232
               <p>The next step is to copy the <code>libsaxon[EDITION].dylib</code> library and the
233
                     <code>rt</code> directories to your install location. The C/C++ interface by
234
                  default assumes the library files and directories are installed in the
235
                     <code>/usr/local/lib</code> directory. The location of the Saxon/C library can
236
                  be set using the <code>SAXONC_HOME</code> environment variable. The privileges of
237
                  the folders and files may need adjusting after copying everything if you encounter
238
                  permission issues. Use for instance the following commands:</p>
239

240
               <kbd>cd libsaxon-HEC-mac-setup-v[VERSION]/</kbd>
241
               <kbd>sudo cp libsaxonhec.dylib /usr/local/lib/.</kbd>
242
               <kbd>sudo cp -r rt /usr/local/lib/.</kbd>
243
            </li>
244

245
            <li>
246
               <p>The <code>DYLD_LIBRARY_PATH</code> environment variable must be set as
247
                  follows:</p>
248

249
               <kbd>export JET_HOME=/usr/local/lib/rt</kbd>
250
               <kbd>export DYLD_LIBRARY_PATH=$JET_HOME/lib/jetvm:$DYLD_LIBRARY_PATH</kbd>
251
            </li>
252
         </ol>-->
253

    
254
         <p>Saxon/C is now installed, and ready to run. Please see <a href="../running">Running
255
               Saxon/C</a> to get started. Note that the commercial products Saxon-PE/C and
256
            Saxon-EE/C require a license, so you may also need to refer to <a href="../licensing"
257
               >Licensing</a> for details about how to get this set up.</p>
258

    
259
      </section>
260

    
261
      <section id="installingWindows" title="Windows">
262
         <h1>Installing on Windows</h1>
263

    
264
         <aside>In the following, [EDITION] means one of: HE, PE, EE; and [VERSION] is the
265
            maintenance release version number (for instance 1.2.1). </aside>
266
         
267
         <ol>
268
            <li>
269
               <p><b>Download</b></p>
270
               <p>Download the Saxon/C software from www.saxonica.com. There are different downloads
271
                  available for the Saxon-HE, Saxon-PE and Saxon-EE products, for different
272
                  operating systems.</p>
273
            </li>
274
            <li>
275
               <p><b>Unpack</b></p>
276
               <p>To install the Saxon-[EDITION]/C release on Windows, first run the executable
277
                  <code>libsaxon-[EDITION]-win-setup-v[VERSION].exe</code>.</p>
278
               <p>This installation script unpacks the Saxon/C files in the <code>C:\Program
279
                  Files\Saxonica\Saxon[EDITION][VERSION]</code> directory by default.</p>
280
            </li>
281
            <li>
282
               <p><b>Choose the install location for the core Saxon/C installation files</b></p>
283
               
284
               <p>On Windows, the default and recommended location is <code>C:\Program
285
                  Files\Saxonica\Saxon[EDITION][VERSION]</code>. This is the location that the
286
                  PHP extension looks for the Saxon/C DLL library, so we advise using this default
287
                  location.</p>
288
               
289
               <p>If you choose to install to a different location, then the SAXONC_HOME variable
290
                  must be set accordingly (see the next step).</p>
291
               
292
               <!--<p>TODO: how does the user specify the installation destination?</p>
293
               <p>Selected as a step in the installer executable???</p>-->
294
            </li>
295
            <li>
296
               <p><b>Set SAXONC_HOME environment variable</b></p>
297
               <p>If the Saxon/C files were installed to a location other than the default
298
                  <code>C:\Program Files\Saxonica\Saxon[EDITION][VERSION]</code>, then the
299
                  SAXONC_HOME variable must be set to the correct location.</p>
300
               <!--<p>TODO how?</p>-->
301
            </li>
302
         </ol>
303

    
304
         <!--<ol>
305
            <li>
306
               <p>To install the Saxon-[EDITION]/C release, first run the executable
307
                     <code>libsaxon-[EDITION]-win-setup-v[VERSION].exe</code>.</p>
308
            </li>
309

310
            <li>
311
               <p>The next step is to select the destination where the product files will be
312
                  installed - the default and recommended location is <code>C:\Program
313
                     Files\Saxonica\Saxon[EDITION][VERSION]</code>. This is the location that the
314
                  PHP extension looks for the Saxon/C DLL library, so we advise using this default
315
                  location. </p>
316
            </li>
317
         </ol>-->
318

    
319
         <p>Saxon/C is now installed, and ready to run. Please see <a href="../running">Running
320
               Saxon/C</a> to get started. Note that the commercial products Saxon-PE/C and
321
            Saxon-EE/C require a license, so you may also need to refer to <a href="../licensing"
322
               >Licensing</a> for details about how to get this set up.</p>
323

    
324

    
325
      </section>
326

    
327

    
328
   </section>
329

    
330
   <section id="licensing" title="Licensing">
331
      <h1>Licensing</h1>
332

    
333
      <h2 class="subtitle">Saxon-PE/C and Saxon-EE/C</h2>
334

    
335
      <p>Saxon-PE/C and Saxon-EE/C are commercial products, and require a license key. By
336
         downloading the software, you agree to the terms and conditions published at <a
337
            target="_blank" href="https://saxonica.com/license/eval-license.pdf"
338
            >https://saxonica.com/license/eval-license.pdf</a> (for use with a free <a
339
            target="_blank" href="https://saxonica.com/download/download.xml">evaluation
340
         license</a>) or <a target="_blank" href="https://saxonica.com/license/paid-license.pdf"
341
            >https://saxonica.com/license/paid-license.pdf</a> (in the case of paid-up licenses,
342
         purchased from our <a target="_blank" href="https://saxonica.com/shop/shop.html">online
343
            store</a>).</p>
344

    
345
      <h3>Location of the Saxon license file</h3>
346

    
347
      <p>Saxon/C looks in the path relative to where the main library has been installed. For
348
         example, in <code>/usr/lib</code> if this is where <code>libsaxon[EDITION]c.so</code> has
349
         been installed. Alternatively, Saxon also looks for the license according to the
350
         environment variable <code>SAXONC_HOME</code>, if this has been set.</p>
351
      <!--<p>The license file can also be placed in the same directory as the stylesheet, but we advise
352
         against this for PHP servers where the license might be compromised.</p>-->
353

    
354
      <p>Alternatively the <code>licenseFileLocation</code> configuration property can be used to
355
         provide the license location (see <a href="/configuration">Configuration</a> for more
356
         details about setting configuration features). For example, to provide the
357
            <code>licenseFileLocation</code> in PHP:</p>
358
      <samp><![CDATA[$saxonProc = new Saxon\SaxonProcessor(true);
359
$saxonProc->setConfigurationProperty("http://saxon.sf.net/feature/licenseFileLocation", "/usr/lib/saxon-license.lic");]]></samp>
360

    
361
      <h2 class="subtitle">Saxon-HE/C</h2>
362

    
363
      <p>Saxon-HE/C is an open-source product. The primary license is the <a target="_blank"
364
            href="https://www.mozilla.org/MPL/2.0/">Mozilla Public License version 2.0</a>. In most
365
         cases, the source files are marked as being "incompatible with secondary licenses", which
366
         means that the code cannot be combined with code issued under a GPL license (the reason for
367
         this is the difficulty of contacting all past contributors to gain their assent).</p>
368

    
369
      <p>Some components are licensed under the Apache version 2.0 license or under BSD-style
370
         licenses. For more information see the <a href="https://saxonica.com/license/license.xml"
371
            target="_blank">Licenses</a> section on the main Saxonica website.</p>
372

    
373
      <p>Although Saxon/C technically adheres to the definition of open source software, there are
374
         practical limitations. Specifically, the "Source Code Form" of the product, in the
375
         terminology of the MPL license, consists primarily of Java source code, and in order to
376
         build Saxon/C from the Java source code, you need access to the Excelsor JET development
377
         tools, which are no longer commercially available to new users.</p>
378

    
379

    
380
   </section>
381

    
382
   <section id="running" title="Running Saxon/C">
383
      <h1>Running Saxon/C</h1>
384

    
385
      <p>To check that Saxon/C is correctly installed (having followed the revelant instructions
386
         from <a href="../installing">Installing Saxon/C</a>, including getting the Saxon license
387
         location set up as required for Saxon-PE/C or Saxon-EE/C, as described in <a
388
            href="../licensing">Licensing</a>), you can try running some of the provided samples. </p>
389

    
390
      <p>For example, to run the C++ <code>testXPath</code> sample file on Linux or Mac OS use the
391
         following commands (where [PLATFORM] is linux or mac):</p>
392

    
393
      <kbd>cd samples/cppTests/</kbd>
394
      <kbd>./build64-[PLATFORM].sh</kbd>
395
      <kbd>./testXPath</kbd>
396

    
397
      <p>Similarly for Windows, use the commands:</p>
398

    
399
      <kbd>cd samples/cppTests/</kbd>
400
      <kbd>buildCPPSaxon[EDITION].bat</kbd>
401
      <kbd>testXPath.exe</kbd>
402

    
403
      <p>The <code>samples/cppTest</code> directory provides many more examples in C/C++ which can
404
         be run. For more information about these samples see <a href="/samples/samples_c"
405
            >Samples</a>.</p>
406

    
407

    
408
      <h2 class="subtitle">Using Saxon/C in applications</h2>
409

    
410
      <p>To get started please browse the <a href="/api">Saxon/C APIs</a>.
411
            <code>SaxonProcessor</code>, which acts as a factory class for generating the
412
         processors, is a good place to start.</p>
413

    
414
      <p>The <code>samples/cppTest</code> directory in the download provides example code in C/C++
415
         (and PHP and Python) which may also be helpful in learning how to use Saxon/C in your
416
         application. For further details see <a href="/samples/samples_c">Samples</a>.</p>
417

    
418
      <p>There are many parameters and options that can be set to control the way in which Saxon
419
         behaves. For more information about setting configuration features on
420
            <code>SaxonProcessor</code> and the other processors in Saxon/C, see <a
421
            href="/configuration">Configuration</a>.</p>
422

    
423
      <h2 class="subtitle">Command Line Interface</h2>
424

    
425
      <p>Saxon/C can be run from the command line in a similar way to its Java counterpart. See the
426
            <code>Transform.c</code> and <code>Query.c</code> files (and <code>Validate.c</code> for
427
         Saxon-EE/C) in the <code>command</code> directory. The <code>build.sh</code> script can be
428
         executed to build the command line programs.</p>
429

    
430
      <p>To run Saxon/C from the command line, the commands look like the following:</p>
431

    
432
      <kbd>./transform [options] [params]</kbd>
433
      <kbd>./query [options] [params]</kbd>
434
      <kbd>./validate [options] source.xml</kbd>
435

    
436
      <p>The same command line options as in the Java products are available in the Saxon/C command
437
         line tool. Please see the relevant sections of the Saxon 9.9 documentation for details:</p>
438

    
439
      <ul>
440
         <li>
441
            <a target="_blank"
442
               href="https://saxonica.com/documentation/index.html#!using-xsl/commandline">Running
443
               XSLT from the Command Line</a>
444
         </li>
445
         <li>
446
            <a target="_blank"
447
               href="https://saxonica.com/documentation/index.html#!using-xquery/commandline"
448
               >Running XQuery from the Command Line</a>
449
         </li>
450
         <li>
451
            <a target="_blank"
452
               href="https://saxonica.com/documentation/index.html#!schema-processing/commandline"
453
               >Running Validation from the Command Line</a>
454
         </li>
455
      </ul>
456

    
457

    
458

    
459
   </section>
460

    
461

    
462
   <section id="installingphp" title="PHP Extension">
463
      <h1>PHP Extension</h1>
464

    
465
      <p>The PHP extension is an interface module that allows Saxon/C to be invoked from PHP
466
         applications.</p>
467

    
468
      <h2 class="subtitle">Prerequisites</h2>
469

    
470
      <p>Please have the following packages on your machine to build Saxon/C for the PHP language:
471
            <code>make</code>, <code>php-devel</code>, (<code>php7.2-dev</code>),
472
            <code>apache2</code> or <code>httpd</code>, <code>gcc-c++</code> or <code>g++</code>,
473
            <code>gcj-jdk</code> (or just link the <code>jni.h</code> file in the
474
            <code>Saxon.C.API</code> directory).</p>
475

    
476
      <p>Saxon/C should already have been installed following the instructions at <a
477
            href="../installing">Installing Saxon/C</a>.</p>
478

    
479
      <h2 class="subtitle">Installing on Linux and Mac OS</h2>
480

    
481
      <!--<p>(Alternatively, you may like to use the installation script <a 
482
         href="https://saxonica.com/saxon-c/download/install.sh">install.sh</a> supplied by
483
         Petr Zak - written for a 64-bit machine, but can be changed for a 32-bit machine.)</p>-->
484

    
485
      <h3>Building with PHP7</h3>
486

    
487
      <p>The PHP extension is in the form of a C/C++ PHP7 extension to Saxon/C created using the
488
         Zend module API.</p>
489

    
490
      <p>To install, run the following commands:</p>
491

    
492
      <kbd>cd /usr/lib/Saxonica/Saxon-[EDITION]C[VERSION]/Saxon-C-API/</kbd>
493
      <kbd>phpize</kbd>
494
      <kbd>./configure --enable-saxon</kbd>
495
      <kbd>make</kbd>
496
      <kbd>sudo make install</kbd>
497

    
498
      <h3>Building with PHP5</h3>
499

    
500
      <p>The Saxon/C PHP extension is built for PHP7. To instead build with PHP5, first replace the
501
            <code>config.m4</code> file in the <code>Saxon-C-API/</code> directory with the one held
502
         in <code>Saxon-C-API/PHP5-Build</code>. Then run the installation steps above.</p>
503

    
504
      <p>Next create a module conf file: </p>
505

    
506
      <kbd>nano /etc/php/7.2/mods-available/20-saxon.ini</kbd>
507

    
508
      <p>with content:</p>
509

    
510
      <samp><![CDATA[; configuration for php Saxon HE/PE/EE module
511
         extension=saxon.so]]></samp>
512

    
513
      <p>and save the file. Now enable the module for PHP using the command:</p>
514

    
515
      <kbd>phpenmod saxon</kbd>
516

    
517
      <p>Alternatively, you can update the <code>php.ini</code> file or add the
518
            <code>20-saxon.ini</code> file under the <code>conf.d</code> directory (if using Ubuntu
519
         it is usually in the location <code>/etc/php/7.2/apache2/</code>) to contain the PHP
520
         extension. Insert the code <code>extension=saxon.so</code> in the Dynamic Extensions
521
         section, then run the following commands:</p>
522

    
523
      <kbd>sudo service apache2 restart</kbd>
524
      <kbd>php -m | grep saxon -i</kbd>
525

    
526
      <p>(Running these should display 'Saxon/C'.)</p>
527

    
528
      <p>If you cannot load the extension from the <code>php.ini</code> file, you need to load it at
529
         script execution time using the code: <code>dl(“saxon.so”);</code>. However this is not
530
         recommended as the loading and unloading can be slow.</p>
531

    
532
      <p>When working with PHP, the environment variables <code>LD_LIBRARY_PATH</code> and
533
            <code>SAXONC_HOME</code> should be added to the apache environment variables. The
534
         apache2 config file is located in one of the following locations depending on your linux
535
         distribution: </p>
536
      <ul>
537
         <li>Ubuntu server: <code>/etc/apache2/envvars</code></li>
538
         <li>Centos server: <code>/etc/sysconfig/httpd</code></li>
539
         <li>SUSE server: <code>/etc/sysconfig/apache2</code></li>
540
      </ul>
541

    
542
      <h2 class="subtitle">Installing on Windows</h2>
543

    
544
      <p>The PHP extension has not yet been built. It can be built using the PHP source. We hope to
545
         provide builds for PHP on Windows soon.</p>
546

    
547
      <p>On Windows we recommend setting the current working directory using the single-argument
548
         version of the <code>SaxonProcessor</code> constructor, because there remains an issue with
549
         building Saxon/C with PHP when using the function<code> VCWD_GETCWD</code>. That is,</p>
550

    
551
      <samp><![CDATA[$proc = new SaxonProcessor('C://www/html//trax//');]]></samp>
552

    
553
      <p>should replace instances of</p>
554

    
555
      <samp><![CDATA[$proc = new SaxonProcessor();]]></samp>
556

    
557
      <p>in your PHP scripts (see the <a href="/samples/samples_php">PHP Samples</a> for an
558
         example). </p>
559
   </section>
560

    
561
   <section id="installingpython" title="Python Extension">
562
      <h1>Python Extension</h1>
563

    
564
      <p>The Python extension is an interface module that allows Saxon/C to be invoked from Python
565
         applications.</p>
566

    
567
      <h2 class="subtitle">Prerequisites</h2>
568

    
569
      <p>Please have the following packages on your machine to build Saxon/C for the Python
570
         language: <code>Python3</code> (64-bit) and <code>Cython</code>.</p>
571

    
572
      <p>The Saxon/C Python extension API has been developed using Cython for Python3. Cython is
573
         required to build the extension library. To install Python and Cython on Mac OS, we
574
         recommend using brew or MacPorts.</p>
575

    
576
      <p>Saxon/C should already have been installed following the instructions at <a
577
            href="../installing">Installing Saxon/C</a>.</p>
578

    
579
      <h2 class="subtitle">Installing</h2>
580

    
581
      <p>The Python extension is held in the directory <code>Saxon.C.API/python-saxon</code>. </p>
582

    
583
      <h3>Linux and Mac OS Platforms</h3>
584
      <p>The Python extension on the Linux and Mac OS platforms can be built using the following
585
         command:</p>
586

    
587
      <kbd>python3 saxon-setup.py build_ext -if</kbd>
588

    
589
      <h3>Windows Platform</h3>
590

    
591
      <p>The Python extension on the Windows platform can be built using the following instructions:</p>
592
       <p>Install Python 3.X (64-bit) with VS 2017 or 2019 which can then be run
593
          with command "py" from Powershell.</p>
594

    
595

    
596
      <ul><li>For Python: update pip</li>
597
         <li>Use pip to install Cython: pip install Cython</li>
598
       <li>open Powershell for Python 3.X (with administrator rights if you
599
          installed in C:\Program Files)</li>
600
      </ul>
601
      <kbd>cd C:\Program Files\Saxonica\SaxonEDITIONX.X.X</kbd>
602
      <kbd>cd Saxon.C.API\python-saxon</kbd>
603
      <kbd>py saxon-setup.py build_ext -if</kbd>
604
       <p>For arbitrary Powershell Windows need to set: $Env:PYTHONPATH +=
605
       ";C:\Program Files\Saxonica\SaxonEDITIONX.X.X\Saxon.C.API\python-saxon" to
606
       ensure that "import saxonc" in any Python program finds the saxonc module</p>
607

    
608
   </section>
609

    
610
   <section id="troubleshooting" title="Troubleshooting">
611
      <h1>Troubleshooting</h1>
612

    
613
      <p>After installing Saxon/C, if you notice anomalies in execution, then the apache log file
614
         usually has useful information on errors reported and crashes. See below for a description
615
         of some of the common errors and crashes, and their solutions:</p>
616
      <ol>
617
         <li>
618
            <p>
619
               <code>FATAL ERROR: Unable to load /usr/lib64/rt/lib/amd64/libjava.so (libjvm.so
620
                  cannot open shared object file: No such file or directory) JNI_CreateJavaVM()
621
                  failed with result-1</code>
622
            </p>
623
            <p><b>Solution:</b> Running the following command should resolve the error:</p>
624
            <kbd>sudo ldconfig</kbd>
625
            <p>Ignore the message 'file /lib/libsaxon[EDITION].so is truncated'. The library was created using
626
            Excelsior JET.</p>
627
            <p>Alternatively create a symlink to the java virtual machine. This is not required to
628
               install or compile, but it is required for PHP code. The following command should
629
               resolve the issue on a 64-bit machine:</p>
630
            <kbd>ln -s $JAVA_HOME/jre/lib/amd64/server/libjvm.so /lib64/libjvm.so<br/></kbd>
631
            <p>Alternatively, it is possible to link the libjvm.so from the 'rt/lib/jetjvm'
632
               directory.</p>
633
         </li>
634
         <li>
635
            <p>
636
               <code>/usr/lib/Saxon-C-API/SaxonProcessor.h:3:17: fatal error: jni.h: No such file or
637
                  directory <br/>#include &lt;jni.h&gt; compilation terminated.</code>
638
            </p>
639
            <p><b>Solution:</b> Link the <code>jni.h</code> on the machine or simply install
640
                  <code>gcj-jdk</code> which should resolve this error. </p>
641
         </li>
642
         <li>
643
            <p>
644
               <code>PHP Warning: PHP Startup: Unable to load dynamic library
645
                  '/usr/lib/php/modules/saxon.so' - libsaxonhec.so: cannot enable executable stack
646
                  as shared object requires: Permission denied in Unknown on line 0</code>
647
            </p>
648
            <p>This has been observed on centos systems when SELinux is enforced/enabled.</p>
649
            <p><b>Solution:</b> Run the following command to show the security setting for the library files:</p>
650
            <kbd>ls -alZ /usr/lib" and 'ls -alZ /usr/lib/php/module/</kbd>
651
            <p>Then run the following commands or similar to change the security context:</p>
652
            <kbd>chcon system_u:object_r:lib_t:s0 /usr/lib/libsaxonhec.so</kbd>
653
            <kbd>chcon system_u:object_r:lib_t:s0 /usr/lib/php/modules/saxon.so</kbd>
654
         </li>
655
         <li>
656
            <p>Some 64-bit Linux flavors do not run the 32-bit JET libraries by default.</p>
657
            <p><b>Solution:</b> For instance, <code>ia32-libs</code> must be installed on
658
               Ubuntu/Debian, e.g. using the following command:<br/>
659
            </p>
660
            <kbd>sudo apt-get install ia32-libs</kbd>
661
         </li>
662
         <li>
663
            <p><code>Unable to load C:\Program Files\Saxonica\SaxonHEC1.2.1\libsaxonhec.dll Error: : No error</code></p>
664
            <p>Caused by attempting to run Saxon/C in 32-bit environments, including 32-bit Python
665
               and PHP builds. Saxon/C can only run with 64-bit builds.</p>
666
            <p><b>Solution:</b> 
667
            The machine operating system must be 64-bit, and Python and PHP builds must be 64-bit to run with Saxon/C.</p>
668
         </li>
669
      </ol>
670

    
671

    
672
   </section>
673

    
674

    
675
</article>
(9-9/10)