This file is part of the pdr/pdx project.
Copyright (C) 2010 Torsten Mueller, Bern, Switzerland

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.



INSTALL - pdr/pdx
=================

1) Requirements
---------------
pdr and pdx depend on the following:

- boost C++ library 1.43
- POCO C++ framework 1.36p2
- optional: GNU readline and history libraries
- optional: libboard C++ library 0.8.8
- optional: Cairo C library 1.8.10

The versions above are those the applications have been developped and
tested with. You can try other versions before you install anything
else. boost 1.39 and POCO 1.35 will also fit.

POCO allows to download two different editions, the Economy and the
Complete Edition. We need the Complete Edition because of the database
components. If you want to use a MySQL server you need to install the
MySQL development sources before you compile POCO, otherwise POCO's
Data/MySQL component will fail. However, POCO's Data/SQLite conponent
will compile and run out of the box. You do not need to install SQLite
itself for pdr/pdx but it could be very handy later at runtime, for
viewing or manipulating data in the case of input errors. I recommend
this.

libboard can cause errors on some compilers because of a missing
header for sprintf(). In this case you will have to add <cstdio>
manually in one or two of it's source files, then it will compile
completely.

Note the linkage tables in the platform dependend sections 2a and 2b!


2a) Building on Unix-like systems
---------------------------------
The build process is configured in Makefile. There are no other steps
to be done before, especially there's no configure script.

The Makefile expects the libraries to be shared:

		shared		static
boost		x		?
POCO		x		?
readline	x		?
history		x		?
libboard	x		?
libcairo	x		?

? means you can try to use static versions. Change the library names
in the Makefile for this.

Then do the following steps:

a) set up the Makefile

The Makefile contains at it's beginning some defines to control
several aspects of building the applications, especially the use of
database engines and graphics libraries. Set these defines according
to your needs. These defines have the following meanings:

DEBUG		create debugable executables

USE_SQLITE	make pdr and pdx able to use SQLite databases

USE_MYSQL	make pdr and pdx able to use MySQL databases

USE_READLINE	use the readline library in interactive modes

USE_BOARD	make pdx able to create svg images

USE_CAIRO	make pdx able to create png images

USE_SQLITE and USE_MYSQL can be used together - so the resulting
executable will be able to run on both databases. In the same way
USE_BOARD and USE_CAIRO can be used together to support both image
types.

If you later want to install the applications using "make install"
check the installation path. Default is /usr/local.

b) make clean

Normally this just cleans up temporary files. But make clean has
another task here, too: it creates a small header containing the
actual date and a signature containing some informations about your
system. There's a default header, too, but the created one is better.

c) make

This builds the binaries, pdr and pdx. The first issue is to create a
private library containing some common used stuff. This private
library is linked in a static way to both applications and will not be
installed on the system.


2b) Building on Windows
-----------------------
Building on Windows is configured in a MSVC solution (Visual Studio
2008) containing a Debug and a Release configuration.

Before you start note the following linkage table:

		shared (DLL)	static
boost				x
POCO		x
libboard			x
libcairo	?		?

Setting up the linker has been a bit difficile. The solution is now
configured as in the table above. I tried to make a consistent shared
OR static configuration but boost and POCO depend on the project
properties "C/C++, Code Generation, Runtime Library" in a different
way. I couldn't get boost linked as shared and I couldn't get POCO
linked as static. It always ended up in serious linker errors. So be
sure you have the libraries available as mentioned in the table.

Until now I didn't get readline and history compiled by MSVC. They
need ncurses or termcap ... So I suggest to compile both programs
without readline and history support. This means don't define
USE_READLINE. You will then have a pure stdin input line in the
interactive modes which is surely limited in it's capabilities but
nevertheless full functionable.

I suggest to use libboard on Windows. It is much easier to compile
than libcairo which requires still other libraries like libpng. But if
you have a compiled libcairo on Windows you can try to use it.

Then do the following steps:

a) open the solution

b) check the defines for database usage in the projects pdr and pdx,
"Project Properties, C/C++, Preprocessor, Preprocessor Definitions",
define USE_SQLITE=1 and/or USE_MYSQL=1, default is USE_SQLITE=1

c) check the compiler input paths
"Project Properties, C/C++, General, Additional Include Directories"
The solution expects the include paths as follows:

	pdrx-1.0.? (here is the solution)

	boost_1_43_0
		boost

	poco-1.3.6p2-all
		Foundation\include
		Data\include
		Data\SQLite\include
		Data\MySQL\include
		Net\include
		XML\include

	libboard-0.8.8
		include

d) check the linker input paths
"Project Properties, Linker, General, Additional Library Directories"
The solution expects the linker input directories to be as follows:

	pdrx-1.0.? (here is the solution)

	boost_1_43_0
		stage\lib

	poco-1.3.6p2-all
		lib

	libboard-0.8.8
		lib

Up to here, be sure you made the same settings in all build
configurations.

e) build as usual


3) Installation
---------------
For installing the applications you don't have to do much more than
creating a directory and copy the files.

Note: on Windows you will have to copy the POCO-DLLs, too, and perhaps
even the MSVC runtime libraries:
	PocoData.dll
	PocoFoundation.dll
	PocoNet.dll
	PocoSQLite.dll
	PocoXML.dll
	(MSVCP90.dll)
	(MSVCR90.dll)


4) Further steps
----------------
To work with pdr and pdx some further steps are needed:

a) read the manual

Read it.

b) create a local directory, this directory should contain
   - a sub-directory for your report templates
   - a sub-directory for your generated output files
   - in the case of SQLite the database file

c) create your personal database

d) create an initial local configuration file named ~/.pdrx

e) use pdr to add the data collections you need to the database

f) develop your local report templates

Refer to the manual for detailed information about all these things.
