Generic installation instructions for ADE-based software
========================================================

Prerequisite software
---------------------

Software based on ADE require the following software to be installed
first:

	GNU make
	Perl version 5 or greater
	Bash
	ADE 

Preparing to compile
--------------------

Run:

	make
	bin/*-config --format=make

and examine the output. It will look something like this (comments
added here only):

        #  under which directory tree should the application's files be installed?
	<APP>_PREFIX = /usr
	#  more specifically, where should the application's commands be installed?
	<APP>_BIN_PREFIX = /usr/bin 
	#  where should the application's documentation be installed?
	<APP>_DOC_PREFIX = /usr/share/doc/<app>
	#  where should the application's configuration files be installed?
	<APP>_ETC_PREFIX = /etc/<app>
	#  where should the application's share files be installed?
	<APP>_SHARE_PREFIX = /usr/share/<app>
	#  where should the application's library be installed?
	<APP>_LIB_PREFIX = /usr/lib/<app>
	#  where should the application's man pages be installed?
	<APP>_MAN1_PREFIX = /usr/share/man/man1
	<APP>_MAN2_PREFIX = /usr/share/man/man2
	<APP>_MAN3_PREFIX = /usr/share/man/man3
	<APP>_MAN4_PREFIX = /usr/share/man/man4
	<APP>_MAN5_PREFIX = /usr/share/man/man5
	<APP>_MAN6_PREFIX = /usr/share/man/man6
	<APP>_MAN7_PREFIX = /usr/share/man/man7
	<APP>_MAN8_PREFIX = /usr/share/man/man8
	<APP>_MAN_PREFIX = /usr/share/man

If the paths you see do not match what you or your system require,
then edit bin/*-config.sh, make the correct setting and repeat this
part of the procedure again. Do this again and again until the settings
displayed are correct.

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

Run:

	make

Testing
-------

Run:

	make tests

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

Run:

	make install

Depending on where you are installing to, you might need to be root
for this to work.

Man page support
----------------

Most ADE-based software includes man pages. These pages make use of
the unsafe '.pso' groff request. Normally the 'man' command will not
invoke groff with unsafe requests enabled. It can be enabled by editing
/etc/manpath.config and adding '-U' to the invocations of nroff and
groff; the following commands will do this on a Debian system:

	perl -pi -e "s/^#?(DEFINE\\s+nroff\\s+).*\$/\$1nroff -mandoc -U/" /etc/manpath.config
	perl -pi -e "s/^#?(DEFINE\\s+troff\\s+).*\$/\$1groff -mandoc -U/" /etc/manpath.config

If you do not do this then:

1) some paths mentioned in man pages will not be display correctly E.g. 
   instead of the text "The configuration data is stored in /etc/foo/foo.conf" 
   you might see "The configuration data is stored in /foo.conf". 

2) SYNOPSIS, OPTIONS and COPYRIGHT & DISTIBUTION POLICY sections will be 
   incomplete.

While this behaviour may be confusing, it is not a disaster.

Application-specific instructions
---------------------------------

This document describes the steps required for ADE-based
software. There may be additional steps needed which are specific to
this application. Please consult doc/README.<app> (if it exists).

Configuration and execution
---------------------------

See the man pages.