<!-- -*- mode: markdown; -*- -->

kitlist
=======

Building
--------

kitlist - a program to maintain a simple list of items and assign items to
one or more categories.


### Required Packages for Desktop Build ###

On a Debian system, the following packages need to be installed to
build the application:

* intltool
* libgconfmm-2.6-dev
* libgtkmm-2.4-dev
* libpqxx-dev (pgsql only)
* libtool
* libxml++2.6-dev
* libglademm-2.4-dev

### Required Packages for Maemo Build ###

On the Maemo platform, the following packages are required:

* intltool
* libgconfmm-2.6-dev
* libgtkmm-2.4-dev
* libhildonmm-dev
* libhildon-fmmm-dev
* libtool
* libxml++2.6-dev
* libglademm-2.4-dev

Version 0.6.2 has been confirmed to compile on the following
platforms:

* Debian 4.0 (Etch)
* Debian 5.0 (Lenny)
* Ubuntu 8.04 (Hardy Heron)

## C++ Compiler Flags ##

Set the environment variable CXXFLAGS when running ./configure.  E.g.

		$ CXXFLAGS="-g -O0 -fno-inline" ./configure

to include debug messages, define KITLIST_DEBUG

		$ CXXFLAGS="-g -O0 -fno-inline -DKITLIST_DEBUG" ./configure


Obtaining the required libraries in the Maemo scratchbox environment
--------------------------------------------------------------------

1. Add the following repositories to the scratchbox configuration:


		cat >> /etc/apt/sources.list.d/maemo-extras.list <<EOF
		deb http://repository.maemo.org/extras/ diablo free non-free
		deb http://repository.maemo.org/extras-devel/ diablo free non-free
		deb-src http://repository.maemo.org/extras/ diablo free non-free
		deb-src http://repository.maemo.org/extras-devel/ diablo free non-free
		EOF

2. Install the required packages:

		$ fakeroot apt-get update
		$ fakeroot apt-get install maemo-explicit maemo-cplusplus-env
		$ fakeroot apt-get install libglademm-2.4-dev libgtkmm-2.4-doc intltool

3. To re-generate the GNU configure files, run the following command:

	To build for deployment to a Maemo platform (E.g. Nokia N810 Tablet)

			$ ./autogen.sh

	For the default Linux desktop build:

			$ ./autogen.sh --disable-maemo-target

	**Note:** The warnings generated by aclocal are usually just warning of
deprecated behavior.

4. Then you can build the application with:

		$ ./configure
		$ make


Running in Maemo Scratchbox Environment
---------------------------------------

1. Xephyr is used to provide an X server based emulation window.  Install
the xserver-xephyr package in Debian 4.0 (Etch).

2. Run the Xephyr server from a normal user terminal:


   	   $ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -extension Composite

3. Login into scratchbox environment, build and run with:

		$ /scratchbox/login
		$ export DISPLAY=:2
		$ af-sb-init.sh start
		$ cd ~/kitlist
		$ ./autogen.sh
		$ ./configure
		$ make
		$ run-standalone.sh ./src/kitlist

4. In the scratchbox environment, build a release with:

		$ dpkg-buildpackage -rfakeroot -b -tc

5. and install it with:

		$ fakeroot dpkg --install ../kitlist_X.X.X_ARCH.deb

6. uninstall with:

		$ fakeroot dpkg --remove kitlist

7. purge with:

		$ fakeroot dpkg --purge kitlist

See [http://wiki.maemo.org/Scratchbox_C++](http://wiki.maemo.org/Scratchbox_C%2B%2B)


Runtime library dependencies
----------------------------

* libgtkmm-2.4-1c2a
* libxml++2.6c2a
* libglademm-2.4
* libgconfmm-2.6-1c2
* libhildon-fmmm
* libhildonmm

Environment Variables
---------------------

There are a number of environment variables that can be used to specify
various connection parameters to the PostgreSQL database.  These are listed in
the [PostgreSQL Documentation](http://www.postgresql.org/docs/8.1/static/libpq-envars.html).  Some of them are mentioned briefly below:

### Example Environment Variables ###

* PGHOST - The database server name
* PGPORT - The port to use
* PGDATABASE - The database name
* PGUSER - The database user name
* PGPASSWORD - The connection password


Internationalisation
--------------------

1. Translatable strings contained in the program have been written in
American English.  To create a translation for another language, go to
the po sub-directory and run the following command to update the
default language file ./po/kitlist.pot:

		$ intltool-update --pot

2. Copy this file to languagecode.po, e.g. fr.po.  This file contains
pairs of strings, one in the default language, the other the
translated version, initially blank.  Also add the language to the
list in the ./po/LINGUAS file, and the ALL_LINGUAS entry in
./configur.ac.

3. To merge code changs into a translated po file, e.g. French:

		$ intltool-update fr

4. Re-build and re-install the program.  To specify the language in a
shell, specify the LANG environment entry, e.g.:

		$ export LANG=fr_FR.UTF-8

**Note:** the kitlist program must be installed before the language
files are picked up at runtime.

More information in
[Programming with gtkmm](http://www.gtkmm.org/docs/gtkmm-2.4/docs/tutorial/html/sec-i18n-marking-strings.html)


Documentation
-------------

The documentation for the code is maintained using
[Doxygen](http://www.stack.nl/~dimitri/doxygen/).  The documentation
is regenerated from the source code as follows:

		$ cd src
		$ make docs

The generated documentation can be viewed under ../doc/doxygen/

A PDF reference manual can be created as follows:

		$ cd ./doc/doxygen/latex
		$ make pdf
		$ ls refman.ps refman.pdf

License
-------

The source code and documentation are licensed under the GPL.  See the
COPYING and AUTHORS files distributed with the source code for
information and contact details.
