-
Notifications
You must be signed in to change notification settings - Fork 472
/
installation.html
392 lines (338 loc) · 19.5 KB
/
installation.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en'>
<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>Installation</h2>
<div class="navigation">
<a href="#requirements">Requirements</a><br />
<a href="#downloading">Downloading</a><br />
<a href="#cmake">Building using CMake</a><br />
<div class="navigation-indented">
<a href="#unix">On Unix</a><br />
<a href="#windows">On Windows</a><br />
</div>
<a href="#unix-makefiles">Building using classic Makefiles on Unix</a><br />
<a href="#testing">Running Tests</a><br />
<a href="#usage">Usage</a><br />
</div>
<h3 id="requirements">Requirements</h3>
<p>Below is an overall list of SOCI core:</p>
<ul>
<li>C++ compiler: <a href="http://gcc.gnu.org/">GCC</a>, <a href="http://msdn.microsoft.com/en-us/visualc">Microsoft Visual C++</a>, <a href="http://clang.llvm.org/">LLVM/clang</a></li>
<li><a href="http://www.cmake.org">CMake</a> 2.8+ - in order to use build configuration for CMake</li>
<li><a href="http://www.boost.org">Boost C++ Libraries</a>: DateTime, Fusion, Optional, Preprocessor, Tuple</li>
</ul>
<p>and backend-specific dependencies:</p>
<ul>
<li><a href="http://dev.mysql.com/doc/refman/5.6/en/c.html">mysqlclient</a> - C API to MySQL</li>
<li><a href="">ODBC (Open Database Connectivity)</a> implementation: <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms710252.aspx">Microsoft ODBC</a>, <a href="http://www.iodbc.org/">iODBC</a>, <a href="http://www.unixodbc.org/">unixODBC</a></li>
<li><a href="http://www.oracle.com/technetwork/database/features/oci/index.html">Oracle Call Interface (OCI)</a></li>
<li><a href="http://www.postgresql.org/docs/8.4/static/libpq.html">libpq</a> - C API to PostgreSQL</li>
<li><a href="http://www.sqlite.org/">SQLite 3</a> library</li>
</li>
</ul>
<h3 id="downloading">Downloading</h3>
<p>Download package with latest release of the SOCI source code: <a href="https://sourceforge.net/projects/soci/files/soci/">soci-X.Y.Z</a>, where X.Y.Z is the version number. Unpack the archive.</p>
<p>If you intend to hack SOCI, you can clone the Git repository:</p>
<pre>git clone git://soci.git.sourceforge.net/gitroot/soci/soci </pre>
<h3 id="cmake">Building using CMake</h3>
<p>SOCI is configured to build using <a href="http://cmake.org/">CMake</a> system in version 2.8+.</p>
<p>The build configuration allows to control various aspects of compilation and installation by setting common CMake variables that change behaviour, describe system or control build (see <a href="http://cmake.org/cmake/help/documentation.html">CMake help</a>) as well as SOCI-specific variables described below. All these variables are available regardless of platform or compilation toolset used.</p>
<p>Running CMake from the command line allows to set variables in the CMake cache with the following syntax: <code>-DVARIABLE:TYPE=VALUE</code>. If you are new to CMake, you may find the tutorial <a href="http://cmake.org/cmake/help/runningcmake.html">Running CMake</a> helpful.</p>
<p>The following tables provide summary of variables accepted by CMake scripts configuring SOCI build. The lists consist of common variables for SOCI core and all backends as well as variables specific to SOCI backends and their direct dependencies.</p>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="CMake essential variables (refer to CMake manual for complete list)">
<caption class="cmake-variables">List of a few essential CMake variables</caption>
<tr>
<td class="variable-name">CMAKE_BUILD_TYPE</td>
<td class="variable-type">string</td>
<td>Specifies the build type for make based generators (see CMake <a href="http://cmake.org/cmake/help/cmake-2-8-docs.html#variable:CMAKE_BUILD_TYPE">help</a>).</td>
</tr>
<tr>
<td class="variable-name">CMAKE_INSTALL_PREFIX</td>
<td class="variable-type">path</td>
<td>Install directory used by install command (see CMake <a href="http://cmake.org/cmake/help/cmake-2-8-docs.html#variable:CMAKE_INSTALL_PREFIX">help</a>).</td>
</tr>
<tr>
<td class="variable-name">CMAKE_VERBOSE_MAKEFILE</td>
<td class="variable-type">boolean</td>
<td>If ON, create verbose makefile (see CMake <a href="http://cmake.org/cmake/help/cmake-2-8-docs.html#variable:CMAKE_VERBOSE_MAKEFILE">help</a>).</td>
</tr>
</table>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="SOCI Core configuration">
<caption class="cmake-variables">List of variables to control common SOCI features and dependencies</caption>
<tr>
<td class="variable-name">WITH_BOOST</td>
<td class="variable-type">boolean</td>
<td>Should CMake try to detect <a href="http://www.boost.org/">Boost C++ Libraries</a>. If ON, CMake will try to find Boost headers and binaries of <a href="http://www.boost.org/doc/libs/release/doc/html/date_time.html">Boost.Date_Time</a> library.</td>
</tr>
<tr>
<td class="variable-name">SOCI_TESTS</td>
<td class="variable-type">boolean</td>
<td>Request to build regression tests for SOCI core and all successfully configured backends.</td>
</tr>
</table>
<h4 id="mysql">MySQL</h4>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="SOCI MySQL configuration">
<caption class="cmake-variables">SOCI MySQL backend configuration</caption>
<tr>
<td class="variable-name">WITH_MYSQL</td>
<td class="variable-type">boolean</td>
<td>Should CMake try to detect <a href="http://dev.mysql.com/doc/refman/5.0/en/c.html">mysqlclient</a> libraries providing MySQL C API. Note, currently the <a href="http://dev.mysql.com/doc/refman/5.0/en/building-clients.html">mysql_config</a> program is not being used.</td>
</tr>
<tr>
<td class="variable-name">MYSQL_DIR</td>
<td class="variable-type">string</td>
<td>Path to MySQL installation root directory. CMake will scan subdirectories <code>MYSQL_DIR/include</code> and <code>MYSQL_DIR/lib</code> respectively for MySQL headers and libraries.</td>
</tr>
<tr>
<td class="variable-name">MYSQL_INCLUDE_DIR</td>
<td class="variable-type">string</td>
<td>Path to MySQL include directory where CMake should look for mysql.h header.</td>
</tr>
<tr>
<td class="variable-name">MYSQL_LIBRARIES</td>
<td class="variable-type">string</td>
<td>Full paths to libraries to link SOCI against to enable the backend support.</td>
</tr>
<tr>
<td class="variable-name">SOCI_MYSQL</td>
<td class="variable-type">boolean</td>
<td>Requests to build <a href="backends/mysql.html">MySQL</a> backend. Automatically switched on, if <code>WITH_MYSQL</code> is set to ON.</td>
</tr>
<tr>
<td class="variable-name">SOCI_MYSQL_TEST_CONNSTR</td>
<td class="variable-type">string</td>
<td>Connection string to MySQL test database. Format of the string is explained <a href="backends/mysql.html">MySQL backend refernece</a>. Example: <code>-DSOCI_MYSQL_TEST_CONNSTR:STRING="db=mydb user=mloskot password=secret"</code></td>
</tr>
</table>
<h4 id="odbc">ODBC</h4>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="SOCI ODBC configuration">
<caption class="cmake-variables">SOCI ODBC backend configuration</caption>
<tr>
<td class="variable-name">WITH_ODBC</td>
<td class="variable-type">boolean</td>
<td>Should CMake try to detect ODBC libraries. On Unix systems, CMake tries to find <a href="http://www.unixodbc.org/">unixODBC</a> or <a href="http://www.iodbc.org/">iODBC</a> implementations.</td>
</tr>
<tr>
<td class="variable-name">ODBC_INCLUDE_DIR</td>
<td class="variable-type">string</td>
<td>Path to ODBC implementation include directories where CMake should look for sql.h header.</td>
</tr>
<tr>
<td class="variable-name">ODBC_LIBRARIES</td>
<td class="variable-type">string</td>
<td>Full paths to libraries to link SOCI against to enable the backend support.</td>
</tr>
<tr>
<td class="variable-name">SOCI_ODBC</td>
<td class="variable-type">boolean</td>
<td>Requests to build <a href="backends/odbc.html">ODBC</a> backend. Automatically switched on, if <code>WITH_ODBC</code> is set to ON.</td>
</tr>
<tr>
<td class="variable-name">SOCI_ODBC_TEST_{database}_CONNSTR</td>
<td class="variable-type">string</td>
<td>ODBC Data Source Name (DSN) or ODBC File Data Source Name (FILEDSN) to test database: Microsoft Access (.mdb), Microsoft SQL Server, MySQL, PostgreSQL or any other ODBC SQL data source. {database} is placeholder for name of database driver ACCESS, MYSQL, POSTGRESQL, etc. See <a href="backends/odbc.html">ODBC backend refernece</a> for details. Example: <code>-DSOCI_ODBC_TEST_POSTGRESQL_CONNSTR="FILEDSN=/home/mloskot/dev/soci/_git/build/test-postgresql.dsn"</code></td>
</tr>
</table>
<h4 id="oracle">Oracle</h4>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="SOCI Oracle configuration">
<caption class="cmake-variables">SOCI Oracle backend configuration</caption>
<tr>
<td class="variable-name">WITH_ORACLE</td>
<td class="variable-type">boolean</td>
<td>Should CMake try to detect <a href="http://en.wikipedia.org/wiki/Oracle_Call_Interface">Oracle Call Interface (OCI)</a> libraries.</td>
</tr>
<tr>
<td class="variable-name">ORACLE_INCLUDE_DIR</td>
<td class="variable-type">string</td>
<td>Path to Oracle include directory where CMake should look for oci.h header.</td>
</tr>
<tr>
<td class="variable-name">ORACLE_LIBRARIES</td>
<td class="variable-type">string</td>
<td>Full paths to libraries to link SOCI against to enable the backend support.</td>
</tr>
<tr>
<td class="variable-name">SOCI_ORACLE</td>
<td class="variable-type">boolean</td>
<td>Requests to build <a href="backends/oracle.html">Oracle</a> backend. Automatically switched on, if <code>WITH_ORACLE</code> is set to ON.</td>
</tr>
<tr>
<td class="variable-name">SOCI_ORACLE_TEST_CONNSTR</td>
<td class="variable-type">string</td>
<td>Connection string to Oracle test database. Format of the string is explained <a href="backends/oracle.html">Oracle backend refernece</a>. Example: <code>-DSOCI_ORACLE_TEST_CONNSTR:STRING="service=orcl user=scott password=tiger"</code></td>
</tr>
</table>
<h4 id="postgresql">PostgreSQL</h4>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="SOCI Oracle configuration">
<caption class="cmake-variables">SOCI PostgreSQL backend configuration</caption>
<tr>
<td class="variable-name">WITH_POSTGRESQL</td>
<td class="variable-type">boolean</td>
<td>Should CMake try to detect PostgreSQL client interface libraries. SOCI relies on <a href="http://www.postgresql.org/docs/9.0/interactive/libpq.html">libpq</a> C library.</td>
</tr>
<tr>
<td class="variable-name">POSTGRESQL_INCLUDE_DIR</td>
<td class="variable-type">string</td>
<td>Path to PostgreSQL include directory where CMake should look for libpq-fe.h header.</td>
</tr>
<tr>
<td class="variable-name">POSTGRESQL_LIBRARIES</td>
<td class="variable-type">string</td>
<td>Full paths to libraries to link SOCI against to enable the backend support.</td>
</tr>
<tr>
<td class="variable-name">SOCI_POSTGRESQL</td>
<td class="variable-type">boolean</td>
<td>Requests to build <a href="backends/postgresql.html">PostgreSQL</a> backend. Automatically switched on, if <code>WITH_POSTGRESQL</code> is set to ON.</td>
</tr>
<tr>
<td class="variable-name">SOCI_POSTGRESQL_TEST_CONNSTR</td>
<td class="variable-type">boolean</td>
<td>Connection string to PostgreSQL test database. Format of the string is explained <a href="backends/postgresql.html">PostgreSQL backend refernece</a>. Example: <code>-DSOCI_POSTGRESQL_TEST_CONNSTR:STRING="dbname=mydb user=mloskot"</code></td>
</tr>
</table>
<h4 id="sqlite">SQLite 3</h4>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="SOCI Oracle configuration">
<caption class="cmake-variables">SOCI SQLite 3 backend configuration</caption>
<tr>
<td class="variable-name">WITH_SQLITE3</td>
<td class="variable-type">boolean</td>
<td>Should CMak try to detect <a href="http://www.sqlite.org/cintro.html">SQLite C/C++ library</a>. As bonus, the configuration tries <a href="http://trac.osgeo.org/osgeo4w/">OSGeo4W</a> distribution if <code>OSGEO4W_ROOT</code> environment variable is set.</td>
</tr>
<tr>
<td class="variable-name">SQLITE_INCLUDE_DIR</td>
<td class="variable-type">string</td>
<td>Path to SQLite 3 include directory where CMake should look for sqlite3.h header.</td>
</tr>
<tr>
<td class="variable-name">SQLITE_LIBRARIES</td>
<td class="variable-type">string</td>
<td>Full paths to libraries to link SOCI against to enable the backend support.</td>
</tr>
<tr>
<td class="variable-name">SOCI_SQLITE3</td>
<td class="variable-type">boolean</td>
<td>Requests to build <a href="backends/sqlite3.html">SQLite3</a> backend. Automatically switched on, if <code>WITH_SQLITE3</code> is set to ON.</td>
</tr>
<tr>
<td class="variable-name">SOCI_SQLITE3_TEST_CONNSTR</td>
<td class="variable-type">string</td>
<td>Connection string is simply a file path where SQLite3 test database will be created (e.g. /home/john/soci_test.db). Check <a href="backends/sqlite3.html">SQLite3 backend refernece</a> for details. Example: <code>-DSOCI_SQLITE3_TEST_CONNSTR="my.db"</code></td>
</tr>
</table>
<h4 id="empty">Empty (sample backend)</h4>
<table class="cmake-variables" cellpadding="2" cellspacing="2" summary="SOCI Oracle configuration">
<caption class="cmake-variables">SOCI empty sample backend configuration</caption>
<tr>
<td class="variable-name">SOCI_EMPTY</td>
<td class="variable-type">boolean</td>
<td>Builds the <a href="backends.html">sample backend</a> called Empty. Always ON by default.</td>
</tr>
<tr>
<td class="variable-name">SOCI_EMPTY_TEST_CONNSTR</td>
<td class="variable-type">string</td>
<td>Connection string used to run regression tests of the Empty backend. It is a dummy value. Example: <code>-DSOCI_EMPTY_TEST_CONNSTR="dummy connection"</code></td>
</tr>
</table>
<p>By default, CMake will try to determine availability of all depdendencies automatically. If you are lucky, you will not need to specify any of the CMake variables explained above. However, if CMake reports some of the core or backend-specific dependencies as missing, you will need specify relevant variables to tell CMake where to look for the required components.</p>
<p>CMake configures SOCI build performing sequence of steps. Each
subsequent step is dependant on result of previous steps corresponding
with particular feature. First, CMake checks system platform and
compilation toolset. Next, CMake tries to find all external
dependencies. Then, depending on the results of the dependency check,
CMake determines SOCI backends which are possible to build. The
SOCI-specific variables described above provide users with basic
control of this behaviour.</p>
<h4 id="unix">Building using CMake on Unix</h4>
<p>Short version using GNU Make makefiles:</p>
<pre class="example">
$ mkdir build
$ cd build
$ cmake -G "Unix Makefiles" -DWITH_BOOST=OFF -DWITH_ORACLE=OFF (...) ../soci-X.Y.Z
$ make
$ make install
</pre>
<h4 id="windows">Building using CMake on Windows</h4>
<p>Short version using Visual Studio 2010 and MSBuild:</p>
<pre class="example">
C:\>MKDIR build
C:\>cd build
C:\build>cmake -G "Visual Studio 10" -DWITH_BOOST=OFF -DWITH_ORACLE=OFF (...) ..\soci-X.Y.Z
C:\build>msbuild.exe SOCI.sln
</pre>
<h3 id="unix-makefiles">Building using classic Makefiles on Unix</h3>
<p>The classic set of Makefiles for Unix/Linux systems is provided for those users who need complete control over the whole process
and who can benefit from the basic scaffolding that they can extend on their own.
In this sense, the basic Makefiles are supposed to provide a minimal starting point for custom experimentation and are not intended to be a complete build/installation solution.<br />
At the same time, 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, respectively.
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 - they usually name the include and library paths.
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>
<h3 id="testing">Running regression tests</h3>
<p>The process of running regression tests highly depends on user's environment and build configuration, so it may be quite involving process. The CMake configuration provides variables to allow users willing to run the tests to configure build and specify database connection parameters (see the tables above for variable names).</p>
<p>In order to run regression tests, configure and build desired SOCI backends and prepare working database instances for them.</p>
<p>While configuring build with CMake, specify <code>SOCI_TESTS=ON</code> to enable building regression tests. Also, specify <code>SOCI_{backend name}_TEST_CONNSTR</code> variables to tell the tests runner how to connect with your test databases.</p>
<p>Dedicated <code>make test</code> target can be used to execute regression tests on build completion:</p>
<pre class="example">
$ mkdir build
$ cd build
$ cmake -G "Unix Makefiles" -DWITH_BOOST=OFF \
-DSOCI_TESTS=ON \
-DSOCI_EMPTY_TEST_CONNSTR="dummy connection" \
-DSOCI_SQLITE3_TEST_CONNSTR="test.db" \
(...)
../soci-X.Y.Z
$ make
$ make test
$ make install
</pre>
<p>In the example above, regression tests for the sample Empty backend and SQLite 3 backend are configured for execution by <code>make test</code> target.</p>
<h3 id="usage">Libraries usage</h3>
<p>CMake build produces set of shared and static libraries for SOCI core and backends separately. On Unix, for example, <code>build/lib</code> directory
will consist of the static libraries named like <code>libsoci_core.a</code>, <code>libsoci_sqlite3.a</code> and shared libraries with names like
<code>libsoci_core.so.3.1.0</code>, <code>libsoci_sqlite3.so.3.1.0</code>, and so on.</p>
<p>In order to use SOCI in your program, you need to specify your project build configuration with paths to SOCI headers and libraries,
and specify linker to link against the libraries you want to use in your program.</p>
</p>
<table class="foot-links" border="0" cellpadding="2" cellspacing="2">
<tr>
<td class="foot-link-left">
<a href="structure.html">Previous (Structure)</a>
</td>
<td class="foot-link-right">
<a href="errors.html">Next (Errors)</a>
</td>
</tr>
</table>
<p class="copyright">Copyright © 2004-2011 Maciej Sobczak, Stephen Hutton, Mateusz Loskot</p>
</body>
</html>