Gnokii installation instructions
================================

[NOTE: For package building see the 'Docs/packaging-howto' file.]


Quickstart
==========

    $ gettextize -c -f --intl --no-changelog	# only for CVS copies
    $ libtoolize -c -f				# only for CVS copies
    $ aclocal					# only for CVS copies
    $ autoheader				# only for CVS copies
    $ autoconf					# only for CVS copies
    $ ./configure [<options>]
    [ If you use latest Red Hat with new (0.11) gettext version ]
    [ run autogen.sh with configure options instead of the      ]
    [ above commands. It will do all required things.           ]
    $ make
    # groupadd gnokii
    # make [install|install-suid|install-strip|install-ss]
    # make install-docs
    $ cp Docs/sample/gnokiirc ~/.gnokiirc
    $ $EDITOR ~/.gnokiirc


Requirements
============

Additional libraries and header files needed for the various gnokii parts:

xgnokii:		libX11, libXpm, glib-2.0, gtk+-2.0
bitmap support:		libXpm for xpm files support, gnokii can deal without
			this (xgnokii cannot)
irda support:		Linux kernel includes
bluetooth support:	bluez (Linux Bluetooth stack)
libical support:	libical-0.24, you may want to use gnokii internal iCal
			implementation but it is limited, no longer developed
			and deprecated. This is only for converting calendar
			and todo entries into iCal files and reading such
			files.

Sources:
http://www.xfree86.org/					libX11, libXpm
http://www.gtk.org/					glib, gtk
http://www.kernel.org/					Linux kernel includes
http://bluez.sf.net/					bluez (Linux Bluetooth stack)
http://sourceforge.net/projects/freeassociation/	libical

For xgnokii you may want download gnokii-artwork package from
http://www.gnokii.org/download/gnokii, the package containing mobile
phone pixmaps to be used with xgnokii keyboard simulator and operator
logo previewer.

Verbose instructions
====================

Preparations
------------

If you retrieved this copy from CVS, then first call

    $ gettextize
    $ libtoolize
    $ aclocal
    $ autoheader
    $ autoconf

Now you have to determine your system specific settings.

    $ ./configure [<options>]

Basic options are:

    --prefix=DIR
	Sets the install path prefix. Default is /usr/local/.

    --without-x
	Compiles without GTK (X11) programs.
		
    --disable-nls
	Set if you don't have/want GNU gettext support.

    --enable-security
	Set if you want to enable all security features supported by your 
        mobile (PIN change, etc.).

    --disable-debug
	Set if you don't want debug code compiled in.

    --disable-rlpdebug
	Set if you don't want RLP code compiled in.

    --disable-xdebug
	Set if you don't want X code compiled in.

    --enable-fulldebug
	Set if you want to produce binaries with debug symbols (cc -g)

    --help		
	Shows all options.

This example is commonly used:

    $ ./configure --prefix=/usr --enable-security

Alternatively, instead of writing these three commands you can use:

    $ sh autogen.sh [<options>]

where options are the same as with configure script. Sometimes (it happens
mainly with libintl and libiconv) some libraries may not be correctly
recognized. You may want to set enviromental variables to let configure do
the work. The sample usage would be:

    $ CPPFLAGS="-I/usr/local/include -L/usr/local/lib" ./configure \
	--prefix=/usr --enable-security

or

    $ CFLAGS="-I/usr/local/include -L/usr/local/lib" ./configure \
	--prefix=/usr --enable-security

and the euivalent with autogen.sh


Compilation
-----------

Start the compilation process by typing

    $ make

or

    $ make gnokii-debug

The second form creates statically linked binaries. These are mainly used 
for debugging the software.


Installation
------------

Now switch to the root account and add a group named "gnokii". Gnokii 
really needs an own group. It is added with

    # groupadd gnokii


Install the binaries into the system with one of the four following lines:

    # make install
    # make install-suid
    # make install-strip
    # make install-ss          # <-- suid AND strip

'install' target is the usual installation process that you would need in
most cases.
'install-suid' target sets more restrictive permissions. Only gnokii group
members will have access to gnokii files. Remember to create the gnokii
group.
'install-strip' target strips the prepared binaries on install.
'install-ss' target does both strip and suid.
When you need to use mgnokiidev and don't want to setup it manually,
install-suid will be a good choice.
We don't recommend to strip the binaries as the debug symbols may give us
some valuable input in case of problems.
For distribution packaging install-ss target will be probably wise choice.

Note that you will need to adjust /dev/ttyS* or /dev/ircomm* and /var/lock
permissions and ownership before starting using gnokii.

If you wish to install gnokii stuff in some other directory root (eg. when
creating a distribution package), you can take an advantage of the DESTDIR
variable:

    $ make DESTDIR=/somewhere install

To install the documentation type

    # make install-docs


Clean-up
--------

To remove products of the compile process, type

    $ make clean

Calling

    $ make distclean

additionaly cleans all ./configure outputs. After this command you must 
run ./configure again if you need to use any Makefile.


Configuration
-------------

Copy the example config file for gnokii from the Docs/sample/ directory to
your home directory:

    $ cp Docs/sample/gnokiirc ~/.gnokiirc

It is a plain ASCII file which can be read in any editor. Make sure you do 
not save it in a wordprocessor's binary-format. It has to remain plain 
text. vi, mcedit, kedit, joe or even emacs are good examples.

Change the settings to fit your system. Lines beginning with a `#' are 
comments. The file should be self-explaining. Note that `#' not at the line
beginning is NOT treated as comments. In particular:

    connection = serial # I have DLR-3P cable

will cause problems.
