# Introduction

# Getting Started With The POCO C++ Libraries

## 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.

Up-to-date Conan packages are available via Conan Center.

### 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 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 (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 Crypto require OpenSSL.
- Data/ODBC requires ODBC (Microsoft ODBC on Windows, unixODBC or iODBC on Unix/Linux)
- Data/MySQL requires the MySQL client.

#### OpenSSL

Unix/Linux

Most Unix/Linux systems 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 macOS, it's recommended to install OpenSSL via Homebrew.

    $ brew install openssl

Windows

On Windows, it is recommended to use one of the pre-built binary packages. A list is available on OpenSSL GitHub.

Shining Light Productions installer is well supported by CMake.

#### 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 iODBC or 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 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 using CMake

CMake is the official build system and can be used to build POCO C++ Libraries on any platform with any compiler. CMake is a meta build system and it generates native makefiles and workspaces that can be used in the compiler environment of your choice. For a quick overview see http://cgold.readthedocs.io/en/latest/overview/cmake-can.html

POCO C++ Libraries requires CMake 3.26 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 C++ Libraries using CMake.

Assuming the POCO C++ Libraries source is located in /path/to/poco directory and you like to build POCO C++ Libraries just type the following commands (Command parameters are all the same on any platform).

    $ cmake -H/path/to/poco -B/path/to/poco-build
    $ cmake --build /path/to/poco-build

This will build POCO C++ Libraries in a subdirectory poco-build. All files produced during build are located in this directory.

## Basic CMake parameters:

### Build Types

The following build types are available: * Debug (Debug build with no optimization) * Release (Release build with optimization) * RelWithDebInfo (Release build with debug info, default) * MinSizeRel (Release build with size optimisation)

By default, POCO is built with RelWithDebInfo.

For single-configuration generators (Makefile, Ninja), set build type at configure time:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_BUILD_TYPE=Debug
    $ cmake --build /path/to/poco-build

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_BUILD_TYPE=Release
    $ cmake --build /path/to/poco-build

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_BUILD_TYPE=RelWithDebInfo
    $ cmake --build /path/to/poco-build

For multi-configuration generators (Visual Studio, Xcode), set build type at build time:

    $ cmake -H/path/to/poco -B/path/to/poco-build
    $ cmake --build /path/to/poco-build --config Debug

    $ cmake -H/path/to/poco -B/path/to/poco-build
    $ cmake --build /path/to/poco-build --config Release

For more information see https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html

### Static vs Dynamic Libraries

By default, POCO builds dynamic (shared) libraries. To build static libraries, set BUILD_SHARED_LIBS=OFF:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DBUILD_SHARED_LIBS=OFF
    $ cmake --build /path/to/poco-build

To build static libraries with a specific build type:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release
    $ cmake --build /path/to/poco-build

On Windows with Visual Studio:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DBUILD_SHARED_LIBS=OFF
    $ cmake --build /path/to/poco-build --config Release

To use static runtime on Windows (/MT instead of /MD), also set POCO_MT=ON:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DBUILD_SHARED_LIBS=OFF -DPOCO_MT=ON
    $ cmake --build /path/to/poco-build --config Release

### Installation Path

Installation path of Poco defaults to /usr/local on UNIX and C:\Program Files\ on Windows.

You can change the path with following parameter: CMAKE_INSTALL_PREFIX=....

For example to install in /usr:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_INSTALL_PREFIX=/usr
    $ cmake --build /path/to/poco-build --install

This will install the poco libs in /usr/lib and the binaries in /usr/bin etc.

See also cmake output like:

    ....
    -- [cmake] Installation target path: /usr/local
    ....

For more information see https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html?highlight=cmake_install_prefix

### Compiler Flags

To set some additional compiler flags, you can use following parameters:

* CMAKE_C_FLAGS For C compiler * CMAKE_CXX_FLAGS For C++ compiler

For example:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_CXX_FLAGS=-fstack-protector
    $ cmake --build /path/to/poco-build

For default compile flags, see cmake output like:

    ...
    -- [cmake] Build with cxx flags:   -O2 -g -DNDEBUG
    -- [cmake] Build with c flags:     -O2 -g -DNDEBUG
    ...

For more information see https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html#variable:CMAKE_%3CLANG%3E_FLAGS

To use the compiler of your choice, you can use the following parameters:

- CMAKE_C_COMPILER C compiler
- CMAKE_CXX_COMPILER C++ compiler

For example to use the clang compiler, execute following cmake command:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++
    $ cmake --build /path/to/poco-build

