ViewVC Help
View File | Revision Log | Show Annotations | Download File | View Changeset | Root Listing
root/public/ibx/trunk/doc/readme.linux.xhtml
Revision: 43
Committed: Thu Sep 22 17:10:15 2016 UTC (8 years, 2 months ago) by tony
Content type: application/xhtml+xml
File size: 22317 byte(s)
Log Message: 
Committing updates for Release R1-4-3

File Contents

# User Rev Content
1 tony 21 <?xml version="1.0" encoding="UTF-8"?>
2 tony 37 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><!--This file was converted to xhtml by LibreOffice - see http://cgit.freedesktop.org/libreoffice/core/tree/filter/source/xslt for the code.--><head profile="http://dublincore.org/documents/dcmi-terms/"><meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8"/><title xml:lang="en-US">- no title specified</title><meta name="DCTERMS.title" content="" xml:lang="en-US"/><meta name="DCTERMS.language" content="en-US" scheme="DCTERMS.RFC4646"/><meta name="DCTERMS.source" content="http://xml.openoffice.org/odf2xhtml"/><meta name="DCTERMS.creator" content="Tony Whyman"/><meta name="DCTERMS.issued" content="2011-04-30T15:39:15" scheme="DCTERMS.W3CDTF"/><meta name="DCTERMS.contributor" content="Tony Whyman"/><meta name="DCTERMS.modified" content="2016-02-12T13:48:46.625304983" scheme="DCTERMS.W3CDTF"/><meta name="DCTERMS.provenance" content="" xml:lang="en-US"/><meta name="DCTERMS.subject" content="," xml:lang="en-US"/><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" hreflang="en"/><link rel="schema.DCTERMS" href="http://purl.org/dc/terms/" hreflang="en"/><link rel="schema.DCTYPE" href="http://purl.org/dc/dcmitype/" hreflang="en"/><link rel="schema.DCAM" href="http://purl.org/dc/dcam/" hreflang="en"/><style type="text/css">
3 tony 21 @page { }
4     table { border-collapse:collapse; border-spacing:0; empty-cells:show }
5     td, th { vertical-align:top; font-size:12pt;}
6     h1, h2, h3, h4, h5, h6 { clear:both }
7     ol, ul { margin:0; padding:0;}
8     li { list-style: none; margin:0; padding:0;}
9     <!-- "li span.odfLiEnd" - IE 7 issue-->
10     li span. { clear: both; line-height:0; width:0; height:0; margin:0; padding:0; }
11     span.footnodeNumber { padding-right:1em; }
12     span.annotation_style_by_filter { font-size:95%; font-family:Arial; background-color:#fff000; margin:0; border:0; padding:0; }
13     * { margin:0;}
14     .Heading_20_1 { font-size:115%; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; font-weight:bold; }
15     .Heading_20_2 { font-size:14pt; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; font-style:italic; font-weight:bold; }
16     .P1 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; }
17 tony 37 .P10 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0.5in; margin-right:0in; text-indent:0in; font-style:normal; }
18     .P11 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; margin-left:0in; margin-right:0in; text-indent:0in; font-style:normal; }
19     .P12 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Courier New; writing-mode:page; margin-left:0in; margin-right:0in; text-indent:0in; font-style:normal; }
20     .P13 { font-size:10pt; margin-bottom:0.1965in; margin-top:0in; font-family:Liberation Mono; writing-mode:page; margin-left:0.3126in; margin-right:0in; text-indent:0in; }
21 tony 43 .P14 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
22 tony 35 .P15 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
23 tony 43 .P16 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
24     .P17 { font-size:14pt; font-style:normal; font-weight:bold; margin-bottom:0.0835in; margin-top:0.1665in; font-family:Arial; writing-mode:page; }
25 tony 37 .P18 { font-size:12pt; font-family:Times New Roman; writing-mode:page; }
26 tony 21 .P2 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
27 tony 27 .P3 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
28     .P4 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
29     .P5 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
30     .P6 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
31     .P7 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
32 tony 37 .P8 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; font-style:normal; }
33     .P9 { font-size:12pt; margin-bottom:0.0835in; margin-top:0in; font-family:Times New Roman; writing-mode:page; }
34 tony 21 .Standard { font-size:12pt; font-family:Times New Roman; writing-mode:page; }
35     .Text_20_body { font-size:12pt; font-family:Times New Roman; writing-mode:page; margin-top:0in; margin-bottom:0.0835in; }
36     .Table1 { float:none; }
37     .Table1_A1 { padding:0.0382in; border-style:none; }
38     .Internet_20_link { color:#000080; text-decoration:underline; }
39     .T1 { font-style:italic; }
40     .T2 { font-style:normal; }
41 tony 27 .T3 { font-style:normal; }
42 tony 21 <!-- ODF styles with no properties representable as CSS -->
43 tony 27 .Table1.A .Table1.B .Numbering_20_Symbols .T4 .T5 { }
44 tony 43 </style></head><body dir="ltr" style="max-width:8.2681in;margin-top:0.7874in; margin-bottom:0.7874in; margin-left:0.7874in; margin-right:0.7874in; writing-mode:lr-tb; "><h1 class="Heading_20_1"><a id="a__Using_Firebird_with_IBX_under_Linux"><span/></a>Using Firebird with IBX under Linux</h1><p class="Text_20_body">Firebird for Linux is distributed by <a href="http://www.firebirdsql.org/" class="Internet_20_link">http://www.firebirdsql.org</a> as a tar archive that including installation script, or as an rpm. Linux Distributions such as Ubuntu, also distribute Firebird as deb packages that are downloaded and installed from their own repositories.</p><p class="Text_20_body">Prior to installing IBX in the Lazarus IDE, you should install Firebird either using the standard tar archive or rpm or (for example under Ubuntu)  by using the Debian Package manager to install the Firebird client and server. There are two Firebird architectures – Superserver and Classic. If in doubt, install the Super Server.</p><p class="Text_20_body">For example, to install Firebird under Ubuntu 10.4, enter at the command line:</p><p class="P1">sudo apt-get install firebird2.1-super</p><p class="Text_20_body">By default, IBX for Lazarus will dynamically load the Firebird 2.x client library. This is regardless of whether it is being run as part of the IDE or in a user program. Provided that this is installed then IBX for Lazarus should run “out of the box”. If IBX cannot find the client library then the IDE will have empty or missing “Firebird” and “Firebird Admin” tabs on the component palette. A user program will terminate with an error message.</p><h2 class="Heading_20_2"><a id="a__The_Example_Database"><span/></a>The Example Database</h2><p class="Text_20_body">In order to use the example application, you will also need to install the example “employee” database. This is installed by default when using the  <a href="http://www.firebirdsql.org/" class="Internet_20_link">http://www.firebirdsql.org</a> distribution. However, if installing from debian packages, you must also install the Firebird examples package (e.g. firebird2.1-examples), and then install the employee database in its correct location.</p><p class="Text_20_body">Enter the following at the command line to download and install the examples database:</p><p class="Text_20_body">for Firebird 2.1:</p><p class="P13">sudo apt-get install firebird2.1-examples</p><p class="P13">sudo gunzip /usr/share/doc/firebird2.1-examples/examples/empbuild/employee.fdb.gz</p><p class="P13">sudo chown firebird.firebird /usr/share/doc/firebird2.1-examples/examples/empbuild/employee.fdb</p><p class="P13">sudo chmod 660 /usr/share/doc/firebird2.1-examples/examples/empbuild/employee.fdb</p><p class="Text_20_body">For Firebird 2.5:</p><p class="P13">sudo apt-get install firebird2.5-examples</p><p class="P13">sudo gunzip /usr/share/doc/firebird2.5-common-doc/examples/empbuild/employee.fdb.gz</p><p class="P13">sudo chown firebird: /usr/share/doc/firebird2.5-common-doc/examples/empbuild/employee.fdb</p><p class="P13">sudo chmod 660 /usr/share/doc/firebird2.5-common-doc/examples/empbuild/employee.fdb</p><p class="Standard">The employee database should now be ready for use and accessible using the alias "employee".</p><p class="Text_20_body"> </p><h2 class="Heading_20_2"><a id="a__Distributing_the_Firebird_Client_Shared_Object_with_your_Applications"><span/></a>Distributing the Firebird Client Shared Object with your Applications</h2><p class="Text_20_body">If you are distributing your application using the Debian Package Manager, then all you need to do is to include “libfbclient2” in your list of package dependencies <span class="T4">(or libfbemded2.5/libfbembed2.1 if you are using the embedded Firebird Server)</span>. The Debian Package Manager will then ensure that the Firebird Client Shared Object is correctly installed.</p><p class="Text_20_body">Otherwise, you will either need to require your users to install the standard Firebird distribution, or package and install the firebird client shared object and support files with your application. As the location of these files will depend on how they were built, if you intend to package the Firebird files with your application, then you need to consult the release notes provided with the original source of these files for instructions on how and where to install them.</p><h2 class="P17"><a id="a__Using_a_Personal_Database"><span/></a>Using a Personal Database</h2><p class="P4">Whilst client/server use of Firebird is typical and allows multi-user access to a shared database, it is also possible to use the Firebird classic library to support the use of a Personal Database, where the database is in a file owned by the user account, is accessible by a single user only and without needing to manage user passwords. </p><p class="P7">From IBX 1.4.0 onwards, the TIBLocalDBSupport component provides simplified management of Personal Databases.</p><p class="P6">In practice and for a Debian derived system, it should be sufficient to install the libfbembed2.5 package and to ensure that neither the “user_name” nor the “ password” parameters are set in the IBDatabase object. You should then be able to open any firebird database to which your program has read/write unix permissions <span class="T5">without needing a Firebird Server to be running.</span></p><p class="P3">On a Redhat/Fedora/Centos system then the firebird-libfbembed should be installed instead.</p><p class="P8">Note: when using the libfbembed.so, if you prefix the database name (In TIBDatabase) with "localhost:" then it will still attempt to access the database via the Firebird Server and will require a username and password. If only the pathname is given, then the username and password should be omitted and the unix file permissions are used to grant access.</p><p class="P7">On the other hand, if Firebird Embedded Server shared object is loaded and a local database path is given and database attach fails due to access permission issues on the temp directory or security database, then the attach is retried with "localhost:" prefixing the databasename. This should avoid problems when the database has to be accessed by a local (e.g. classic) server and libfbembed is used.</p><p class="P5"><span class="T5">You can also use the Firebird distribution package from the Firebird Project</span> – but <span class="T5">this </span>does require more careful configuration. It is best described by an example:</p><table border="0" cellspacing="0" cellpadding="0" class="Table1"><colgroup><col/><col/></colgroup><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P18" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">1.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="Text_20_body"><span class="T2">Download a recent version of Firebird classic (e.g. 2.5) as a tar archive from </span><a href="http://www.firebirdsql.org/" class="Internet_20_link"><span class="T2">http://www.firebirdsql.org</span></a><span class="T2">. Open this archive and then extract the inner archive “buildroot.tar.gz” into your home directory. This should extract as a single directory with subdirectories.</span></p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P18" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">2.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P2">The extracted directory contains the default Firebird root directory files, such as “firebird.conf” and “security2.fdb”, various utilities in the “bin” directory and the libfbemded shared object in the “lib” subdirectory.</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P18" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">3.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P2">Your program should contain an IBDatabase component with its properties set as follows:</p><ol><li><ol><li><p class="P14" style="margin-left:0cm;"><span style="display:block;float:left;min-width:0.635cm;">i.</span>Database Name: Full pathname for the database file.<span class="odfLiEnd"/> </p></li><li><p class="P14" style="margin-left:0cm;"><span style="display:block;float:left;min-width:0.635cm;">ii.</span><span class="T4">Neither the</span>“user_name” <span class="T4">nor the </span>“password” parameter <span class="T4">should be present</span><span class="odfLiEnd"/> </p></li><li><p class="P16" style="margin-left:0cm;"><span style="display:block;float:left;min-width:0.635cm;">iii.</span>Logon Promt: false<span class="odfLiEnd"/> </p></li></ol></li></ol></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P18" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">4.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="Text_20_body">If a Service API component is being used (these are on the Firebird Admin tab) then the properties of this component should be set as follows:</p><ol><li><ol><li><p class="P14" style="margin-left:0cm;"><span style="display:block;float:left;min-width:0.635cm;">i.</span>Server Name: empty<span class="odfLiEnd"/> </p></li><li><p class="P14" style="margin-left:0cm;"><span style="display:block;float:left;min-width:0.635cm;">ii.</span>Protocol: Local<span class="odfLiEnd"/> </p></li><li><p class="P15" style="margin-left:0cm;"><span style="display:block;float:left;min-width:0.635cm;">iii.</span>“<span class="T4">Neither the</span>“user_name” <span class="T4">nor the </span>“password” parameter <span class="T4">should be present</span><span class="odfLiEnd"/> </p></li><li><p class="P16" style="margin-left:0cm;"><span style="display:block;float:left;min-width:0.635cm;">iv.</span>Logon Prompt: false<span class="odfLiEnd"/> </p></li></ol></li></ol></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P18" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">5.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P2">The program should now be compiled.</p></td></tr><tr><td style="text-align:left;" class="Table1_A1"><ol><li><p class="P18" style="margin-left:0cm;"><span class="Numbering_20_Symbols" style="display:block;float:left;min-width:0.635cm;">6.</span><span class="odfLiEnd"/> </p></li></ol></td><td style="text-align:left;" class="Table1_A1"><p class="P2">Now open a command line terminal and enter the following:</p><p class="P12">export FIREBIRD=$HOME/opt/firebird</p><p class="P12">export LD_LIBRARY_PATH=$HOME/opt/firebird/lib</p><p class="P12">&lt;path to your program&gt;</p><p class="P11">The program should now run and load the libfbembed.so.2.5 shared object from where it was extracted <span class="T4">(this takes precedence over the Firebird client library)</span>. When the database is opened it is opened directly and must have its permissions set to that it is read/write to the current user account. <span class="T4">T</span>here is no need to prompt the user for login parameters as <span class="T4">a local database should be opened using the unix account permissions.</span></p><p class="P11">Note: the FIREBIRD environment variable tells the embedded server where it can find its support files,  and the LD_LIBRARY_PATH  environment variable tells the Linux loader where it can find the shared object library.</p></td></tr></table><p class="P2"> </p><p class="P2">What has been achieved is the direct use of a Personal database without needing the Firebird Server to be installed on the system. Access controls are normal file controls and the database is typically private to the owning user. There is no shared access.</p><p class="P2">You could deploy your program with the contents of the “lib” directory and, as a minimum, the firebird.conf <span class="T4">and</span> firebird.msg files, and start it with a startup script that is a variation on the above. The location of these files is not important as long as the above environment variable<span class="T4">s</span> correctly identify where they are located and the directory containing the firebird.conf file is read/write to the current user.</p><h2 class="Heading_20_2"><a id="a__Using_a_Different_Firebird_shared_object_library"><span/></a>Using a Different Firebird shared object library</h2><p class="Text_20_body">There are alternative Firebird libraries that can be used. The Firebird 1.x client should work with IBX for Lazarus; you may want to experiment with a later version of Firebird. You could also use the Firebird Classic library (libfbembed.so.x). </p><p class="Text_20_body">The easiest way to make IBX for Lazarus to load a different library is to use the FBLIB environment variable (see above example). This can be set before running the Lazarus IDE (to make IBX load a different Firebird library when running in the IDE) or before running a user program. For example, entering the following commands into a command line shell, will run the Lazarus IDE with the Firebird 1.5 client library.</p><p class="P1">export FBLIB=libfbclient.so.1.5</p><p class="P1">startlazarus</p><p class="Text_20_body">Note that if you are using a Firebird library that is not in a standard location, then you may also want to set the LD_LIBRARY_PATH environment variable to the directory in which the Firebird library is located. </p><p class="P2">Alternatively, the name of an alternative library can be compiled into a user program. The “IBINTF” unit contains a callback function <span class="T1">OnGetLibraryName</span>. If this is set then it is called by the library loader before loading the Firebird Library and is expected to return the name of a shared object library. This function needs to be defined in the initialization section of a unit loaded before IBX i.e. early on in the initialization sequence. This can be achieved by placing the name of the unit in the “uses” clause of the progam's .lpr file immediately after the “interfaces” unit. </p><h2 class="Heading_20_2"><a id="a__How_IBX_for_Lazarus_located_and_loads_the_Firebird_Shared_Object_Library"><span/></a>How IBX for Lazarus located and loads the Firebird Shared Object Library</h2><p class="P9">By default, IBX will look for and dynamically load <span class="T4">either libfbembed.so.2.5, libfbembed.so.2.1 or the</span> libfbclient.so.2 shared object, <span class="T4">loading the first one found in the list</span>. libfbclient.so.2 is typically deployed as a soft link to the most recent version of the Firebird 2.x <span class="T4">client</span>library. As long as this has been installed in a location known to the <span class="T1">Linux</span><span class="T2"> loader then IBX will work “out of the box”. However, if this </span><span class="T3">or one of the embedded </span><span class="T2">librar</span><span class="T3">ies</span><span class="T2"> is in a non-standard location then you may need to set the LD_LIBRARY_PATH environment variable prior to running the Lazarus IDE or your program.</span></p><p class="P2">IBX will also recognise the FBLIB environment variable. If present, then this overrides the default <span class="T4">list of library names (semi-colon separated list)</span> for the shared object library and can be used to point IBX at any different version of the Firebird Library including the embedded server. For example, to use the embedded server, enter the command:</p><p class="P10">export FBLIB=libfbembed.so.2.<span class="T4">5</span></p><p class="P11">before running the IDE or your program. Note, as above, if the shared library is not in a  standard location then you may need to set the LD_LIBRARY_PATH.</p><p class="Text_20_body"><span class="T2">In your program, you can also create an event handler for the </span><span class="T1">OnGetLibraryName</span><span class="T2"> event defined in the IBIntf Unit. The event handler should be set in an initialization section and has the type:</span></p><p class="P10">procedure(var libname: string)</p><p class="P11">If present, then it is called prior to loading the shared object library and is expected to return the library name in its var parameter. This overrides the default library name, but can still be overridden by the FBLIB environment variable. A typical use for this event handler is to dynamically determine whether the Firebird Client library or the Embedded Server is to be used..</p></body></html>