Repository: pocoproject/poco

Stars: 9400

README.md Copy Chapter

![alt text][logo]


POCO (Portable Components) C++ Libraries are: Copy Section

- A collection of C++ class libraries, conceptually similar to the Java Class Library or the .NET Framework.
- Focused on solutions to frequently-encountered practical problems.
- Focused on "internet-age" network-centric applications.
- Written in efficient, modern, 100% ANSI/ISO Standard C++.
- Based on and complementing the C++ Standard Library/STL.
- Highly portable and available on many different platforms, from embedded to server.
- Open Source, licensed under the Boost Software License.

![alt text][overview]

To start using POCO, see the Guided Tour
and Getting Started documents.

Quick Start (with CMake) Copy Chapter

Prerequisites Copy Section

- CMake 3.26 or newer
- A C++17 compiler (Visual C++ 2019, GCC 8.0, Clang 5, or newer)
- C++20 is supported and recommended; some features are only available with C++20
- OpenSSL 1.1.1 or newer headers and libraries (optional, but recommended)
- MySQL, PostgreSQL, ODBC, and Apache/APR client libraries (optional)
- C++20, CMake 3.28 or later, and Ninja (for C++ modules)

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. For example, via Debian APT:

$ sudo apt-get install openssl libssl-dev

On macOS, the easiest way to install OpenSSL is via Homebrew:

$ brew install openssl

On Windows, the easiest way to install OpenSSL is via
WinGet:

$ winget install --id -e ShiningLight.OpenSSL.Dev

On Windows, POCO can also use the native Windows TLS APIs (SChannel).

Installing All Dependencies (Linux and macOS) Copy Section

All dependencies can be installed with the following commands:

#### Debian Linux (including Ubuntu and Raspbian)

$ sudo apt-get -y update && sudo apt-get -y install git g++ cmake libssl-dev libmysqlclient-dev libpq-dev

#### RedHat Linux

$ sudo dnf install -y git gcc-c++ cmake openssl-devel mysql-devel postgresql-devel

#### Arch Linux

$ sudo pacman -Syu --noconfirm git gcc make cmake openssl mariadb-libs postgresql-libs

#### macOS (with Homebrew)

$ brew install cmake openssl mysql-client libpq

#### Windows (with WinGet)

$ winget install --id -e Git.Git LLVM.LLVM Kitware.CMake ShiningLight.OpenSSL.Dev PostgreSQL.PostgreSQL Oracle.MySQL Microsoft.msodbcsql

Building with CMake (Linux, macOS, Windows) Copy Section

CMake (version 3.26 or newer) is the official build system for
building the POCO C++ Libraries.

$ git clone -b main https://github.com/pocoproject/poco.git
$ cd poco
$ mkdir cmake-build
$ cd cmake-build
$ cmake ..
$ cmake --build . --config Release

On macOS, it's necessary to tell CMake where to find the OpenSSL headers
and libraries by setting the OPENSSL_ROOT_DIR CMake variable.
For example, if OpenSSL has been installed with Homebrew,
the cmake invocation becomes:

$ cmake .. -DOPENSSL_ROOT_DIR=/opt/homebrew/opt/openssl@3

On Intel Macs, use /usr/local/opt/openssl@3 instead.

Similarly, the locations of other external libraries can be specified:

$ cmake .. -DOPENSSL_ROOT_DIR=/opt/homebrew/opt/openssl@3 -DMYSQL_ROOT_DIR=/opt/homebrew/opt/mysql-client -DPostgreSQL_ROOT_DIR=/opt/homebrew/opt/libpq

Other common ways of building with CMake (e.g., cmake-gui) will also work.

There are also a number of project-specific CMake variables that can be changed.

#### Reducing Binary Size

The default build includes all components and features. For size-constrained
deployments, consider the following options:

- Build only needed components (-DPOCO_MINIMAL_BUILD=ON
-DENABLE_<COMPONENT>=ON): Only build the specific libraries you need.

- Disable FastLogger (-DENABLE_FASTLOGGER=OFF): The Quill-based
high-performance logger adds ~290 KB to Foundation. Disable it if
you don't need sub-microsecond logging.

- Enable hidden visibility (-DCMAKE_CXX_VISIBILITY_PRESET=hidden
-DCMAKE_VISIBILITY_INLINES_HIDDEN=ON): Allows the linker to discard
unreferenced internal symbols from shared libraries.

Example combining all options:

$ cmake .. -DPOCO_MINIMAL_BUILD=ON -DENABLE_FOUNDATION=ON -DENABLE_NET=ON \
  -DENABLE_UTIL=ON -DENABLE_FASTLOGGER=OFF \
  -DCMAKE_CXX_VISIBILITY_PRESET=hidden -DCMAKE_VISIBILITY_INLINES_HIDDEN=ON

#### Cross-Compiling

With a proper CMake toolchain file (specified via the CMAKE_TOOLCHAIN_FILE CMake variable),
the POCO C++ Libraries can be cross-compiled for embedded Linux systems:

$ cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/mytoolchain.cmake -DCMAKE_INSTALL_PREFIX=/path/to/target

#### Installing

The POCO C++ Libraries headers and libraries can optionally be installed by building the install target.

$ sudo cmake --build . --target install

The default install location is /usr/local/ on Linux and macOS and
C:\Program Files\ on Windows and can be overridden by setting
the CMAKE_INSTALL_PREFIX CMake variable.

#### Building and Installing - Using vcpkg

You can download and install poco using the vcpkg dependency manager:

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

#### Building and Installing - Using Conan

You can download and install poco using the Conan
package manager. It needs to be installed first.

You can install Poco libraries from Conan Center:

$ conan install --requires=poco/1.15.2

Or, you can download Poco recipe and build locally:

$ conan install --requires=poco/1.15.2 --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
on the Conan Center Index repository.

Building Without CMake Copy Section

If you do not want to or cannot use CMake, POCO can also be built with GNU Make
(Linux, macOS and other supported Unix platforms).

Please refer to the documentation for more information.

Getting POCO via a Package Manager Copy Section

POCO can also be obtained via different package managers.

Community and Contributing Copy Chapter

POCO has an active user and contributing community, please visit our website and blog.
Answers to POCO-related questions can also be found on Stack Overflow.

Please see CONTRIBUTING for submitting contributions, bug reports, feature requests or security issues.

POCO vs. Boost Copy Section

In regards to Boost, in spite of some functional overlapping,
POCO is best thought of as a Boost complement (rather than replacement).
Side-by-side use of Boost and POCO is a very common occurrence.

[overview]: doc/images/overview.png "Poco Overview"
[logo]: doc/images/logo.png "Poco Logo"