To cross compile POCO C++ Libraries for another architecture/device you should have a cmake toolchain file and execute following command:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchainfile
    $ cmake --build /path/to/poco-build

See https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html for more information.

## Poco special build parameters:

POCO C++ Libraries allows you to set some build time options. As an example: to disable the SevenZip support type the following command:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DENABLE_SEVENZIP=OFF
    $ cmake --build /path/to/poco-build

Here is an overview of POCO build options:

- ENABLE_XML Set to OFF|ON (default is ON) to build XML support library
- ENABLE_JSON Set to OFF|ON (default is ON) to build JSON support library
- ENABLE_NET Set to OFF|ON (default is ON) to build Net support library
- ENABLE_NETSSL Set to OFF|ON (default is ON if OpenSSL found) to build NetSSL support library
- ENABLE_CRYPTO Set to OFF|ON (default is ON if OpenSSL found) to build Crypto support library
- ENABLE_JWT Set to OFF|ON (default is ON if OpenSSL found) to build JWT (JSON Web Token) library
- ENABLE_DATA Set to OFF|ON (default is ON) to build Data support library
- ENABLE_DATA_SQLITE Set to OFF|ON (default is ON) to build Data SQLite support library
- ENABLE_DATA_MYSQL Set to OFF|ON (default is ON if MySQL found) to build Data MySQL or MariaDB support library
- ENABLE_DATA_POSTGRESQL Set to OFF|ON (default is ON if PostgreSQL found) to build Data PostgreSQL support library
- ENABLE_DATA_ODBC Set to OFF|ON (default is ON if ODBC found) to build Data ODBC support library
- ENABLE_MONGODB Set to OFF|ON (default is ON) to build MongoDB support library
- ENABLE_REDIS Set to OFF|ON (default is ON) to build Redis support library
- ENABLE_PDF Set to OFF|ON (default is OFF) to build PDF support library
- ENABLE_UTIL Set to OFF|ON (default is ON) to build Util support library
- ENABLE_ZIP Set to OFF|ON (default is ON) to build Zip support library
- ENABLE_SEVENZIP Set to OFF|ON (default is OFF) to build SevenZip support library
- ENABLE_APACHECONNECTOR Set to OFF|ON (default is ON if Apache/APR found) to build ApacheConnector support library
- ENABLE_CPPPARSER Set to OFF|ON (default is OFF) to build C++ parser library
- ENABLE_ENCODINGS Set to OFF|ON (default is ON) to build Encodings library
- ENABLE_ENCODINGS_COMPILER Set to OFF|ON (default is OFF) to build Encodings Compiler
- ENABLE_PAGECOMPILER Set to OFF|ON (default is ON) to build PageCompiler
- ENABLE_PAGECOMPILER_FILE2PAGE Set to OFF|ON (default is ON) to build File2Page
- ENABLE_POCODOC Set to OFF|ON (default is OFF) to build Poco Documentation Generator
- ENABLE_TESTS Set to OFF|ON (default is OFF) to build unit tests
- ENABLE_SAMPLES Set to OFF|ON (default is OFF) to build samples
- ENABLE_ACTIVERECORD Set to OFF|ON (default is ON) to build ActiveRecord library
- ENABLE_ACTIVERECORD_COMPILER Set to OFF|ON (default is ON) to build ActiveRecord Compiler
- ENABLE_PROMETHEUS Set to OFF|ON (default is ON) to build Prometheus library
- ENABLE_MODULES Set to OFF|ON (default is OFF) to build C++ modules (requires C++20 and CMake 3.28+)
- ENABLE_COMPILER_WARNINGS Set to OFF|ON (default is OFF) to enable compiler warnings
- POCO_UNBUNDLED Set to OFF|ON (default is OFF) to control linking dependencies as external
- POCO_ENABLE_CPP20 Set to OFF|ON (default is ON) to build with C++20 standard

Windows only parameters:

- POCO_MT Set to OFF|ON (default is OFF) to control build of POCO as /MT instead of /MD
- ENABLE_NETSSL_WIN Set to OFF|ON (default is OFF) to build NetSSL support library using Windows SSL

You can also see and enable or disable available options by executing the following command:

    $ cmake-gui /path/to/poco-build

or for console only:

    $ ccmake /path/to/poco-build

POCO C++ Libraries options are prefixed with ENABLE_. (This will be changed in POCO 2.x.x to POCO_)

## Third-party library location

