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.35 ... 1.46
  - POCO C++ framework 1.36p2 ... 1.4.1p1

optional:
  - GNU readline and history libraries
  - libboard C++ library 0.9.0
  - Cairo C library 1.8.10
  - libEtPan 1.0

The versions above are those the applications have been developped and
tested with. You can try other versions before you install anything
else.

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.

Note the linkage tables in the following platform dependend sections!


2a) Building on Unix-like systems (with Autotools)
--------------------------------------------------
Now standard configuration and building via Autotools is possible:

	aclocal
	autoheader
	automake --add-missing
	autoconf
	./configure
	make
	make install

The configure script will check for the presence of the neccessary
libraries.

Now to the options of the configure script. Any --enable-* option may
also be used as --disable-* to override the defaults.

--prefix=[PREFIX]	change the target for 'make install'.
			(/usr/local by default)

--enable-debug		don't optimize and build with debug information
			(disabled by default)

--enable-sqlite		make pdr and pdx able to use SQLite databases
			(enabled by default)

--enable-mysql		make pdr and pdx able to use MySQL databases
			(disabled by default)

--enable-readline	use the readline library in interactive modes
			(enabled by default)

--enable-board		make pdx able to create svg images
			(enabled by default)

--enable-cairo		make pdx able to create png images
			(enabled by default)

--enable-etpan		make pdr able to access IMAP mailboxes
			(enabled by default)

--enable-poco141	use the new POCO 1.4.1 library names
			(disabled by default)

Remarks:

* --enable-sqlite and --enable-mysql can be used together - so the
  resulting executable will be able to run on both databases. Note
  that you can't disable both database engines, as one is obligatory
  needed. The configure script will stop and warn you if you disable
  both database engines.

* In the same way --enable-board and --enable-cairo can be used
  together to support both libraries.

* You do not need --enable-etpan for POP3 mail access. POP3 access is
  implicit and always enabled. If you use --enable-etpan both POP3 and
  IMAP access are usable.


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
libetpan	x
libcairo	x

readline	(... never tried ...)
history			"

As you see 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 any readline and history support. Then you will have a pure
stdin input line in the interactive modes which is surely limited in
it's capabilities but nevertheless full functionable.

libEtPan 1.0 causes some issues while compiling itself even if you use
the original MSVC solution. Most of them are to be solved by minor
changes in it's sources but you need some experience in C and C++ and
in different compilers and in Windows programming for doing this.

Then do the following steps:

a) open the solution

b) check the defines 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, set USE_ETPAN=1 if you
want to use libEtPan, set USE_CAIRO=1 if you want to build with Cairo
support

c) check the compiler input paths
"Project Properties, C/C++, General, Additional Include Directories"
If the solution file is here ...

	pdrx-1.?.?\pdrx.sln

... the following include paths are expected:

	boost\include\boost-1_46_1
	poco-1.4.1p1-all\Foundation\include
	poco-1.4.1p1-all\Data\include
	poco-1.4.1p1-all\Data\SQLite\include
	poco-1.4.1p1-all\Data\MySQL\include
	poco-1.4.1p1-all\Net\include
	poco-1.4.1p1-all\XML\include
	libboard\include
	libetpan-1.0\build-windows\include
	cairo\include

d) check the linker input paths
"Project Properties, Linker, General, Additional Library Directories"
If the solution file is here ...

	pdrx-1.?.?\pdrx.sln

... the following linker input paths are expected:

	boost\lib
	poco-1.4.1p1-all\lib
	libboard\lib\Release
	libetpan-1.0\build-windows\Release
	cairo\lib

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

e) build as usual (yes, it's slow)


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 some DLLs, too, and perhaps
even the MSVC runtime libraries:

	PocoData.dll
	PocoFoundation.dll
	PocoNet.dll
	PocoSQLite.dll
	PocoXML.dll
	libetpan.dll
	freetype6.dll
	libcairo-2.dll
	libfontconfog-1.dll
	libpng14-14.dll
	zlib1.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.
