poco/README

This is the README file for the Applied Informatics C++ Portable Components.

In this document you will find a brief description of the directory layout,
as well as a description necessary steps to build the C++ Portable Components.

The Applied Informatics C++ Portable Components currently consist of four 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, etc.)
All libraries come with a test suite and a number of sample programs.

The directory layout is as follows:

build/                     the build system for Unix/OpenVMS 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

bin/                       all executables (dynamic link libraries on Windows)

doc/                       additional documentation

lib/                       all libraries (import 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/
        Foundation/        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/
        Foundation/        header files for the XML library
    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


DOCUMENTATION
=============

At this time, no online-browsable API documentation is available. Please refer to
the comments in the header files. API documentation in HTML format will be
provided with the 1.0 release.


BUILDING ON WINDOWS
===================

Microsoft Visual Studio 7.1 (2003) or 8.0 (2005) is required to build the C++ Portable Components
on Windows platforms. Solution and project files for both versions are included.
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 (or 2005) Command Prompt and cd to the directory where you have
extracted the C++ Portable Components sources. Then simply start the build_vs71.cmd (or
build_vs80.cmd, respectively) batch file. This will build all libraries, test suites and 
sample programs, in both debug and release versions. The dynamic link libraries will be 
placed in the top-most bin directory. The import libraries will be placed in the top-most lib 
directory. The test suite executables will be placed in the testsuite/bin directories.
The sample executables will be placed in the sample/*/bin directories.

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.

If you want to run the test suite or samples from within Visual Studio, we recommend that
you download and install the free Solution Build Environment for Visual Studio .NET 2003,
from <http://www.workspacewhiz.com/SolutionBuildEnvironmentReadme.html>.

You can then add the bin directory to the PATH environment variable in a .slnenv file,
using the following entry.

POCO_BASE=p:\poco
PATH=$(PATH);$(POCO_BASE)\bin

Of course you will have to change the path p:\poco so that it matches your environment.


BUILDING ON UNIX/LINUX/MAC OS X
===============================

For building on Unix platforms, the C++ Portable Components come with their own
build system. The build system is based on GNU Make 3.80, with the help from a few
shell scripts. If you do not have GNU Make 3.80 installed on your machine, you will
need to download it from <http://directory.fsf.org/devel/build/make.html>, build
and install it prior to building the C++ Portable Components.

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.
Before starting a build, you must define the environment variable POCO_BASE to point
to the directory where you have extracted the sources for the C++ Portable Components.
For example, if you have extracted the sources to /home/jdoe/poco-0.95, then you would
define POCO_BASE as follows (assuming you are using sh or bash)

> export POCO_BASE=/home/jdoe/poco-0.95

Once you have defined POCO_BASE, you are ready to go.
To build all libraries, testsuites and samples, simply

> cd $POCO_BASE
> gmake

NOTE: The global Makefile automatically sets POCO_BASE to the current working
directory if it is undefined. However, you must define POCO_BASE yourself if
you want to build only specific components (for example, the Foundation library,
a test suite or the samples).

To build on Mac OS X 10.4 with GCC 4.0, define the following environment variable:

> export POCO_CONFIG=Darwin8
> make


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.


BUILDING ON OPENVMS
===================

The C++ Portable Components come with their own build system for OpenVMS, implemented
by a bunch of DCL scripts. The scripts can be found in the build/vms directory.

To build the C++ Portable Components on OpenVMS, follow the following steps.

1) Download the .zip distribution of the C++ Portable Components

2) Unzip the archive
   $ unzip -aa poco-0_91_4.zip

3) Change the directory
   $ set def [.poco-0_01_4]

4) Create a lib directory
   $ create/dir [.lib]

5) Run the buildvms.com script
   $ @buildvms

This will build the debug versions of the libraries. To build the release
versions, use
   $ @buildvms -release


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

For more information, see the Applied Informatics C++ Portable Components website
at <http://poco.appinf.com>.


--
$Id: //poco/1.1.0/dist/README#2 $