
		 Installation instructions
		 =========================

Topics
------

  Abstract
  1. Introduction
  2. Basic building steps
  3. How to install
  4. How to build packages
  A. Credits
  B. Bug reports
  C. Resources


Abstract
--------

This  infrastructure  reflects  the  personal needs  of  its
author (that's me!).   He has tried to provide  ways to do a
custom  installation, so that  others will  find it  easy to
install the package.  Please, read  all the file and then go
on with the installation.

  This file is not specific  to this project: it documents a
packaging infrastructures used in a set of projects.


1. Introduction
---------------

This software is packaged with GNU Autoconf and a set of GNU
m4 macros  to allow easy construction  of "Makefile.in" from
"Makefile.*"  templates.  The   automake  stuff  is  clearly
inspired to  GNU Automake,  but no code  comes from  the GNU
package. 

  Some  of the configuration  files are  located in  the top
source directory,  others in the  "gnuconfig" or "tclconfig"
subdirectory. 

  There should be  two Makefile templates: "Makefile.ds" and
"Makefile.rl";  the  first is  mandatory  and  it's the  one
processed by the "automake.sh" script, the second is sourced
in the first.

  There   should   be   a  configuration   script   template
"configure.ds",  which  is  processed by  the  "autoconf.sh"
script to  produce: first the "configure.ac"  file, then, by
executing GNU Autoconf, the common "configure" script.

  If we need to do some changes, make them on "configure.ac"
and  the final  "Makefile". The  make file  should  be human
readable  (especially if  we use  GNU Emacs  and  its narrow
mode).

  The infrastructure  makes use  of GNU Autoconf,  GNU BASH,
GNU Make and the GNU C Compiler (if required) along with the
common  UNIX binary  utilities (GNU  version),  like "grep".
There's no warranty that  the package will build and install
correctly without  them (because  the author cannot  test it
with other sets of utilities).

  The author considers GNU tar, GNU find and GZIP to be part
of the  standard installation of  every UNIX system,  but we
should  be able  to build  and install  the  package without
them: they  are required only to build  ".tar.gz" source and
binary distribution archives.


2. Basic building steps
-----------------------

If you don't  see the "gnuconfig" directory as  child of the
top source  directory, but you see  a "tclconfig" directory:
substitute it to "gnuconfig" in the following.

a.  Find  the  directory  in which  the  "configure.ds"  and
   "Makefile.ds" files are located  (usually they are in the
   top  source  directory of  the  package)  and change  the
   working directory there.

b. If we don't see  the "Makefile.in", we have to explicitly
   invoke "./gnuconfig/automake.sh":

	$ bash ./gnuconfig/automake.sh

c.   If  we  don't   see  the  "configure.ac"  template  and
   "configure"  executable  script,  we have  to  explicitly
   invoke "./gnuconfig/autoconf.sh":

	$ bash ./gnuconfig/autoconf.sh

   it will execute GNU Autoconf as a subprocess.

d.  Now we can  run "configure"  with whatever  command line
   options we want:

	$ ./configure --prefix=/usr/local ...

   we'll want to examine  all the available options with the
   "--help" flag.

	$ ./configure --help

   Remember that  if there's the need to  use an environment
   variable  (for  example to  select  a  C compiler),  it's
   better  to place  the selection  on the  command  line of
   "configure", for example like this:

	$ ./configure CC=/usr/local/bin/gcc

   The   author   highly   recommends   us  to   install   a
   "config.site"  file  in  our  file system,  so  that  GNU
   Autoconf  can configure itself  with the  correct layout;
   see the documentation of GNU Autoconf for details.

   The  Makefile  produced by  this  step  should be  enough
   human-readable.

   It should be possible  to configure and build the package
   in a  directory different from  the top directory  of the
   source tree. For example: one should be able to:

	$ cd <top directory>
	$ mkdir tmp && cd tmp
	$ ../configure
	$ make

   If  "configure" doesn't find  the files  it needs  in the
   current directory,  it tries in the uplevel  one. This is
   really  useful; the  build  directory can  even be  under
   "/tmp".

e. Now we can build the package:

	$ make all

   and optionally run the tests (if any):

	$ make test

  The "clean" and  "realclean" ".PHONY" rules are supported:
they  clean the  rebuilt files.   If  we want  to reset  all
(including the configuration) and restart:

	$ make config-clean


3. How to install
-----------------

An  "install" rule  is  provided by  the  Makefile, but  the
author suggests  us not  to use it  directly if we  have GNU
find, GNU tar and gzip. Instead, we can do:

    $ make bindist

in  the build  directory we'll  find a  "bin.tar.gz" archive
with  the binary installation  tree in  it.  Examine  it and
choose what to do.  We can simply install it with GNU tar:

    $ tar --directory=/ --extract --gunzip \
            --file ..._bin.tar.gz

  It  is   possible  that   the  package  also   creates:  a
"..._dev.tar.gz"  archive  with  files related  to  software
development  (example: C  header files);  a "..._doc.tar.gz"
archive with  the documentation; a  "..._sta.tar.gz" archive
with statically linkable libraries.

  The archives are built in the temporary directory selected
by the  "TMPDIR" environment variable. If we  don't have the
"TMPDIR" environment variable set, the Makefile will default
to "/tmp".

  If  we don't have  GNU tar  and GZIP,  we can  install the
package in  a temporary directory  by selecting a  value for
"INSTALL_ROOT" from the command line of "make"; example:

    $ make install INSTALL_ROOT=/tmp/${USER}/dist/PKG

  We can examine it and  set all the owner, group and access
permissions  that  we  need.   Then we  can  package  and/or
install  it with  any of  the common  available  tools.  For
example, with GNU tar we can package it like this:

    $ tar --create --file=PKG_1.2.3_bin.tar  \
              --directory=/tmp/marco/dist/PKG .

and then compress  it, or whatever we want  to do. The final
dot in  the command will make  all the pathnames  in the tar
file prefixed with "./", so that we'll be able to unpack the
file in a temporary directory later.

  To test the  install operation we can use  the "-n" option
of GNU Make:

    $ make -n install

to see a log of the commands that will be executed.


4. How to build packages
------------------------

In  the Makefile  there is  support for  source distribution
packaging. Just do:

    $ make dist

and  in the  build directory  we will  find  a "_src.tar.gz"
archive.   The archive  file  is built  under the  temporary
directory selected by  the "TMPDIR" environment variable; if
we  don't have  the "TMPDIR"  environment variable  set, the
Makefile will default to "/tmp".


A. Credits
----------

This infrastructure exists thanks to the wonderful effort of
the GNU Project and the free software community. 

  The scripts and macros were written by Marco Maggi.


B. Bug reports
--------------

Bug   reports  and  suggestions   about  the   building  and
installation infrastructure  are welcome.  Send  them to the
author by email: take the mail hostname of the ISP, which is
"tiscalinet.it", and  join it with the  mail username, which
is "marcomaggi", and we have the address.


C. Resources
------------

We can get the GNU software at:

		   <http://www.gnu.org/>


### end of file
# Local Variables:
# mode: text
# End:
