mirror of
https://github.com/pocoproject/poco.git
synced 2024-12-21 22:47:58 +01:00
358 lines
15 KiB
Plaintext
358 lines
15 KiB
Plaintext
Getting Started With The POCO C++ Libraries
|
||
AAAIntroduction
|
||
|
||
!!!Welcome
|
||
|
||
Thank you for downloading the POCO C++ Libraries and welcome to the growing community of POCO C++ Libraries
|
||
users. This document will help you in getting a smooth ride while installing and setting up the
|
||
POCO C++ Libraries and going the first steps with the software.
|
||
|
||
|
||
!!!Setting Up The POCO C++ Libraries
|
||
|
||
The POCO C++ Libraries are delivered in full source code only. Due to the
|
||
large number of possible build configurations, no binary releases are provided
|
||
from the project maintainers.
|
||
This means that you have to build the libraries and tools before you can use them the first time.
|
||
|
||
<*Note: There are binary releases available as installation packages for
|
||
various operating systems (e.g., Debian Linux, Ubuntu Linux, OpenBSD,
|
||
OpenWRT, etc.). However, these packages are not maintained by the core
|
||
team and may not always be up to date.*>
|
||
|
||
|
||
!!Source Code Distribution Format
|
||
|
||
The source code for the POCO C++ Libraries is delivered in a ZIP file
|
||
for Windows users and/or in a compressed TAR file (.tar.gz or .tar.bz2)
|
||
for Unix/Linux users. Both archives contain the same files, the only
|
||
difference is that all text files in the ZIP files have line endings
|
||
suitable for Windows (CR-LF), while the text files in the TAR file have
|
||
line endings suitable for Unix/Linux (LF only).
|
||
All libraries and tools follow a common convention for the directory
|
||
layout. This directory layout is shown below.
|
||
|
||
build/ the build system for Unix/OpenVMS and additional utility scripts
|
||
config/ build configurations for various Unix platforms
|
||
rules/ common build rules for all platforms
|
||
scripts/ build and utility scripts
|
||
vms/ OpenVMS build system scripts
|
||
vxconfig/ VxWorks build configurations
|
||
|
||
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 (Basic or Complete
|
||
Edition), there may be other libraries as well (such as Data, Crypto,
|
||
NetSSL_OpenSSL and Zip).
|
||
|
||
|
||
!!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.
|
||
|
||
|
||
!OpenSSL
|
||
|
||
Most Unix/Linux systems (including Mac OS X) already have OpenSSL
|
||
preinstalled, or OpenSSL can be easily installed using the system’s
|
||
package management facility. For example, on Ubuntu (or other
|
||
Debian-based Linux distributions) you can type
|
||
|
||
$ sudo apt-get install openssl libssl-dev
|
||
----
|
||
|
||
to install the necessary packages.
|
||
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.
|
||
|
||
On Windows, OpenSSL binaries come bundled with the POCO distribution
|
||
in the %POCO_BASE%\openssl directory. Visual Studio solutions for
|
||
libraries depending on OpenSSL will look for headers in the
|
||
%POCO_BASE%\openssl\include directory. During the build of the Crypto
|
||
library, the pre-built OpenSSL binaries will be copied into
|
||
%POCO_BASE%\bin[64] and \lib[64] directories through a VS Pre-Build Event.
|
||
To build your own version of OpenSSL, run
|
||
|
||
%POCO_BASE%\openssl\buildall.cmd
|
||
|
||
This script will download all the prerequisites for the OpenSSL build
|
||
and binaries will be under the %POCO_BASE%\openssl directory.
|
||
|
||
If you wish to use the externally built OpenSSL binaries,
|
||
the easiest way to install OpenSSL on Windows is to use a binary
|
||
(prebuild) release, for example the one from Shining Light
|
||
Productions that comes with a Windows installer
|
||
(http://www.slproweb.com/products/Win32OpenSSL.html).
|
||
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. To disable
|
||
internal automatic linking of supplied binaries, define POCO_EXTERNAL_OPENSSL
|
||
in your build environment. Alternatively, you can either rename your binaries,
|
||
or edit the %POCO_BASE%\Crypto\include\Poco\Crypto\Crypto.h
|
||
file if the names of the OpenSSL libraries from your build differ from
|
||
the names used thereof (look for "#pragma comment" lines in Crypto.h).
|
||
|
||
|
||
!ODBC
|
||
|
||
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 installed.
|
||
On Unix/Linux platforms, you can use [[http://www.iodbc.org/ iODBC]]
|
||
(preinstalled on Mac OS X) or [[http://www.unixodbc.org/ unixODBC]. On
|
||
Linux, use your distribution's package management system to install the
|
||
necessary libraries and header files. For example, on Ubuntu, type
|
||
|
||
$ sudo apt-get install libiodbc2 libiodbc2-dev
|
||
----
|
||
|
||
to install the iODBC library and header files.
|
||
|
||
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.
|
||
|
||
|
||
!MySQL Client
|
||
|
||
The Data library requires the [[http://dev.mysql.com MySQL]] client
|
||
libraries and header files if you want to build the MySQL connector
|
||
(which is the default). On Windows platforms, use the MySQL client
|
||
installer to install the necessary files. On Unix/Linux platforms, use
|
||
the package management system of your choice to install the necessary
|
||
files. Alternatively, you can of course build MySQL yourself from
|
||
source.
|
||
|
||
|
||
!!Building On Windows
|
||
|
||
Microsoft Visual Studio 7.1 (2003), 8.0 (2005), 9.0 (2008) or 10.0
|
||
(2010) is required to build the POCO C++ Libraries on Windows platforms.
|
||
Solution and project files for all versions are included. For Visual
|
||
Studio 2008, 2010 and 2012, 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 .NET 2003/2005/2008/2010 Command
|
||
Prompt and go (<[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 (71, 80, 90, 100 or 110). 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. Build environment is set up by the buildwin.cmd; to avoid
|
||
build problems, it is recommended to start the build in a clean command
|
||
prompt console, i.e. not in the one provided by Visual Studio for 32/64-bit
|
||
builds (although those will work fine if used appropriately for the right
|
||
32/64-bit build type).
|
||
|
||
Visual Studio Express builds have limited support. In particular, the
|
||
coupling of the TesTSuite with MFC on Windows is the obstacle for clean
|
||
ful VS Express builds. There are plans to alleviate this in the future
|
||
relalses.
|
||
|
||
To disable certain components (e.g., NetSSL_OpenSSL or Data/MySQL) from
|
||
the build, edit the text file named <*components*> in the distribution
|
||
root directory and remove or comment 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 resulting shared libraries must be in the PATH
|
||
environment variable.
|
||
|
||
|
||
!!Building On Unix/Linux/Mac OS X
|
||
|
||
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 newer) installed on your machine, you will need to download it from
|
||
http://directory.fsf.org/devel/build/make.html and
|
||
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
|
||
----
|
||
|
||
For help, either invoke
|
||
|
||
$ ./configure --help
|
||
----
|
||
|
||
Alternatively, you can read 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 Mac OS X (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 using CMake
|
||
|
||
As an alternative to the platform specific Makefiles and Solutions, CMake can be used
|
||
to do build Poco. CMake is a cross platform Makefile generator that also supports
|
||
Microsoft Visual Studio and Apple Xcode.
|
||
Poco requires CMake 3.0 or higher. Static binaries for many platforms can be downloaded from http://www.cmake.org/
|
||
|
||
CMake supports out of source builds and this is the recommended way to build Poco using CMake.
|
||
|
||
Assuming you are currently in the Poco source directory on a Unix machine
|
||
and you like to build Poco with the generated Makefiles just type the following commands.
|
||
|
||
$ mkdir cmake_build
|
||
$ cd cmake_build
|
||
$ cmake ..
|
||
$ make
|
||
|
||
This will build Poco in a subdirectory <*cmake_build*>. All files produced during build are located in this directory.
|
||
|
||
CMake allows you to set some build time options. As an example: to disable the SevenZip support
|
||
type the following command:
|
||
|
||
$ cmake -DENABLE_SEVENZIP=OFF ..
|
||
|
||
Similar options are available for other components (see: CMakeLists.txt).
|
||
|
||
|
||
!!!Tutorials And Sample Code
|
||
|
||
Introductory documentation consisting of various documents and tutorials
|
||
in the form of slide decks can be found at the
|
||
[[http://pocoproject.org/documentation/ POCO C++ Libraries Documentation]] page.
|
||
|
||
Sample applications demonstrating the various features of the POCO C++
|
||
Libraries are delivered with the source code. Every library's source
|
||
code directory
|
||
has a <*samples*> directory containing various sample applications.
|
||
|
||
When building the sample applications on platforms using the gmake-based
|
||
build system, please make sure that the environment variable
|
||
<[POCO_BASE]> contains
|
||
the path to the POCO C++ Libraries source tree root directory.
|
||
|
||
|
||
!!!Creating Your Own POCO-based Applications
|
||
|
||
The best way to create your first POCO-based application is by copying
|
||
one of the sample projects and making the desired changes. Examine the
|
||
project files and Makefiles to see what compiler options must be set for
|
||
your specific platform.
|