README for the Publib framework
Lars Wirzenius
"@(#)publib-framework:$Id: README,v 1.4 1996/12/27 22:48:08 liw Exp $"

This is the README for the Publib framework, version 1.0.  This is the
first release version, but it will probably still format your hard disk.


Executive summary
-----------------

	gzip -dc framework-XXX.tar.gz | tar xf -
	gzip -dc liw-modules-XXX.tar.gz | tar xf -
	gzip -dc XXX-modules-XXX.tar.gz | tar xf -
	mkdir objs
	cd objs
	cat >> Default.config
	library=publib
	libshort=pub
	modules=../liw
	prefix=/usr/local
	^D
	../framework/configure
	make
	make install
	make clean


Blurb
-----

See the file called Blurb for a quick overview of Publib, including
instructions for getting it.


Unpacking The Sources
---------------------

Unpacking the framework distribution creates a directory framework, and
puts the framework sources in there.  The modules packages unpack into
their own directories (e.g., liw-modules-*.tar.gz unpacks into liw).
All these directories can be unpacked at the same level.

If you have the .tar.gz version of the sources, use the following
command to unpack the sources of the framework:

	gzip -dc framework-xxx.tar.gz | tar xf -

(replace publib-xxx.tar.gz with the pathname of the actual file with
the framework sources).  To unpack the modules, do:

	gzip -dc module-xxx.tar.gz | tar xf -

