generic-library/poco
1
0
Fork 0
mirror of https://github.com/pocoproject/poco.git synced 2024-12-13 10:32:57 +01:00
Code Issues Projects Releases Wiki Activity

updated README and getting started doc

Browse Source
This commit is contained in:
Guenter Obiltschnig 2017-11-10 12:45:40 +01:00
parent 7829aca793
commit f3e97a523d
2 changed files with 121 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
README
View File

@ -22,6 +22,8 @@ build/ the build system for Unix and additional utility scri
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)
@ -95,6 +97,7 @@ Most Unix/Linux systems already have OpenSSL preinstalled. 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 (e.g., apt-get install openssl libssl-dev).
On macOS, install OpenSSL via Homebrew (brew install openssl).
The easiest way to install OpenSSL on Windows is to get the pre-built
libraries from the pocoproject/openssl Git repository at
@ -127,6 +130,26 @@ In this case, please edit the Makefile in Data/ODBC and/or Data/MySQL
accordingly.
BUILDING WITH CMAKE
===================
The POCO C++ Libraries support CMake as a build system 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 ..
$ make -s -j (or build the generated Visual Studio solution on Windows)
If you cannot or do not want to build with CMake, there are other options,
described in the following.
BUILDING ON WINDOWS
===================
@ -246,23 +269,6 @@ available:
> ./configure --omit=NetSSL_OpenSSL,Crypto,Data/ODBC,Data/MySQL
BUILDING WITH CMAKE
===================
The POCO C++ Libraries support CMake as a build system 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 ..
$ make -s -j (or build the generated Visual Studio solution on Windows)
BUILDING FOR VXWORKS
====================

185
doc/00200-GettingStarted.page
View File

@ -4,7 +4,7 @@ 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
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.
@ -12,14 +12,17 @@ POCO C++ Libraries and going the first steps with the software.
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.
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
@ -32,28 +35,29 @@ 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
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
vms/ OpenVMS build system 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
@ -62,7 +66,7 @@ layout. This directory layout is shown below.
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/
@ -74,7 +78,7 @@ layout. This directory layout is shown below.
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/
@ -97,16 +101,16 @@ 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
- Data/ODBC requires ODBC
(Microsoft ODBC on Windows, unixODBC or iODBC on Unix/Linux)
- Data/MySQL requires the MySQL client.
!OpenSSL
!!Unix/Linux
<*Unix/Linux*>
Most Unix/Linux systems (including Mac OS X) already have OpenSSL
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
@ -119,7 +123,13 @@ 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.
!!Windows
On macOS, it's recommended to install OpenSSL via Homebrew.
$ brew install openssl
---
<*Windows*>
On Windows, there are three options:
@ -128,7 +138,7 @@ On Windows, there are three options:
- Use a third-party pre-built OpenSSL
!!! POCO pre-built OpenSSL binaries
POCO pre-built OpenSSL binaries
OpenSSL binaries (version 1.1.0) built with VS 2013 are available for download at:
@ -140,34 +150,38 @@ entire directory to C:\%POCO_BASE%\openssl\
Or, %POCO_BASE%\openssl directory can be deleted and openssl
repository cloned:
cd %POCO_BASE%
rmdir /s /q openssl
git clone https://github.com/pocoproject/openssl
$ 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 identically (libcrypto and libssl).
!!! Build OpenSSL using scripts from POCO distribution package
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.
!!!!Prerequisites
Prerequisites
- 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]
Usage
!!!!Example
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 VS 2013:
C:\%POCO_BASE%\openssl\build.ps1 -openssl_release 1.1.0 -vs_version 120 -config release -platform x64 -library shared
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 buil OpenSSL in C:\%POCO_BASE%\openssl\VS_120 directory; the built OpenSSL
@ -176,20 +190,19 @@ binaries can be linked from EXEs and DLLs built with VS 2008-2017.
Pre-generated POCO Visual Studio projects are configured to use headers and
libraries from VS_120 directory.
!!! Use a third-party pre-built OpenSSL
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
(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
(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.
!!!NOTE:
To disable internal automatic linking of supplied binaries in pre-generated
NOTE: To disable internal automatic linking of supplied binaries in pre-generated
POCO VS projects, 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
@ -203,12 +216,12 @@ 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
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.
@ -230,55 +243,80 @@ 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. 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).
If you cannot or do not want to build with CMake, there are other options,
described in the following.
!!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.
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 .NET 2003/2005/2008/2010 Command
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 (71, 80, 90, 100 or 110). You
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
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
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.
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
!!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
(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
@ -327,8 +365,8 @@ on your system. To do this, use the <[--omit]> argument to configure:
----
<*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
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.".*>
@ -357,33 +395,6 @@ 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