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.42
  - POCO C++ framework 1.36p2

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. 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.

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.

a) Options to 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)

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 image types.

* 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 Unix-like systems (without Autotools)
-----------------------------------------------------
The build process is configured in Makefile.simple. The Makefile
expects all the libraries to be shared:

		shared		static
boost		x		?
POCO		x		?
readline	x		?
history		x		?
libboard	x		?
libcairo	x		?
libetpan	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_ETPAN	make pdr able to access IMAP mailboxes

Remarks:

* USE_SQLITE and USE_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 USE_BOARD and USE_CAIRO can be used together to
  support both image types.

* You do not need USE_ETPAN for POP3 mail access. POP3 access is
  implicit and always enabled. If you define USE_ETPAN both POP3 and
  IMAP access are usable.

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.


2c) 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

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

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.

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-DLL you can truely try to use it.

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

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_1_42_0
		boost

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

	libboard-0.9.0
		include

	libetpan-1.0
		build-windows\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_1_42_0
		stage\lib

	poco-1.3.6p2-all
		lib

	libboard-0.9.0
		lib

	libetpan-1.0
		build-windows\Release

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 the POCO-DLLs, too, and perhaps
even the MSVC runtime libraries:
	PocoData.dll
	PocoFoundation.dll
	PocoNet.dll
	PocoSQLite.dll
	PocoXML.dll
	libetpan.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.