(replace module-xxx.tar.gz with the pathname of the actual file with the
module sources, e.g., liw-modules-0.6.tar.gz).  This last command needs
to be repeated once for every module that you wish to install (you don't
have to install modules you don't need).

Version 0.6 of the author's module collection is distributed as one
.tar.gz file that contains all his (publically distributable) modules.


Building The Library
--------------------

First you should create a directory where all the object files and other
files created by the build process go.  You can have several of these,
e.g., one per architecture.  The object directory should be your
working directory.

	mkdir objs
	cd objs

Then you need to run the configuration script before running make (there
won't even exist a Makefile before that).  In the object directory, give
the following command:

	../framework/configure --prefix=/usr/local --with-modules=../liw \
		--with-library=publib --with-libshort=pub

(modify the command as necessary if you have unpacked things in a different
place).  The --prefix option sets the directory below which things are
installed.

Please look at and, if necessary, modify, the Makefile and Rules.mk that
are created by configure.  Hopefully, you don't need to touch them.  If
you do, please communicate any problems you had to fix to the author, so
that they can be fixed in future releases.

After that, 'make' or `make all' builds everything, `make install'
installs everything, `make clean' gets rid of files built by make, and
`make realclean' gets rid of everything that can be built by make or
configure. You nead GNU make, or some other make that understands
the VPATH macro.

If you run configure again, with a different --with-modules, or change the
modules macro, you need to run `make clean' or else make won't necessarily
copy all headers correctly.

Hence, the typical commands to build and install the library are

	../framework/configure --prefix=/usr/local --with-modules=../liw
	edit Makefile Rules.mk
	make all
	make install

You may wish to give configure some options to specify where things
should be installed.  See the file publib/INSTALL for more information.
It is a generic instruction file for software packages that use GNU
autoconf; some of the instructions are not be relevant for Publib.

The framework supports several --with options:

	--with-modules		sets the module path; the argument should
				be a list of colon separated directories,
				e.g., "../liw:../misc:$HOME/src/my-modules";
				each directory in the list is a parent
				directory; the actual module source code
				directories come below them

	--with-noassert		compile without generating code for assert's

	--with-library		set the name of the library (default: publib)

	--with-libshort		set the short name of the library (default:
				pub, giving libpub.a)
				
	--with-verbose-make	print information about what is happening
				when make is running

The configuration script also accepts some other arguments, see the
generic instructions in publib/INSTALL.

If you want to set specific C compilation flags, set the environment
variable CFLAGS before running configure.  Specifically, if you use
GCC, but do not want to use debugging (configure automatically sets
compilation options to "-g -O" if it notices GCC), set CFLAGS to, for
example, "-O".

	env CFLAGS='-O' ../framework/configure --with-noassert

(You can leave off the "env" part if you don't have it and are using
a Bourne shell.  This doesn't work with C shell.)

The options to configure can be stored in a file called Default.config,
which is a shell script that sets the following variables:

	prefix		same as --prefix
	modules		same as --with-modules
	library		same as --with-library
	libshort	same as --with-libshort
	assert		"yes" or "no" (--with-noassert)
	verbmake	"yes" or "no" (--with-verbose-make)
	autoconf	"yes" or "no" (run autoconf, if installed?)
	
For example, you might write the following to Default.config:

	prefix=/usr/local
	modules=../liw
	library=publib
	libshort=pub
	assert=no
	verbmake=no
	autoconf=no
	
It is not necessary to set all variables.  Default.config is used 
automatically the configure script.


Tools Required
--------------

For unpacking the sources, the tools depend on how your copy has been
packaged.  The variables are compression program (compress or gzip)
and shell archives versus tar files.  All but gzip are standard on
Unix systems; you can find gzip on a number of anonymous ftp sites,
e.g., in prep.ai.mit.edu: pub/gnu/gzip-1.2.4.tar.gz (use the newest
version).

For building and installing the library, no special software is
needed.  The build process uses standard Unix tools (C compiler, make,
cp, rm, mkdir, find, uniq, sed, true, and so on).  Your C compiler and
library *MUST* be standard compliant; e.g., SunOS 4 usually isn't
(unless you buy an extra compiler kit from Sun; note that SunOS 4 + gcc
isn't good enough, since the libraries and headers are still screwed).

For developing the library, you need GNU autoconf, which is used to
generate the automatic configuration script (publib/configure).
Autoconf in turn needs GNU m4 (normal m4 is not sufficient).  Both can
be found on prep.ai.mit.edu, in the directory pub/gnu.  You probably
only need to generate configure if you change configure.in, and you
probably don't need to do that.


Writing and Distributing New Modules
------------------------------------

Publib is all about reusing code, so I would be delighted if you would
write more modules, or to enhance existing ones.  See below for some
notes about how the Publib framework works.  When you are ready to
distribute, mail Lars Wirzenius at lars.wirzenius@helsinki.fi for more
information about the preferred way to distribute it via Publib.  Or, if
you prefer, just distribute it and tell people where they can get the
framework so they can build it.  If you have enhanced an existing
module, please contact its maintainer (should be mentioned in the
documentation for the module).

Publib is intended to have very low overhead for developing and
distributing new modules.  One of the results is that there is no
central quality assurance group (although we would be delighted to
try out new modules, or new versions, within time constraints).  We
hope that the easier publication will result in more modules to be
written, and that the ease of making new versions will give enough 
quality.  (It works for Linux, it should work for us!)


How The Publib Build Mechanism Works (out of date)
------------------------------------

The framework sources are in directory referred to here as the base
directory, publib/ in filenames, or $(srcdir), if an absolute name is
required.  This directory contains the following files (at least)
relevant to the build process:

	configure	automatic configuration script
	configure.in	autoconf generates `configure' from this
	Generic.mk	generic makefile for modules
	Makefile	toplevel makefile
	Makefile.in	configure generates Makefile from this
	Rules.mk	shared stuff for all makefiles
	Rules.mk.in	configure creates Rules.mk from this
	publib.3	man page for Publib
	publib.3.in	the Publib man page (publib.3) is generated
			from this by Makefile
	include/	build-time include directory; Makefile copies
			the modules' headers here
	fwmodules/	subdirectory with the modules that are part
			of the framework (errormsg and port)
	modules/	subdirectory with the modules of the library
			(might be symlink; see macro modules in Makefile);
			this is created by the person unpacking the module
			 source code
	Template/	some template files for use with a new module

First, publib/configure is run (the current working directory
should be publib).  This automatically creates publib/Makefile
and publib/Rules.

The build process is as follows.

	1. All Publib headers are copied into publib/include/publib.
	   This makes it easy for modules to use each others' header
	   files, without having enourmous -I options for the compiler.

	2. A publib/include/publib.h header is built.  It
	   automatically includes all other Publib headers.  This is
	   a convenience for the user (only publib.h needs to be
	   included).

	3. The Publib man page is built.  (The list of all modules
	   that are to be built is automatically inserted.)

	4. All modules are built.  The publib/Makefile automatically
	   invokes the makefile in each module.  The modules'
	   makefiles are responsible for adding any object files into
	   the library file ($(libname) within the modules' makefiles,
	   after $(srcdir)/Rules has been included).

Requirements For Modules (out of date)
------------------------

The framework sources contain two modules that are put into
publib/fwmodules.

	errormsg	error message printing
	port		stuff for portability

A new module is placed into the build framework by putting its
sources into a subdirectory below publib/modules and making
sure it adheres to the following conventions.

	1. Its Makefile includes $(srcdir)/Rules

	2. Its Makefile supports the following targets

		all		build library modules
		tests		build (and optionally run) test programs
		install		install everything that is to be installed
		preinstall	things to do just before `install'
		postinstall	things to do just after `install'
		clean		remove most files built by make
		realclean	remove everything that can be rebuilt

	3. It refers to all Publib headers, including its own, with

		#include "publib/foo.h"

	4. All headers can safely be included multiple times, and do
	   not require other Publib headers to be included first.  The
	   simplest way to ensure this is to make the header look like

	   	#ifndef __publib_foo_h
	   	#define __publib_foo_h

	   	/* the actual header contents come here */

	   	#endif

	   Additionally, if there is a need to reference other modules'
	   headers in the header itself, an include is done:

	   	#include <publib/bar.h>

	   Note <>, not "", for delimiting the filename in this case.

The $(srcdir)/Generic.mk makefile can be used by most modules, by
including it into the module's makefile.  It provides all the
necessary things a module's makefile needs to, and allows the actual
makefile for the module be very simple.  See instructions at the
comment at the top of it for instructions.  Unless the module needs to
do something complicated during the build, Generic.mk should be quite
enough.

The __publib_error macro in fwmodules/errormsg/errormsg.h should be used
to report errors.  It will do nothing, print an error message, exit the
program, or abort the program (or a combination of these), based on the
user's preferences.  This makes it easy to generate a debugging version
of the library that helps identify the problem.  Usage is like this:

	p = malloc(n);
	if (p == NULL)
		__publib_error("malloc failed");
	return p;

The error message includes the name of the source file, the line
number in the source file, and the string argument.

The module's makefile should use $(INSTALL_MAN) for installing
man pages.  It will either be a BSD compatible install(1) program,
or the publib/install.sh script, which is 


Postcards
---------

If you like Publib (the framework or any of my modules), and want to
make me happy, send me a postcard to

	Lars Wirzenius
	Hernesaarenkatu 15 A 2
	00150 Helsinki
	Finland

Please don't send letter bombs (but money, computers or small furry
creatures from Alpha Centauri are fine).  You can also send e-mail,
but I prefer post cards.


Acknowledgements and history
----------------------------

The Publib effort started from an article posted to gnu.misc.discuss,
comp.sources.d, and comp.software-eng at the end of February, 1992, by
Steve Nuchia.  He then created the mailing list which has been used for
communication, library@sccsi.com.  Several people were active in the
discussion at the beginning.  Lars Wirzenius built a few prototypes for
the framework, based on the discussions on the list.  Paul Sander
and Greg Woods especially gave valuable comments on them.

Patrik Andersin noted the problem with running configure twice with different
module directories and the headers not being copied correctly.

The first version released outside of the list was 0.2, posted on
February 19 to alt.sources by Lars Wirzenius.

The list has been rather dead since the end of 1993.

The second version was 0.3, posted to alt.sources and put on
the ftp sites on July 16, 1994.

The third version was 0.4, not posted to alt.sources, only put on
the ftp sites on October 10, 1994.

The fourth version was 0.5, not posted to alt.sources or comp.sources.unix,
only put on the ftp sites in May, 1995.