<!-- -*- 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 8 (Jessie) or Debian 9 (Stretch) 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
* libglib2.0-dev (optionally required if needing to re-run `autogen.sh`)


### C++ Compiler Flags ###

Optionally, to use different 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


### Building a Debian Package

On a Debian system, install the `build-essential` package to install the
essential packages required to build a debian package from source.
Additionally, install the `devscripts` package to install packages useful for
creating Debian packages.

The `./doc` folder in the source distribution should include the following
files:

- kitlist.1
- userguide.html
- userguide.pdf

The are removed with `make maintainer-clean`.  They can be rebuilt using
[Pandoc] by installing the following packages:

	- pandoc
	- texlive

then build with:

		$ ./configure --enable-build-docs
		$ make
		$ cd doc
		$ make docs

[Pandoc]: http://johnmacfarlane.net/pandoc/

Build an unsigned package:

		$ dpkg-buildpackage -us -uc

Build GPG signed changes file and source package:

		$ dpkg-buildpackage


GConf
-----

GConf is used to store the following attributes:

* Printed Page Title
* Most recently used files
* Debug log file name

However running GConf under MAC OS X and Windows is not
straight-forward, so GConf is disabled by default for these build
targets (./configure --without-gconf).  An alternative mechanism for
these formats has yet to be developed, so in the mean time these
features are not available.  The printed page title can be changed,
but the change is not saved across sessions.


Building for Windows
--------------------

As I no longer have access to a machine running Windows, building on Windows
or cross-compilng for Windows is no longer supported.

In the past, the application could be built for Windows platform
using [MinGW][] or by cross-compiling on Linux.  The instructions remain here
in case they should prove useful.

It's not currently documented and not entirely straight-forward, although I
have not as yet been able to build the application's alternative language
files.  However, this fails after the build is otherwise complete, so
interrupting the looping make file with Ctrl-c does the trick.  In any event
you need to:

1. Install the [MinGW][] development environment
2. Install various [MinGW][] packages (TODO:: document which packages) to support the build
3. Install version 2.16 of [gtkmm for Windows](http://live.gnome.org/gtkmm/MSWindows)
4. compile with `./configure

[MinGW]: http://www.mingw.org/


### Cross Compilation on Linux ###

The application can be cross-compiled on Linux for a Windows
target. These notes are based on instructions for [Cross-compiling GTK+
apps for Windows][cross-compiling-gtk+]

[cross-compiling-gtk+]: http://live.gnome.org/GTK%2B/Win32/Apps

Setup the tool chain following [the instructions][mingw_instructions]
on the [MinGW Wiki][mingw_wiki].

[mingw_wiki]: http://www.mingw.org/wiki/MinGWiki
[mingw_instructions]: http://www.mingw.org/wiki/LinuxCrossMinGW

The following settings in x86-mingw32-build.sh.conf worked for me:

		assume GCC_VERSION                   3.4.5-20060117-2
		assume BINUTILS_VERSION              2.19.1
		assume RUNTIME_VERSION               3.14
		assume W32API_VERSION                3.13-mingw32

Execute the mingw32 build script with an appropriate target.  E.g.:

		$ sh x86-mingw32-build.sh i686-pc-mingw32

Download the [gtkmm developer bundle][gtk-dev-bundle] and install it
in a new folder using Wine (or Windows), then copy the contents to
/opt/mingw/i686-pc-mingw32.

[gtk-dev-bundle]:http://live.gnome.org/gtkmm/MSWindows

Fix the package config files to have the correct prefix and rename the
DLLs.

		cd /opt/mingw/i686-pc-mingw32
		sed -i 's|^prefix=.*$|prefix=/opt/mingw/i686-pc-mingw32|g' lib/pkgconfig/*.pc
		cd ./lib
		for f in *.lib; do mv $f lib${f%%lib}a; done

Finally, build the kitlist application as follows:

		$ export PATH=/opt/mingw/bin:$PATH PKG_CONFIG_PATH=/opt/mingw/i686-pc-mingw32/lib/pkgconfig
		$ ./configure --prefix=/opt/mingw/i686-pc-mingw32/ --host=i686-pc-mingw32 --build=i686-pc-linux-gnu
		$ make
		$ makensis kitlist.nsi

**Note:** The application does not run under Wine.


### Useful Links ###

* <http://www.gtk.org/download-windows.html>
* <http://live.gnome.org/gtkmm/MSWindows/BuildingGtkmm>


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

The application can optionally be compiled to use a PostgreSQL
database instead of XML documents, using `./configure
--disable-xml-dao`.  In this case 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][].
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

[PostgreSQL Documentation]: http://www.postgresql.org/docs/8.1/static/libpq-envars.html


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

> If the locale is not installed, run

			# dpkg-reconfigure locales


**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].  Install the
following packages to regenerate the documention from source:

	- doxygen
	- texlive-latex-extra

The documentation can be regenerated from the source code as follows:

		$ ./configure --enable-build-docs
		$ cd doc
		$ make docs

The generated [Doxygen] documentation can be viewed under `../doc/doxygen/`.

[Doxygen]: http://www.stack.nl/~dimitri/doxygen/


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.
