1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
|
<html>
<head>
<title>KInterbasDB Installation Guide - Source Distribution</title>
<link rel="stylesheet" href="global.css" type="text/css">
</head>
<body>
<a href="index.html">Table of Contents</a>
<hr>
<h1 class="compactHeading">KInterbasDB Installation Guide - Source Distribution</h1>
<p style="font-style: italic; font-size: 85%;">
<span style="font-weight: bold;">Note:</span>
You might prefer to
<a href="installation-binary.html">install a pre-compiled binary distribution</a>
of KInterbasDB if one is available for your platform.
</p>
<h3>Steps:</h3>
<table border="0" style="margin-bottom: 20px; width: 100%;">
<tr>
<td style="vertical-align: top;">
<ol>
<li><a href="#step_dependencies">Satisfy the Dependencies</a></li>
<li><a href="#step_compile">Compile KInterbasDB</a></li>
<li><a href="#step_install">Install KInterbasDB</a></li>
<li><a href="#step_test">Test Your KInterbasDB Installation</a></li>
</ol>
</td>
<td width="50">
</td>
<td style="vertical-align: top;">
<table border="1" style="font-size: 90%;">
<thead style="background-color: #eeeeee; font-size: 110%; font-weight: bold;">
<td>
Shortcut for the Experienced and Impatient:
</td>
</thead>
<tr>
<td>
(decompress KInterbasDB into <code><em>temp_dir</em></code>)<br>
<code>cd <em>temp_dir</em></code><br>
<code>python setup.py build</code><br>
<code>python setup.py install</code><br>
<code>python -c "import kinterbasdb"</code><br>
(delete <code><em>temp_dir</em></code>)<br>
</td>
</tr>
<tr>
<td style="font-size: 85%;">
Then hit the <a href="usage.html">Usage Guide</a>.
</td>
</tr>
</table>
</td>
</tr>
</table>
<hr>
<a name="step_dependencies"><h2>Step 1: Satisfy the Dependencies</h2></a>
<p>
KInterbasDB requires a valid combination of the dependencies in the
<a href="#dependency_list">list</a>
below.
</p>
<p>
Detailed instructions on how to install each dependency are beyond the scope
of this document; consult the dependency distributor for installation
instructions.
</p>
<p>
<strong>Satisfying the dependencies is not difficult</strong>!
For mainstream operating systems--including Windows and Linux--easily
installable binary distributions are available for
<em>all</em> of KInterbasDB's dependencies (see the download links below).
</p>
<a name="dependency_list"><h4>Dependencies:</h4></a>
<ol class="compactList" type="a">
<li>
Operating System and C Compiler - one of:<br>
<ul class="compactList">
<li>Win32 and a C compiler (
If compiling against Firebird 1.5,
MinGW
[<a href="http://sourceforge.net/project/showfiles.php?group_id=2435">download here</a>]
or Microsoft Visual C++
[<a href="http://msdn.microsoft.com/visualc/howtobuy/default.asp">buy here</a>];
if compiling against Firebird 1.0 or Interbase®,
Microsoft Visual C++
or Borland C++ Compiler 5.5
[<a href="http://www.borland.com/bcppbuilder/freecompiler/">download here</a>].
)
</li>
<li>Linux and GCC</li>
<li>Other POSIX-compliant operating system and a C compiler</li>
</ul>
</li>
<li>
Database - one of:<br>
<ul class="compactList">
<li><a href="http://firebirdsql.org">Firebird<a/> 1.0 or later
- client or server installation
[<a href="http://sourceforge.net/project/showfiles.php?group_id=9028">download here</a>]
</li>
<li><a href="http://www.interbase.com">Interbase®</a> 5.5 through 6.x
- client or server installation
[<a href="http://www.borland.com/devsupport/interbase/opensource/">download here</a>]
</li>
<li>(?) Interbase® >= 7.x</li>
</ul>
</li>
<li><a href="http://www.python.org">Python</a>
[<a href="http://www.python.org/download/">download here</a>]
2.1 or later
<br><br>
</li>
<li>
<a href="http://www.lemburg.com/files/python/eGenix-mx-Extensions.html">eGenix.com mx Extensions for Python</a>,
version 2.0.1 or later
[<a href="http://www.lemburg.com/files/python/eGenix-mx-Extensions.html#Download-mxBASE">download here</a>]
<br>
<p class="textParagraph">
By default, KInterbasDB uses the <code>DateTime</code> module of the
eGenix.com <code>mx</code> Extensions to represent date and time values,
as <a href="Python-DB-API-2.0.html#hints">recommended</a> by the
Python DB API Specification.
</p>
<p class="textParagraph">
However, it is not strictly necessary to use the <code>mx.DateTime</code>
module to handle dates and times.
Instructions for substituting alternatives (such as the
<code>datetime</code> module that entered the standard library with
Python 2.3) can be found
<a href="usage.html#adv_param_conv_dynamic_type_translation">here</a>
and
<a href="usage.html#adv_param_conv_dynamic_type_translation_deferred_loading">here</a>.
</p>
</li>
</ol>
<!-- END COMMON SATISFY_DEPENDENCIES SECTION -->
<hr>
<a name="step_compile"><h2>Step 2: Compile KInterbasDB</h2></a>
<p>
Once you have successfully installed the dependencies, you may proceed with
the installation of KInterbasDB itself.
</p>
<p>
Beginning with version 3.0, KInterbasDB has full support for the
<a href="http://www.python.org/sigs/distutils-sig/"><code>distutils</code></a>,
the standard facility for Python package distribution and installation.
Full instructions for using the distutils are available
<a href="http://www.python.org/doc/current/inst/inst.html">here</a>,
but you can skip them unless you have an otherwise insoluble problem.
</p>
<p>
Open a command prompt, change to the directory where you decompressed the
kinterbasdb source distribution, and type:
<br>
<code>python setup.py build</code>
</p>
<p>
The installation script, <code>setup.py</code>, will attempt to
automatically detect the information
needed by the C compiler; then it will invoke the distutils to perform the
actual compilation. If you installed automatic distributions of the
dependencies that place themselves in standard locations (on UNIX-style
operating systems)
or record their locations in the system registry (on Windows),
the compilation should proceed without incident.
</p>
<p>
On Windows, compilers other than Microsoft Visual C++ usually require some
library conversion to work with Python or Firebird.
With Firebird 1.5 and MinGW or Firebird 1.0 and Borland C++,
<code>setup.py</code> will perform this conversion automatically. If the
automatic conversion fails, ensure that your compiler is installed properly
(especially that its <code>bin</code> directory is in your <code>PATH</code>).
For more information, see the
<a href="#compiler_specific_compilation_notes">compiler-specific notes</a>
in this document, as well as the
<a href="http://python.org/doc/current/inst/tweak-flags.html#SECTION000622000000000000000">Section 6.2.2</a>
of the Python standard library documentation on "Installing Python Modules".
</p>
<p>
If <code>setup.py</code> raises no errors and its output concludes with
something like "<code>Creating library...</code>", then you are
ready to proceed to the <a href="#step_install">next step</a>.
</p>
<p>
If you receive an error message, examine its contents and then consult
the following table:
</p>
<table border="1" style="margin-bottom: 20px;">
<thead style="background-color: #eeeeee; font-weight: bold;">
<td>
Error Message Header
</td>
<td>
Explanation
</td>
</thead>
<tr style="vertical-align: top;">
<td>
LIBRARY AUTODETECTION ERROR
</td>
<td>
<p>
The setup script was unable to automatically find one or more
files needed for the compilation process, such as a library needed
by the C compiler.
</p>
<p>
Using a text editor, you will need to manually specify the relevant
paths in the
<code>manual_config</code>
section of the setup configuration file,
<code>setup.cfg</code>
(in the root directory of the KInterbasDB source distribution).
Uncomment the item in question and provide a value appropriate to
your system.
Save the newly modified <code>setup.cfg</code>,
then repeat <a href="#step_compile">the compilation step</a>.
</p>
<p>
If manually specifying the library paths fails to solve the
problem:<br>
- Your C compiler or linker may not be properly configured.
<br>
- You may have a corrupt or incomplete installation
of one or more KInterbasDB dependencies.
</p>
<hr style="margin-bottom: 0px;">
<p style="margin-top: 0px;">
<em>Linux-specific note:</em><br>
It has been pointed out that the RPM distribution of the
eGenix.com mx Extensions for Python installs into
<code><strong>/usr/<em>local</em>/lib</strong>/python<em>x</em>.<em>y</em>/site-packages</code>, whereas
binary distributions of Python are often installed in
<code><strong>/usr/lib</strong>/python<em>x</em>.<em>y</em></code>
</p>
<p>
If you are attempting to use the RPM distribution of the eGenix
package and kinterbasdb's setup script (as well as Python in
general) cannot find it, you may need to move the eGenix package
from
<code>/usr/local/lib/python<em>x</em>.<em>y</em>/site-packages</code> to
<code>/usr/lib/python<em>x</em>.<em>y</em>/site-packages</code>
</p>
<p>
This problem has only been reported on Mandrake Linux, but probably
affects other RPM-based distributions also. It should be noted that
the eGenix package itself has very good <code>distutils</code>
support, so using a binary distribution is of dubious advantage in
the first place.
</p>
</td>
</tr>
<tr style="vertical-align: top;">
<td>
COMPILER CONFIGURATION ERROR
</td>
<td>
<p>
The setup script could not function because of the current
configuration of your compiler. The error message should
provide details about what went wrong, and perhaps a suggestion
of how to fix the problem.
</p>
<p>
If you are not using the standard compiler for your platform,
consult the
<a href="#compiler_specific_compilation_notes">compiler-specific
notes</a>.
</p>
</td>
</tr>
<tr style="vertical-align: top;">
<td>
LIBRARY CONVERSION ERROR
</td>
<td>
<p>
The setup script's attempt to convert libraries intended for use
with Microsoft Visual C++ into a format compatible with your
compiler was not successful.
</p>
<p>
Consult the
<a href="#compiler_specific_compilation_notes">compiler-specific notes</a>
in this document, as well as
<a href="http://python.org/doc/current/inst/tweak-flags.html#SECTION000622000000000000000">Section 6.2.2</a>
of the Python standard library documentation on
"Installing Python Modules".
</p>
</td>
</tr>
<tr style="vertical-align: top;">
<td>
PYTHON SYSTEM ERROR
</td>
<td>
<p>
Your Python installation is outdated, lacks some crucial modules,
or is otherwise inadequate.
The error message will indicate what your options are, which
may include installing a more recent Python version, compiling
additional C extension modules for your current Python version,
or editing <code>setup.cfg</code> to manually specify library
paths, thus relieving <code>setup.py</code> of the burden of
detecting them.
</p>
</td>
</tr>
<tr style="vertical-align: top;">
<td>
KINTERBASDB DISTRIBUTION ERROR
</td>
<td>
<p>
The setup script cannot find a file that was supposed to be
included with the KInterbasDB source distribution. Try
downloading the KInterbasDB source distribution again and
decompressing it into a fresh temporary directory, then
repeat <a href="#step_compile">the compilation step</a>.
</p>
</td>
</tr>
<tr style="vertical-align: top;">
<td>
LIBRARY MANUAL SPECIFICATION ERROR
</td>
<td>
<p>
One of the library paths specified in <code>setup.cfg</code> is
not valid. Verify the location of the library, then edit
<code>setup.cfg</code> to reflect the correct path.
</p>
<p>
If you had no particular reason to manually specify the library
path in the first place, try commenting out that entry
in <code>setup.cfg</code>,
then repeat <a href="#step_compile">the compilation step</a>
and let the setup script attempt to automatically detect the
location of the library.
</p>
</td>
</tr>
</table>
<p>
If the problem persists after you have followed the advice in the error
message itself and in the table above, visit the
<a href="http://sourceforge.net/forum/forum.php?forum_id=30917">KInterbasDB Forum</a>
and report your problem.
</p>
<a name="compiler_specific_compilation_notes"><h4>Compiler-Specific
Notes</h4></a>
<ul> <!-- platforms -->
<li><!-- Windows platform -->
Microsoft Windows
<ul>
<li>Microsoft Visual C++ 6.0
<ol style="margin-bottom: 25px;">
<li>
The Visual C++ command-line utilities must be available on your
system path, and their required environment variables must be
initialized to meaningful values.
If, when you installed Visual C++, you did <em>not</em> allow
it to register the paths needed for command-line compilation, you
will need to run the <code>vcvars32.bat</code> batch file from
the <code>bin</code> subdirectory of your Visual C++
installation.<br>
By default, this directory is
<code>C:\Program Files\Microsoft Visual Studio\VC98\bin</code>
</li>
<li>
Use the <em><strong>same</strong></em> command prompt window to
run the following command in the temporary directory into which
you decompressed KInterbasDB:<br>
<code>python setup.py build</code>
</li>
</ol>
</li>
<li>Borland C++ Compiler 5.5 (free version for Win32)
<p>In order to compile KInterbasDB automatically with the Borland
compiler,
you must use version 1.0.2 or later of the Python <code>distutils</code>.
Python 2.2 includes the required version. If you <em>must</em> use a
version of Python before 2.2, you
can
<a href="http://www.python.org/sigs/distutils-sig/download.html">update</a>
the <code>distutils</code> package independently of your Python
version, or just compile manually.
</p>
<p>
Note that KInterbasDB supports the Borland C++ Compiler only with
Firebird 1.0 and Interbase®, not Firebird 1.5 or later. With Firebird 1.5
or later, use either the free MinGW (documented in the next section)
or Microsoft Visual C++.
</p>
<ol style="margin-bottom: 25px;">
<li>Make sure that the <code>bin</code> subdirectory of the directory
where you installed the Borland compiler is in your PATH.<br>
By default, this directory is <code>C:\Borland\bcc55\bin</code>,
so you could execute the command:<br>
<code>SET PATH=%PATH%;C:\Borland\bcc55\bin</code><br>
to add the compiler's bin directory to your path.
</li>
<li>In the temporary directory into which you decompressed KInterbasDB,
run the command:<br>
<code>python setup.py build --compiler=bcpp</code>
</li>
</ol>
</li>
<li><a href="http://mingw.org">MinGW</a> (Windows port of GCC)
<p>
Note that KInterbasDB supports MinGW only with Firebird 1.5 or later,
not Firebird 1.0 or Interbase®. With earlier versions of the database,
use either the free Borland C++ Compiler (documented in the previous
section)
or Microsoft Visual C++.
</p>
<ol style="margin-bottom: 25px;">
<li>
Make sure that the <code>bin</code> subdirectory of the directory
where you installed MinGW is in your PATH.
<br>
KInterbasDB requires
numerous MinGW sub-packages, so it's easiest to install the
monolithic distribution of MinGW, rather than piecing together
individual sub-packages. The monolithic distribution is an
executable installer; installation is trivial.
<br>
KInterbasDB's setup script will automatically perform all of the
required preparatory steps for compiling an extension with MinGW
on your Python installation.
</li>
<li>In the temporary directory into which you decompressed KInterbasDB,
run the command:<br>
<code>python setup.py build --compiler=mingw32</code>
</li>
</ol>
</li>
</ul>
</li> <!-- end Windows platform -->
</ul> <!-- end platforms -->
<hr>
<a name="step_install"><h2>Step 3: Install KInterbasDB</h2></a>
<p>
During this step, the setup script moves the KInterbasDB package (including
the newly compiled C extensions) to the standard package directory
of your Python installation so that Python will be able to
<code>import kinterbasdb</code> and <code>import kinterbasdb.services</code>
</p>
<p>
In addition to the Python code and shared library files actually used by the
Python interpreter, the setup script typically installs some supporting
files, such as documentation. Depending on your system configuration, these
supporting files may be placed in the same directory or a different directory
from the files used by the Python interpreter.
</p>
<p>
Run the following command:<br>
<code>python setup.py install</code>
</p>
<p>
The setup script will install KInterbasDB, listing each file it installs.
</p>
<p>
Errors during this step are rare because compilation
(the finicky part of this process) has already taken place; installation
is really just a matter of copying files. However, there will be file
system permission errors if the Python installation directory is not
writable by the user running the setup script. If you encounter such an
error, try one of the following:<br>
- Log in as a user who has the required file system permissions and repeat
<a href="#step_install">the installation step</a>.<br>
- Manually copy the directory
<code>build/lib.<em>platform</em>-<em>pyver</em>/kinterbasdb</code>
(which contains the Python modules and compiled library files created
during the compilation step) to a directory in your PYTHONPATH. This
approach will not install the supporting files, but they are for the benefit
of the programmer rather than the Python interpreter anyway.
</p>
<hr>
<a name="step_test"><h2>Step 4: Test Your KInterbasDB Installation</h2></a>
<p>
<span class="XXX_ADDRESS_THIS">XXX</span>
A substantial portion of a kinterbasdb test suite has been written; it will
be published with kinterbasdb-3.1 final.
</p>
<p>
In the meantime, switch to a directory
<em>other than the temporary directory into which you decompressed the
source distribution</em> (to avoid conflict between the copy of kinterbasdb
in that directory and the copy placed under the standard Python
<code>site-packages</code> directory), then verify the importability of your
KInterbasDB installation by issuing the following command:<br>
<code>python -c "import kinterbasdb"</code><br>
</p>
<p>
If the import attempt does not encounter any errors, you are finished.
Next, consider reading the <a href="usage.html">KInterbasDB Usage Guide</a>.
</p>
<p>
You should not encounter any errors at this stage since you have
already completed the compilation and installation steps successfully.
If you do, please report them to the
<a href="http://sourceforge.net/forum/forum.php?forum_id=30917">KInterbasDB Forum</a>.
</p>
<hr>
<a href="index.html">Table of Contents</a>
</body>
</html>
|
