CODAS compilation strategy

99/04/20

The present makefile system for building all CODAS libraries
and binaries is primitive and not entirely satisfactory, but it
is fairly simple, and it does work on multiple platforms. It
was originally designed to work with Turbo-C as well as DOS/Win
versions of gcc, but I have not actually made a TC compilation
for a long time. Here is how it works: (for command line
options etc., see the individual scripts; or try invoking them
with no command line argument for a quick summary of usage and
options.)

A complete set of routines used in building and zipping is in
codas3/make.  Both makefiles and perl routines are required. 
NOTE: the Gnu Make program is required.  Different versions of
Make use different syntax in many areas, most crucially in the
specification of "include" files, so supporting only a single
version of Make simplifies things enormously.  Fortunately, Gnu
Make is readily available on all target platforms.
Changing a codas3 directory tree from one platform to another
requires running at most two perl routines:

   convert.prl changes the line termination between CR LF
   (DOS/Win) and LF (Unix); it operates only on files for which
   this conversion makes sense, it can be run multiple times
   without duplicating the line endings, and it does not change
   the permissions or times of the files.

   sethost.prl changes the makefile system between platforms. 
   As needed, it copies codas3/make/makefile.{dos|unx} to
   codas3/makefile; this is the master makefile that traverses
   the directory tree invoking make in the subdirectories, and
   the two versions use different strategies as required by the
   differences between command.com and the unix shells. 
   sethost.prl also copies codas3/make/{host}/makefile.dep to
   codas3/makefile.dep, where host is, for example, sol for
   Solaris, sgi for Silicon Graphics, or mgw for Minimalist
   Gnu-Win (a variation of gcc for Win95/NT).  makefile.dep is
   included by all other makefiles; it contains everything that
   differs among platforms.

The make subdirectory also includes:

   formake.prl rectifies the format of a makefile, ensuring
   that indentation is via tabs and that a backslash at the end
   of a line is immediately followed by newline, not accidently
   by invisible space characters.

   listobj.prl is not run manually; it is part of the system
   for compiling libraries.

   zipcod.prl is used for zipping up parts of the codas3 tree
   for distribution.

   Other files such as sortcnt.prl may appear, but are not part
   of the standard compilation system.

   For each target there is a subdirectory (e.g. sol, mgw,
   etc.) with:

      makefile.dep has all platform-variable elements, included
      by all makefiles.

      library.mak has instructions for making a library on that
      platform.  This file is included as needed by other
      makefiles; it is not copied or invoked directly.

Outside the codas3/make tree, each directory with C source
files (*.c) has its own makefile.  

   The makefiles for libraries are extremely simple; all the
   work is done in the master makefile (codas3/makefile) and in
   the host-specific included file library.mak. The master
   makefile executes the script listobj.prl to generate a list
   of all C source files, which it then writes out as a list of
   all object files to be used by library.mak in constructing
   the library. Therefore, adding a C file to a library source
   directory is all that is needed to add a module to the
   library; it will be automatically added to the list of
   objects.  All makefiles in library directories are almost
   identical; they may differ only in the specification of the
   relative paths of the files they include, depending on how
   deep in the tree the directory is.

   The situation is not quite so simple for directories that
   result in executables.  Each such directory has a makefile
   that follows the same form as all others, but each must
   include its own macro lists of libraries to be linked and
   its own rules for making the particular binaries. 
   Therefore, to add an executable to a directory, one must add
   a block of statements to the makefile in that directory.

Compilation can be initiated from the codas3 level:

   "make libs" to make all the libraries;

   "make bins" to make all the executables;

   "make" to make both, libraries first, of course.

   "make clean" to delete object files and other junk.

Compilation can also be done manually in any given directory by
executing "make" in that directory.

There is no separate "make install" step; libraries land
directly in the codas3/lib/{host}/ directory, and executables
in the codas3/bin/{host}/ directory.

Limitations:

   Only the very most basic dependencies are includes; there
   are no header file dependencies, and binaries are not
   relinked automatically when a library is changed.  

   If compilation fails in the middle of a directory, and is
   resumed by running "make" again after fixing the problem, it
   may not complete that directory properly.

   Only static linking is used at present, so executables are
   unnecessarily large.

   Only gnu make is supported.

   Only versions of gcc are used on the DOS/Win platform--no
   Visual C, no Borland C.

I have briefly looked at Troll Tech's free Tmake system as a
possible alternative that would remove these limitations;
unfortunately, it appears that it would require quite a bit of
work and a major reorganization of the codas3 tree to implement
it.