README for the Publib framework Lars Wirzenius and the Publib mailing list "@(#)publib-framework:README,v 1.6 1994/07/16 12:38:47 liw Exp" Introduction ------------ Publib is an attempt at creating a library of reusable C functions. It consists of the build framework and the actual library modules. The framework is the mechanism that does the actual compiling and installation (and related things) of the library. The modules are groups of actual library functions. Publib was born out of discussion on a mailing list (see the end of this file), and is developed and maintained by Lars Wirzenius. There is no official set of modules. The intent is that many parties will supply modules so that the installer of the library can pick and choose between modules, and will install those that interest him. However, at this point, there is only one set of modules. No copyright restrictions for the modules is placed by the framework, and the framework itself is in the public domain (except for the files publib/configure, publib/COPYING, and publib/install.sh). This means that it can be used with commercial modules as well. Please check the documentation for each module for any restrictions on its use. Just because some people are paranoid about the GPL: the file publib/COPYING applies to the file publib/configure only. publib/install.sh comes from the X distribution and may be copied freely. Getting Publib -------------- Publib has been posted to the alt.sources Usenet newsgroup, and also put on the following anonymous ftp sites: ftp.funet.fi: /pub/languages/C/Publib ftp.cs.helsinki.fi: /pub/Software/Local/Publib For version 0.3, you need the following files: publib-0.3.tar.gz the framework itself liw-modules-0.3.tar.gz The modules by the author Unpacking The Sources --------------------- Unpacking the framework distribution creates a directory publib, and puts the framework sources in there. The default place to unpack the modules is into the publib/modules directory. However, you can also unpack them elsewhere, and either make publib/modules be a symbolic link to that directory, or set the makefile macro `modules' in publib/Makefile.in to point at that directory. Note, however, that publib/modules or its replacement directory will contain subdirectories, one per module. Each subdirectory within publib/modules that contains a file called Makefile is assumed to be module directory. (That is, if publib/modules/foo/Makefile exists, then publib/modules/foo contains a module that will be built. This check allows there to be additional files and subdirectories within the modules directory, especially CVS directories.) If you have the .tar.gz version of the sources, use the following command to unpack the sources of the framework: gzip -dc publib-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: mkdir publib/modules cd publib/modules and then: gzip -dc module-xxx.tar.gz | tar xf - (replace module-xxx.tar.gz with the pathname of the actual file with the module sources). 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.3 of the author's module collection is distributed as one .tar.gz file that contains all his (publically distributable) modules. Building The Library -------------------- You need to run a configuration script before running make (there won't even exist a Makefile before that). In directory publib, give the following command: ./configure Please look at and, if necessary, modify, the Makefile and Rules.mk that are output 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 (assuming you have the right tools; note, however, that the configure command is also removed, and that you will need to have GNU autoconf to rebuild it). Hence, the typical commands to build and install the library are ./configure 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. Particularly, Publib doesn't (yet) support compilation from another directory. No --with- options are supported. If you need to run configure many times before getting everything just right, and you need to modify Makefile or Rules.mk after running configure, you may want to modify things in Makefile.in and Rules.mk.in so that you do not need to re-do the edits all the time. 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). For developing the library, you may 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. Available Modules ----------------- See the file publib/LIST for a list of some modules. This list doesn't pretend to be complete; it lists those modules that the maintainer of the framework was aware of (and, naturally, includes many of his own modules). Writing and Distributing New Modules ------------------------------------ Publib is all about reusing code, so we 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 ------------------------------------ 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 ------------------------ 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 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 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. 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.