This repository has been archived by the owner on May 4, 2021. It is now read-only.
forked from pocoproject/poco
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
273 lines (203 loc) · 11.3 KB
/
README
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
This is the README file for the POCO C++ Libraries.
In this document you will find a brief description of the directory layout,
as well as a description necessary steps to build the POCO C++ Libraries.
The Foundation library contains a platform abstraction layer (including classes
for multithreading, file system access, logging, etc.), as well as
a large number of useful utility classes, such various stream buffer and stream
classes, URI handling, and many more.
The XML library contains an XML parser with SAX2 and DOM interfaces,
as well as an XMLWriter.
The Util library contains classes for working with configuration files and
command line arguments, as well as various utility classes.
The Net library contains network classes (sockets, HTTP client/server, etc.).
All libraries come with a test suite and a number of sample programs.
The basic directory layout is as follows:
build/ the build system for Unix and additional utility scripts
config/ build configurations for various Unix platforms
rules/ common build rules for all platforms
scripts/ build and utility scripts
vxconfig/ VxWorks build configurations
cmake/ Support files for CMake
bin/ all executables (dynamic link libraries on Windows)
bin64/ all 64-bit executables (and DLLs)
doc/ additional documentation
lib/ all libraries (import libraries on Windows)
lib64/ all 64-bit libraries
CppUnit/ project and make/build files for the CppUnit unit testing framework
doc/ additional documentation
include/
CppUnit/ header files for CppUnit
src/ source files for CppUnit
WinTestRunner/ Windows GUI for CppUnit
Foundation/ project and make/build files for the Foundation library
include/
Poco/ header files for the Foundation library
src/ source files for the Foundation library
testsuite/ project and make/build files for the Foundation testsuite
src/ source files for the Foundation testsuite
bin/ test suite executables
samples/ sample applications for the Foundation library
XML/ project and make/build files for the XML library
include/
Poco/
XML/ header files for the core XML library
SAX/ header files for SAX support
DOM/ header files for DOM support
src/ source files for the XML library
testsuite/ project and make/build files for the XML testsuite
src/ source files for the XML testsuite
bin/ test suite executables
samples/ sample applications for the XML library
Net/ project and make/build files for the Net library
include/
Poco/
Net/ header files for the Net library
src/ source files for the Net library
testsuite/ project and make/build files for the Net testsuite
src/ source files for the Net testsuite
bin/ test suite executables
samples/ sample applications for the Net library
Depending on what package you have downloaded, there may be other libraries
as well (such as Data, Crypto, NetSSL_OpenSSL and Zip).
DOCUMENTATION
=============
Plenty of documentation (tutorial slides, articles and SDK reference)
is available at <http://pocoproject.org/documentation/>.
EXTERNAL DEPENDENCIES
=====================
The following libraries require third-party software (header files and
libraries) being installed to build properly:
- NetSSL_OpenSSL and Crypt require OpenSSL.
- Data/ODBC requires ODBC
(Microsoft ODBC on Windows, unixODBC or iODBC on Unix/Linux)
- Data/MySQL requires the MySQL client.
Most Unix/Linux systems already have OpenSSL preinstalled. If your system
does not have OpenSSL, please get it from http://www.openssl.org or
another source. You do not have to build OpenSSL yourself - a binary
distribution is fine (e.g., apt-get install openssl libssl-dev).
On macOS, install OpenSSL via Homebrew (brew install openssl).
The easiest way to install OpenSSL on Windows is to get the pre-built
libraries from the pocoproject/openssl Git repository at
<https://github.com/pocoproject/openssl>. This repository is included
as a submodule in the poco GitHub repository, but not in the release
source code packages. You can also provide your own OpenSSL build by
editing the Visual Studio project files.
Depending on where you have installed the OpenSSL libraries,
you might have to edit the build script (buildwin.cmd), or add the
necessary paths to the INCLUDE and LIB environment variables.
Through the Poco/Crypto/Crypto.h and Poco/Net/NetSSL.h header files,
Visual C++ will automatically link the libcrypto.lib and libssl.lib
libraries. If your OpenSSL libraries are named differently, compile
with the macro POCO_EXTERNAL_OPENSSL defined and edit the project
files accordingly.
The Data library requires ODBC support on your system if you want
to build the ODBC connector (which is the default). On Windows
platforms, ODBC should be readily available if you have the
Windows SDK. On Unix/Linux platforms, you can use iODBC
(preinstalled on macOS X) or unixODBC. For the MySQL connector,
the MySQL client libraries and header files are required.
The Data/ODBC and Data/MySQL Makefiles will search for the ODBC
and MySQL headers and libraries in various places. Nevertheless,
the Makefiles may not be able to find the headers and libraries.
In this case, please edit the Makefile in Data/ODBC and/or Data/MySQL
accordingly.
BUILDING WITH CMAKE
===================
The POCO C++ Libraries support CMake as a build system on Linux, macOS and Windows.
To build the POCO C++ Libraries with CMake:
1. create a cmake-build directory (e.g. in the POCO root directory):
$ mkdir cmake-build
2. and run CMake from there:
$ cd cmake-build
$ cmake ..
$ make -s -j (or build the generated Visual Studio solution on Windows)
If you cannot or do not want to build with CMake, there are other options,
described in the following.
BUILDING ON WINDOWS
===================
Microsoft Visual Studio 2015 or newer is required to build the POCO C++ Libraries on
Windows platforms. Solution and project files for all versions from 2015 to 2019 are included.
64-bit (x64) builds are supported as well.
You can either build from within Visual Studio (Build->Batch Build->Select All;Rebuild)
or from the command line. To build from the command line, start the
Visual Studio Command Prompt and cd to the directory where you
have extracted the POCO C++ Libraries sources. Then, simply start the buildwin.cmd script
and pass as argument the version of visual studio (140, 150, 160, etc.). You can customize
what is being built by buildwin.cmd by passing appropriate command line arguments to
it. Call buildwin.cmd without arguments to see what is available.
To disable certain components (e.g., NetSSL_OpenSSL or Data/MySQL) from the build,
edit the file named "components" and remove the respective lines.
Certain libraries, like NetSSL_OpenSSL, Crypto or Data/MySQL have dependencies
to other libraries. Since the build script does not know where to find the necessary
header files and import libraries, you have to either add the header file paths to
the INCLUDE environment variable and the library path to the LIB environment variable,
or you'll have to edit the buildwin.cmd script, where these environment variables can
be set as well.
In order to run the test suite and the samples, the top-most bin directory containing
the shared libraries must be in the PATH environment variable.
IMPORTANT NOTE: Please make sure that the path to the directory containing the
POCO C++ Libraries source tree does not contain spaces. Otherwise, the Microsoft
message compiler may fail when building the Foundation library.
BUILDING ON UNIX/LINUX/macOS
============================
For building on Unix platforms, the POCO C++ Libraries come with their own
build system. The build system is based on GNU Make 3.80 (or newer), with the help
from a few shell scripts. If you do not have GNU Make 3.80 (or later) installed on
your machine, you will need to download it from
http://directory.fsf.org/devel/build/make.html>,
build and install it prior to building the POCO C++ Libraries.
You can check the version of GNU Make installed on your system with
> gmake --version
or
> make --version
Once you have GNU Make up and running, the rest is quite simple.
To extract the sources and build all libraries, testsuites and samples, simply
> gunzip poco-X.Y.tar.gz
> tar -xf poco-X.Y.tar
> cd poco-X.Y
> ./configure
> gmake -s
See the configure script source for a list of possible options.
For starters, we recommend --no-tests and --no-samples, to reduce build times.
On a multicore or multiprocessor machine, use parallel makes to speed up
the build (make -j4).
Once you have successfully built POCO, you can install it
to /usr/local (or another directory specified as parameter
to configure --prefix=<path>):
> sudo gmake -s install
You can omit certain components from the build. For example, you might
want to omit Data/ODBC or Data/MySQL if you do not have the corresponding
third-party libraries (iodbc or unixodbc, mysqlclient) installed
on your system. To do this, use the --omit argument to configure:
> ./configure --omit=Data/ODBC,Data/MySQL
IMPORTANT: Make sure that the path to the build directory does not
contain symbolic links. Furthermore, on macOS (or other systems
with case insensitive filesystems), make sure that the characters in
the path have the correct case. Otherwise you'll get an error saying
"Current working directory not under $PROJECT_BASE.".
BUILDING ON QNX NEUTRINO
========================
For QNX Neutrino, the Unix build system (see the instructions above) is used.
You can use the build system to cross-compile for a target platform on a Solaris or
Linux host. Unfortunately, the Cygwin-based Windows host environment has some major
quirks that prevent the build system from working there. You can also use the
build system on a self-hosted QNX system. The default build configuration for QNX
(found in build/config/QNX) is for a self-hosted x86 platform. To specify another
target, edit the CCVER setting in the build configuration file. For example, to
compile for a PowerPC target, specify CCVER=3.3.1,gcc_ntoppcbe.
Service Pack 1 for QNX Neutrino 6.3 must be installed, otherwise compiling the
Foundation library will fail due to a problem with the <list> header in the
default (Dinkumware) C++ standard library.
When building on QNX, you might want to disable NetSSL_OpenSSL, Crypto and
some Data connectors, unless you have the necessary third party components
available:
> ./configure --omit=NetSSL_OpenSSL,Crypto,Data/ODBC,Data/MySQL
BUILDING FOR VXWORKS
====================
Please see the VxWorks Platform Notes in the Reference Documentation for
more information. The Reference Documentation can be found online
at <http://pocoproject.org/docs/>.
MORE INFORMATION
================
For more information, see the POCO C++ Libraries website
at <http://pocoproject.org>.