README

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/                     64-bit executables (and DLLs) on Windows

doc/                       additional documentation

lib/                       all libraries (import libraries on Windows)
lib64/                     64-bit libraries on Windows

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 <https://docs.pocoproject.org/>.


EXTERNAL DEPENDENCIES
=====================

The following libraries require third-party software (header files and
libraries) being installed to build properly:

- NetSSL_OpenSSL, Crypto and JWT require OpenSSL.
- Data/ODBC requires ODBC
  (Microsoft ODBC on Windows, unixODBC or iODBC on Unix/Linux)
- Data/MySQL requires the MySQL or MariaDB client library.
- Data/PostgreSQL requires the PostgreSQL client library (libpq).

Most Unix/Linux systems already have OpenSSL preinstalled. If your system
does not have OpenSSL, please get it from https://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).
On Windows, OpenSSL can be installed with vcpkg, or through WinGet
(winget install -e --id ShiningLight.OpenSSL.Dev).

Depending on where you have installed the OpenSSL libraries,
you might have to add the necessary paths to the INCLUDE and LIB
environment variables, or set OPENSSL_ROOT_DIR when using CMake.

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
===================

CMake is the official build system for the POCO C++ Libraries 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 ..
$ cmake --build . --config Release


BUILDING - USING VCPKG
======================

You can download and install poco using the vcpkg (https://vcpkg.io)
dependency manager:

$ git clone https://github.com/Microsoft/vcpkg.git
$ cd vcpkg
$ ./bootstrap-vcpkg.sh
$ ./vcpkg integrate install
$ ./vcpkg install poco

The Poco port in vcpkg is kept up to date by Microsoft team members and community contributors.
If the version is out of date, please create an issue or pull request
(https://github.com/Microsoft/vcpkg) on the vcpkg repository.


BUILDING - USING CONAN
======================

You can download and install poco using the Conan (https://github.com/conan-io/conan)
package manager. It needs to be installed (https://conan.io/downloads.html) first.

You can install Poco libraries from Conan Center (https://conan.io/center.html):

$ conan install --requires=poco/1.15.0

Or, you can download Poco recipe and build locally:

$ conan install --requires=poco/1.15.0 --build=poco

The Poco recipe and packages in Conan Center are kept up to date by Conan team members and community contributors.
If the version is out of date, or you detect any wrong behavior, please create an issue or pull request
(https://github.com/conan-io/conan-center-index) on the Conan Center Index repository.


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.

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


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 <https://docs.pocoproject.org/>.


MORE INFORMATION
================

For more information, see the POCO C++ Libraries website
at <https://pocoproject.org>.