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.*> Up-to-date [[https://conan.io Conan]] packages are available via [[https://bintray.com/pocoproject/conan/Poco%3Apocoproject Bintray]]. !!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 Crypt 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, there are three options: - Use POCO pre-built OpenSSL binaries (simplest and recommended) - Build OpenSSL using scripts from POCO distribution package - Use a third-party pre-built OpenSSL <*POCO pre-built OpenSSL binaries*> OpenSSL binaries (version 1.1.0) built with Visual Studio 2013 are available for [[https://github.com/pocoproject/openssl/tree/master/build download]]. In case you are using pre-built binaries, please make sure to copy the entire directory to <*C:\%POCO_BASE%\openssl\*>. Or, %POCO_BASE%\openssl directory can be deleted (if existing) and POCO openssl github repository cloned into it: $ cd %POCO_BASE% $ rmdir /s /q openssl $ git clone https://github.com/pocoproject/openssl All libraries are located in their proper folders (eg. <*win64/bin/debug/*>), and all are named accordingly (<*libcrypto[mt[d]]*> and <*libssl[mt[d]]*>). <*Build OpenSSL using scripts from POCO distribution package*> Alternatively, if you choose to build your own OpenSSL, POCO C++ Libraries distribution package comes with scripts to build OpenSSL on Windows operating system. This requires Windows PowerShell. Usage: C:\%POCO_BASE%\openssl\build.ps1 [-openssl_release 1.0.0 | 1.1.0] [-vs_version 150 | 140 | 120 | 110 | 100 | 90] [-config release | debug | both] [-platform Win32 | x64] [-library shared | static] ---- Example: Building OpenSSL 1.1.0, DLL release build for x64 with Visual Studio 2013: C:\%POCO_BASE%\openssl\build.ps1 -openssl_release 1.1.0 -vs_version 120 -config release -platform x64 -library shared ---- The above command will download all the necessary packages (perl, nasm, etc) and build OpenSSL in <*C:\%POCO_BASE%\openssl\build*> directory; the built OpenSSL binaries can be linked from EXEs and DLLs built with Visual Studio 2008 to 2017. Pre-generated POCO Visual Studio projects are configured to use headers and libraries from <*C:\%POCO_BASE%\openssl\build*> directory. <*Use a third-party pre-built OpenSSL*> Yet another 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. You might also have to edit the project settings if the names of the OpenSSL libraries from your build differ from the names used in the project files. !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]] 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 using CMake As an alternative to the platform specific Makefiles and Solutions, CMake can be used to do build POCO C++ Libraries on any platform with any compiler. CMake is a meta build system and it generate 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.2 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 --target all This will build POCO C++ Libraries in a subdirectory <*poco-build*>. All files produced during build are located in this directory. 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 --target all Similar options are available for other components. To see and enable or disable available options execute 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_*>) To use POCO C++ Libraries in your cmake project, add following line in your project for example to use crypto: find_package(Poco REQUIRED PocoCrypto) .... 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: To use the compiler of your choice for example 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 --target all 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 --target all See https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html for more information. 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 install <*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 Some more infos 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 2008 or newer is required to build the POCO C++ Libraries on Windows platforms. Solution and project files for all versions 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 2008 (or 2010, 2013, etc.) 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 (90, 100, 110, ... 150). 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). 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/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 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=]>): $ 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 <**> 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 [[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.