-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathINSTALL.txt
299 lines (221 loc) · 11.2 KB
/
INSTALL.txt
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
INSTALL
=======
Find updated versions of this document at: https://exodbc.elisium.ch
This document describes some hints on how to build exobc and its components
(tests, samples) using cmake. Please follow cmkake instructions on how to
obtain cmake for your platform: https://cmake.org/
Quickstart
==========
A short manual on how to build libexodbc only, without samples and tests.
Required are the boost headers (http://www.boost.org/).
From exOdbc top-level directory:
mkdir build
cd build
set BOOST_ROOT=e:/lib/boost_1_62_0 [Probably required for Windows only.]
cmake -DBUILD_TESTS=OFF -DBUILD_SAMPLES=OFF ..
cmake --build .
And some explanations:
Create a directory for the build-environment and cd into it:
mkdir build
cd build
On Windows you probably need to tell cmake where to look for the required boost
header-only libraries by setting BOOST_ROOT (or alternatively, BOOST_INCLUDEDIR):
set BOOST_ROOT=e:/lib/boost_1_62_0
Then let cmake configure the environment to build only the core exodbc library
by setting BUILD_TESTS and BUILD_SAMPLES to samples OFF:
cmake -DBUILD_TESTS=OFF -DBUILD_SAMPLES=OFF ..
Finally build the library:
cmake --build .
On Windows you can choose a build configurations ('Debug' or 'Release'):
cmake --build . --config Release
cmake --build . --config Debug
The resulting binaries have been placed in 'bin'.
Full build
==========
Build all components including the tests and samples.
Requires the boost headers and a built library boost-filesystem. A working
git client is required to download googletest from github during configuration.
From exOdbc top-level directory:
Create a directory for the build-environment and cd into it:
mkdir build
cd build
Tell cmake where to look for the required boost libraries. boost-filesystem and
boost-system are required to build the tests.
set BOOST_ROOT=e:/lib/boost_1_62_0
cmake ..
or to prepare a 64bit build (See cmake doc for a list of available Generators):
cmake -G "Visual Studio 14 2015 Win64" ..
Build all targets:
cmake --build .
Install reference
=================
Configuration options and dependencies. See the cmake documentation for
more available options.
Configuration Options
---------------------
Some option variables may change the resulting cmake-configuration and can
be used with cmake:
BUILD_TESTS: If set to ON, exodbctest is built.
Default: ON
BUILD_SAMPLES: If set to ON, samples are built.
Default: ON
BUILD_SHARED_LIBS: Build shared or static libs.
Default: OFF
and how dependencies are used:
Boost_USE_STATIC_LIBS: Set to ON to link against static libs of boost.
Default: ON on Windows, OFF else.
BOOST_ROOT: Root directory of boost.
For example, to configure 64bit vc140 builds without tests but with samples:
cmake -G "Visual Studio 14 2015 Win64" -DBUILD_TESTS=OFF ..
To configure 64bit vc140 builds as static lib and link against boost static libs:
cmake -G "Visual Studio 14 2015 Win64" -DBoost_USE_STATIC_LIBS=ON -DBUILD_SHARED_LIBS=OFF ..
To configure 32bit vc140 builds as shared lib with dynamic linking against boost:
cmake -G "Visual Studio 14 2015" -DBoost_USE_STATIC_LIBS=OFF -DBUILD_SHARED_LIBS=ON ..
Debug or Release build
----------------------
With multi-configuration generators like Visual Studio you can pick the build
configuration during build time:
cmake --build . --config Release
cmake --build . --config Debug
Note that only Release and Debug configurations are available. See
CMakeLists.txt for more details.
With single-configuration generators you must pick the build configuration
during configuring, using the option CMAKE_BUILD_TYPE
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake -DCMAKE_BUILD_TYPE=Release ..
Generated Files
---------------
Note that during configuration the following files will be generated inside the
source folder:
include/exodbc/exodbcConfig.ha
test/exOdbcTestConfig.h
Do not remove those files.
Dependencies
------------
libexodbc:
- boost (header-only)
exOdbcTest
- gtest: Fetched during compilation from github. See CMakeLists.txt.in for more
information.
- boost: Only boost-filesystem is required (but it must be compiled).
- libexodbc
Some samples on how to build the required boost components, see the boost documentation for
more information:
bootstrap
To build 32bit shared libs:
b2 --with-filesystem --with-program_options variant=debug link=shared threading=multi runtime-link=shared address-model=32
b2 --with-filesystem --with-program_options variant=release link=shared threading=multi runtime-link=shared address-model=32
To build 32bit static libs:
b2 --with-filesystem --with-program_options variant=debug link=static threading=multi runtime-link=shared address-model=32
b2 --with-filesystem --with-program_options variant=release link=static threading=multi runtime-link=shared address-model=32
To build 64bit shared libs:
b2 --with-filesystem --with-program_options variant=debug link=shared threading=multi runtime-link=shared address-model=64
b2 --with-filesystem --with-program_options variant=release link=shared threading=multi runtime-link=shared address-model=64
To build 64bit static libs:
b2 --with-filesystem --with-program_options variant=debug link=static threading=multi runtime-link=shared address-model=64
b2 --with-filesystem --with-program_options variant=release link=static threading=multi runtime-link=shared address-model=64
Clean build environment
-----------------------
From build-environment directory:
cmake --build . --target clean
Start over (Clean cmake environment)
------------------------------------
Simply remove the build-environment directory.
Documentation
=============
Documentation requires doxygen and can be built using the target 'doc':
cmake --build . --target doc
The resulting docs will be placed in a folder 'doc'.
Test Reference
==============
How to run the tests against different databases. exOdbc has been tested against various databases:
* Sql Server
* MySql
* DB2
* Access
* Excel
For most tests a database with a few tables is required.
Test Options
------------
There are a few CMake options to configure which tests to include:
ENABLE_SQLSERVER_TEST: Enable the test for Sql Server
Default: ON
ENABLE_POSTGRESQL_TEST: Enable the test for PostgreSQL
Default: ON
ENABLE_MYSQL_TEST: Enable the test for MySql
Default: ON for Windows, OFF for Linux.
ENABLE_DB2_TEST: Enable the test for DB2
Default: ON for Windows, OFF for Linux.
ENABLE_ACCESS_TEST Enable the test for Access. Only set on Windows 32bit builds.
Default: ON
ENABLE_EXCEL_TEST Enable the test for Excel. Only set on Windows 32bit builds.
Default: ON
To run tests against a specific database, a connection string is required:
SQLSERVER_TEST_CS Connection-String used to run tests against Sql Server
POSTGRESQL_TEST_CS Connection-String used to run tests against PostgreSQL
MYSQL_TEST_CS Connection-String used to run tests against MySql
DB2_TEST_CS Connection-String used to run tests against DB2
ACCESS_TEST_CS Connection-String used to run tests against Access
EXCEL_TEST_CS Connection-String used to run tests against Excel
For every database, there is a cache variable allowing to set the --gtest_filter
argument value. It is used to skip tests that are known to fail on certain databases.
See: https://exodbc.elisium.ch/trac/query?milestone=exOdbc+Known+Failures&group=component
for a list of tests known to fail.
SQLSERVER_TEST_GTEST_FILTER Argument value for '--gtest_filter'
Default: '*' - all tests are supposed to work on Sql Server
POSTGRESQL_TEST_GTEST_FILTER Argument value for '--gtest_filter'
Default: Filter out tests that are known to fail with PostgreSQL
MYSQL_TEST_GTEST_FILTER Argument value for '--gtest_filter'
Default: Filter out tests that are known to fail with MySql
DB2_TEST_GTEST_FILTER Argument value for '--gtest_filter'
Default: '*' - all tests are supposed to work on DB2
ACCESS_TEST_GTEST_FILTER Argument value for '--gtest_filter'
Default: Filter out tests that are known to fail with Access
EXCEL_TEST_GTEST_FILTER Argument value for '--gtest_filter'
Default: 'ExcelTest.*' run only some very specific excel tests.
The log level used in exodbctest can be set using the following cache variables:
SQLSERVER_TEST_LOG_LEVEL Default: 'Warning'
POSTGRESQL_TEST_LOG_LEVEL Default: 'Warning'
MYSQL_TEST_LOG_LEVEL Default: 'Warning'
DB2_TEST_LOG_LEVEL Default: 'Warning'
ACCESS_TEST_LOG_LEVEL Default: 'Warning'
EXCEL_TEST_LOG_LEVEL Default: 'Warning'
Prepare Test Database
---------------------
Database-type specific scripts to create test tables are provided in test/sql.
For Access and Excel, database files are provided in test/db.
The database itself must be created using db-specific tools, there are
currently no scripts available to do so (why not? -> see #11). The following
constraints must be met for the test-databases:
* Sql Server: Database and schema must be named 'exodbc'
* MySql: Schema must be named 'exodbc'
Run the scripts in the test/sql directory to create the required tables with
their values in that database.
Alternatively, you can also use exodbctest with the --createDb parameter to
create the required tables:
If the --createDb parameter is passed to exodbctest, exodbctest will try to
connect to the database, using the passed connection string or dsn arguments,
try to identify the database-type and run the corresponding scripts inside
test/sql. Afterwards the tests are run.
see exodbctest help for more information:
exodbctest --help
Run Tests
---------
Use ctest to run the tests. From the build-environment directory:
ctest --verbose -C Debug
ctest --verbose -C Release
To run a specific test use:
ctest --verbose -C Debug -R AccessTest
To list tests:
ctest -C Debug -N
TestSettings.xml
----------------
The main reason for this file is to have a convienent way of running the tests
from inside Visual Studio. The Google Test Adapter plugin does not (yet?)
provide a convinient way of passing arguments to the test app, and the Visual
Studio dialog doesn't help much.
If exodbctest is invoked without arguments, it will search for a file named 'TestSetting.xml'.
If one is found, the connection string / dsn and which tests to run are determined from the
TestSettings.xml file.
If no argument '--gtest_filter' is given on the command-line, exodbctest will create such an
argument that skips all tests defined to be skipped in TestSettings.xml.