If a third-party library is not installed in a default location, CMake will fail to run. The following parameters exist to set additional search paths for cmake to find third-party libraries:

To find PostgreSQL:

- PostgreSQL_ROOT_DIR - Set root installation path where to find include path and libraries of PostgreSQL or
- PostgreSQL_ROOT_INCLUDE_DIRS - Set include paths where to find PostgreSQL headers
- PostgreSQL_ROOT_LIBRARY_DIRS - Set library paths where to find PostgreSQL libraries

To find ODBC:

- ODBC_ROOT_DIR - Set root installation path where to find include path and libraries of ODBC or
- ODBC_ROOT_INCLUDE_DIRS - Set include paths where to find ODBC headers
- ODBC_ROOT_LIBRARY_DIRS - Set library paths where to find ODBC libraries

To find MySQL or MariaDB:

- MYSQL_ROOT_DIR - Set root installation path where to find include path and libraries of MySQL or MariaDB or
- MYSQL_ROOT_INCLUDE_DIRS - Set include paths where to find MySQL or MariaDB headers
- MYSQL_ROOT_LIBRARY_DIRS - Set library paths where to find MySQL or MariaDB libraries

- APRUTIL_ROOT_DIR - Set root installation path where to find include path and libraries of apr util or
- APRUTIL_ROOT_INCLUDE_DIRS - Set include paths where to find apr util headers
- APRUTIL_ROOT_LIBRARY_DIRS - Set library paths where to find apr util libraries

- APR_ROOT_DIR - Set root installation path where to find include path and libraries of apr or
- APR_ROOT_INCLUDE_DIRS - Set include paths where to find apr headers
- APR_ROOT_LIBRARY_DIRS - Set library paths where to find apr libraries

- APACHE2_ROOT_DIR - Set root installation path where to find include path and libraries of apache2 or
- APACHE2_ROOT_INCLUDE_DIRS - Set include paths where to find apache2 headers

For example set installation path of MySQL:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DMYSQL_ROOT_DIR=/usr/local/mysql
    $ cmake --build /path/to/poco-build

or

    $ cmake -H/path/to/poco -B/path/to/poco-build -DMYSQL_ROOT_INCLUDE_DIRS=/usr/local/mysql/include/mysql -DMYSQL_ROOT_LIBRARY_DIRS=/usr/local/lib/mysql
    $ cmake --build /path/to/poco-build

## How to use POCO in your cmake project:

To use POCO C++ Libraries in your CMake project, add the following line in your project, for example to use Crypto:

    find_package(Poco REQUIRED Crypto)
    ....
    target_link_libraries(yourTargetName ... Poco::Crypto)

If you get an error like 'By not providing "FindPoco.cmake"', then you should set CMAKE_PREFIX_PATH to the installation directory of your POCO C++ Libraries. For example:

    $ cmake -H/path/to/yourProject -B/path/to/yourProject-build -DCMAKE_PREFIX_PATH=/path/to/installationOf/poco

## Some other Hints:

For a faster build, use ninja as build system. See https://ninja-build.org/ For example on Ubuntu execute following commands:

    $ sudo apt-get install ninja-build

This installs the ninja command. To use ninja-build execute following cmake commands:

    $ cmake -H/path/to/poco -B/path/to/poco-build -GNinja
    $ cmake --build /path/to/poco-build --target all

See https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html for other generators.

To enable verbose output from Makefile builds, execute following cmake commands:

    $ cmake -H/path/to/poco -B/path/to/poco-build -DCMAKE_VERBOSE_MAKEFILE=ON
    $ cmake --build /path/to/poco-build --target all

For more information about CMake, see:

$ cmake —help-full https://cmake.org/cmake/help/latest/ http://cgold.readthedocs.io/en/latest/index.html

### Building On Windows

Microsoft Visual Studio 2019 or newer is required to build the POCO C++ Libraries on Windows platforms. Use CMake to generate Visual Studio solutions and build. 64-bit (x64) builds are supported as well.

Certain libraries, like NetSSL_OpenSSL, Crypto or Data/MySQL have dependencies to other libraries. Use vcpkg to install the required packages.

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/macOS

Use CMake to build the POCO C++ Libraries on Unix, Linux and macOS.

Alternatively, the POCO C++ Libraries come with their own GNU Make based build system. The build system requires GNU Make 3.80 or newer.

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
    $ make -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

## Tutorials And Sample Code

Introductory documentation consisting of various documents and tutorials in the form of slide decks can be found at the 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 CMakeLists.txt files to see how to configure your project.