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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type" />
<link rel="stylesheet" type="text/css" href="style.css" />
<title>SOCI - structure</title>
</head>
<body>
<p class="banner">SOCI - The C++ Database Access Library</p>
<h2>Library structure, files and compilation</h2>
<div class="navigation">
<a href="#structure">Structure</a><br />
<a href="#compilation">Compilation</a><br />
<div class="navigation-indented">
<a href="#autotools">With autotools on Unix/Linux</a><br />
<a href="#makefiles">With classic Makefiles on Unix/Linux</a><br />
<a href="#msvc">With Microsoft Visual C++ 2005 on Windows</a>
</div>
</div>
<h3 id="structure">The SOCI library structure</h3>
<div class="diagram">
<img alt="Library structure diagram" src="structure.png" />
</div>
<p>The core part of the library and the backend interface definition are
placed in the <code>core</code> directory of the library distribution.
The <code>soci-backend.h</code> file is an internal abstract
interface to the actual backends, which are needed to perform
operations on the given database server. Normally, the C++ client
program needs to interface with the <code>soci.h</code> header and the
header(s) relevant to the given backend(s) (for example, <code>soci-oracle.h</code>).
It is possible for the same program to use many backends at the same
time.</p>
<p>The gray boxes above indicate that the SOCI library is extensible and
that there are two aspects of this extensibility: more backends can be
added, and more interfaces (possibly for other languages) can be
defined to reuse the already existing backends.</p>
<p>Everything in SOCI is
declared in the namespace <code>SOCI</code>.
All code examples presented in this documentation assume that your code
begins with something
like:</p>
<pre class="example">
#include "soci.h"
// other includes
using namespace SOCI;
// ...
</pre>
<div class="note">
<p><span class="note">Note:</span>
In simple programs, <code>#include</code> for the relevant
backend is needed only in the file where the <code>Session</code>
object is created, because it is where the name of the backend factory
is referenced. The example program on the <a href="index.html">previous
page</a> shows the appropriate <code>#include</code> directive for the
Oracle backend.</p>
</div>
<h3 id="compilation">Compilation</h3>
<p>Download the SOCI distribution file: soci-X.Y.Z.tar.gz|tar.bz2|zip, where X.Y.Z is the version number. Unpack this file.</p>
<h4 id="autotools">With autotools on Unix/Linux</h4>
<p>Configure:</p>
<pre class="example">
$ ./configure
</pre>
<p>You may want to pass custom options to <code>./configure</code> script.
Backends can be enabled using options named as <code>--enable-backend-<name></code> and
disabled using <code>--disable-backend-<name></code>.
For example, to compile with support for MySQL that is already installed in some standard location, do this:</p>
<pre class="example">
$ ./configure --enable-backend-mysql=yes
</pre>
<p>There are also <code>--with-<package></code>
options which can be used to tell the script where the required headers and libraries can be found.</p>
<p>For example, to compile the library with the Oracle backend that is itself installed on a separate filesystem the following might be needed (example broken into three lines for clarity):</p>
<pre class="example">
$ ./configure --enable-backend-oracle=yes \
--with-oracle-include=/u01/oracle/product/10.1.0/rdbms/public \
--with-oracle-lib=/u01/oracle/product/10.1.0/lib
</pre>
<p>Run <code>./configure --help</code> to learn what configuration options are available.</p>
<p>Build (after successful configuration):</p>
<pre class="example">
$ make
</pre>
<p>Installation:</p>
<pre class="example">
$ make install
</pre>
<p>After the last step, SOCI components will be placed under default installation prefix <code>/usr/local</code> or custom location, if specified using <code>--prefix</code> option.</p>
<h4 id="makefiles">With classic Makefiles on Unix/Linux</h4>
<p>The classic set of Makefiles for Unix/Linux systems is provided just in case if the autotools method fails to recognize the local system configuration. In this sense, the Makefiles are supposed to only provide a minimal starting point for custom experimentation and are not intended to be a complete build/installation solution.<br />
On the other hand, they are complete in the sense that they can compile the library with all test programs and for some users this level of support will be just fine.</p>
<p>The <code>core</code> directory of the library distribution contains
the <code>Makefile.basic</code> that can be used to compile the core part of
the library. Run <code>make -f Makefile.basic</code> or <code>make -f Makefile.basic shared</code> to get
the static and shared versions. Similarly, the <code>backends/<i>name</i></code> directory contains the
backend part for each supported backend with the appropriate <code>Makefile.basic</code>
and the <code>backends/<i>name</i>/test</code>
directory contains the test program for the given backend.</p>
<p>For example, the simplest way to compile the static version of the
library and the test program for PostgreSQL is:</p>
<pre class="example">
$ cd src/core
$ make -f Makefile.basic
$ cd ../backends/postgresql
$ make -f Makefile.basic
$ cd test
$ make -f Makefile.basic
</pre>
<div class="note">
<p><span class="note">Note:</span>
For each backend and its test program, the <code>Makefile.basic</code>s
contain the variables that can have values specific to the given
environment. These variables are placed at the beginning of the <code>Makefile.basic</code>s.
Please review their values in case of any compilation problems.</p>
</div>
<p>The Makefiles for test programs can be a good starting point to find
out correct compiler and linker options.</p>
<h4 id="msvc">With Microsoft Visual C++ 2005 on Windows</h4>
<p>The SOCI distribution package includes solution files for Visual C++ 2005 - they can be found inside the <code>build\msvc80</code> directory:</p>
<ul>
<li><code>dll\soci_dll.sln</code> - to build SOCI as DLL libraries</li>
<li><code>lib\soci_lib.sln</code> - to build SOCI as static libraries</li>
</ul>
<p>Both solutions <a href="http://msdn2.microsoft.com/en-gb/library/tybz7dex(VS.80).aspx" title="MSDN: Property Inheritance">inherit</a> common
settings and macros from <a href="http://msdn2.microsoft.com/en-gb/library/a4xbdz1e(VS.80).aspx" title="MSDN: Property Sheets">Visual Studio Property Sheet</a> in file <code>build\msvc80\soci.vsprops</code>. The main concept behind the <code>soci.vsprops</code> is to provide common place where paths and
names of SOCI libraries and external dependencies are defined.</p>
<p><strong>NOTE:</strong> Currently, MySQL backend compilation is not supported due to some problems with linking to MySQL client library. If you know how to use it from Visual C++ 2005 and without rebuilding MySQL libraries on your own, please let us know.</p>
<p>Configure:</p>
<ol>
<li>Open <code>soci_dll.sln</code> or <code>soci_lib.sln</code> solution in Visual C++ IDE</li>
<li>Open View -> <a href="http://msdn2.microsoft.com/en-gb/library/z1f703z5(VS.80).aspx" title="MSDN: How to: Edit Project Property Sheets">Property Manager</a></li>
<li>Expand one of the projects (it doesn't matter which one), expand selected configuration ie. Debug, go through <code>soci_lib</code> sheet and double-click on <code>soci</code> to open its properties</li>
<li>According to your environment, customize paths and list of libraries by editing the following macros (double-click on macro update <code>Value</code> box):
<ul>
<li><code>FIREBIRD_INCLUDE_DIR</code> - path to FireBird client library headers</li>
<li><code>FIREBIRD_LIB_DIR</code> - path to FireBird client library</li>
<li><code>FIREBIRD_LIB</code> - FireBird library, can be left unchanged</li>
<li><code>MYSQL_INCLUDE_DIR</code> - <em>NOT USED</em></li>
<li><code>MYSQL_LIB_DIR</code> - <em>NOT USED</em></li>
<li><code>MYSQL_LIB</code> - <em>NOT USED</em></li>
<li><code>ODBC_INCLUDE_DIR</code> - ODBC include path, can be left unchanged</li>
<li><code>ODBC_LIB_DIR</code> - ODBC libraries path, can be left unchanged</li>
<li><code>ODBC_LIB</code> - ODBC library file, can be left unchanged</li>
<li><code>ORACLE_INCLUDE_DIR</code> - path to OCI headers</li>
<li><code>ORACLE_LIB_DIR</code> - path to OCI libraries</li>
<li><code>ORACLE_LIB</code> - list of OCI libraries</li>
<li><code>POSTGRESQL_INCLUDE_DIR</code> - path to <code>libpq</code> headers</li>
<li><code>POSTGRESQL_LIB_DIR</code> - path to <code>libpq</code> library</li>
<li><code>POSTGRESQL_LIB</code> - <code>libpq</code> library, can be left unchanged</li>
<li><code>SQLITE3_INCLUDE_DIR</code> - path to SQLite 3 headers</li>
<li><code>SQLITE3_LIB_DIR</code> - path to SQLite 3 library</li>
<li><code>SQLITE3_LIB</code> - SQLite 3 library, can be left unchanged</li>
</ul>
</li>
<li><strong>Leave the remaining macros untouched</strong></li>
</ol>
<p>After the configuration is ready, you can build SOCI libraries from the Visual C++ 2005 IDE.</p>
<p>Build:</p>
<pre class="example">
Build -> Build Solution
</pre>
<p>If no errors occured, SOCI libraries and test programs can be found in subdirectory <code>debug</code> or <code>release</code>, depending on selected build configuration.</p>
<p>Running tests:</p>
<p>You need to edit <code>maketest.mak</code> file and change relevant connection strings in the <code>CONFIGURATION</code> block, according to your environment.</p>
<p>Run all tests:</p>
<pre class="example">
nmake /f maketest.mak
</pre>
<p>Run test for selected backend:</p>
<pre class="example">
nmake /f maketest.mak <backendname>
</pre>
<p>
It is also possible to run test programs directly from command prompt, without using <code>maketest.mak</code> controller.</p>
<table class="foot-links" border="0" cellpadding="2" cellspacing="2">
<tr>
<td class="foot-link-left">
<a href="index.html">Previous (Contents)</a>
</td>
<td class="foot-link-right">
<a href="errors.html">Next (Errors)</a>
</td>
</tr>
</table>
<p class="copyright">Copyright © 2004-2006 Maciej Sobczak, Stephen Hutton</p>
</body>
</html>
|