For some reason, the following message did not make it out yesterday,
so I have reposted it.

John

From: ramsdell@mitre.org (John D. Ramsdell)
Subject: Csound GNU build system lessons learned
To: Csound Developers Discussion List 
Cc: ramsdell@mitre.org
Date: 13 Dec 2003 11:51:36 -0500

Even though the GNU build system in the csound module has yet to be
completed, I would like to relay lessons learned that I think should
be reflected in the GNU build system in the csound5 module.  The
biggest deficiency in the csound module's current GNU build system is
its inability to build shared libraries, so I will not comment on the
wisdom (or lack of wisdom) of using libtool.  In suffices to say that,
so far, libtool's only function has been to slow down builds.

The three tools that have demonstrated their usefulness are autoconf,
autoheader, and automake.  To better support autoheader, each
AC_DEFINE statement in the csound module's configure.ac contains a
documentation string.  The result is a nicely commented config.h.in
file.

Unlike autoconf, which has been a solid tool for a long time, older
versions automake were not easy to use, however, the current version
of automake is very solid.  Not only is there mature support for C,
and C++ programs, but the version on my machine provides support both
Python and Java programs.  Of course, for Java programs, automake
requires you use gcj, the Java front-end to the GNU Compiler
Collection.  I ask this of anyone not convinced of the merits of
employing automake in the csound5 module: please compare
anal/adsyn/Makefile.am with anal/adsyn/makef.  I'm sure you'll see
that the automake version of this information is much more
understandable.  The real understandability test is to compare
csound/Makefile.am with csound/Makefile.lnx.

It is easy to employ automake if your project follows two rules.  

1. Source files should be placed only in directories that do not
   contain directories, other than CVS.

2. To the extent possible, sources used to build a product, such as a
   program or a library, should be placed in the directory in which
   the product is built.  This rule does not apply to header files,
   which can be included from arbitrary directories.

With respect to the first rule, automake makes use of a commonly
respected convention on the organization of source files that existed
long before automake.  Unix programmers following the convention
always know that a directory contains no directories by simply noting
the existence of file names of sources.  With this convention, there
is no need to employ typographical conventions to identify
directories, such as capitalizing directory names or adding a .dir
extension.

The second rule used to be strictly enforced by automake, however, the
current version of automake allows exceptions to both rules.  Violate
these rules with caution.

--------------

What follows is a list issues presented in no particular order.

The GNU build system in the csound module includes the csound/config.h
file generated by configure.ac only in the file csound/autoheader.h,
and other parts of the package include autoheader.h.  This
arrangements makes it easy to augment definitions in config.h.  By the
way, I'm not in love with name autoheader.h--you may want to change
it.

At some point, to handle C99 booleans, autoheader.h should include

#if HAVE_STDBOOL_H
# include 
#else
# if !defined HAVE__BOOL
#  ifdef __cplusplus
typedef bool _Bool;
#  else
typedef unsigned char _Bool;
#  endif
# endif
# define bool _Bool
# define false 0
# define true 1
# define __bool_true_false_are_defined 1
#endif

To handle C99 booleans, source files must be changed.

The tool autoscan helps produce a configure.ac script.  I notice that
when it generates its AC_CHECK_HEADERS macro call, it makes sure there
are no line breaks in its argument.  The same is true for
AC_CHECK_FUNCS macro call.  I bet if the line breaks in the argument
to AC_CONFIG_FILES are removed, that file could be a text file once
again.

The use of FLTK in the library that implements the Csound API raises a
number of issues.

In csound/csound.c, the csoundYield function must conditionally cause
the invocation of Fl::check().  If it does not, the main routine in
csound/ccsound.c cannot use the FLTK graphing routine, since it has
access only to symbols declared public in libcsound, in other words,
it can only use symbols in the Csound API.

In configure.ac, the fltk-config program is consulted to obtain its
opinion on how to link FLTK programs.  On Cygwin, the -mwindows option
is included, under the assumption that no one would ever want to use
FLTK with a console application, but, of course, console csound does
just that.  I've currently turned off the use of FLTK on Cygwin.

When building wxCsound on a platform that has FLTK installed, one
finds one must link the wxcsound program with both wxWindows libraries
and FLTK libraries.  This does not feel right to me.

I considered reimplementing wxCsound using FLTK, but found wxWindows
provided much better support for Windows.  For example, wxWindows
provides a tabbed window pane that maps directly to the Windows
equivalent, but I cannot see how to obtain the same functionality with
FLTK. 

The wxCsound package is distinct from the csound package.  The
csound-config program is consulted to obtain its opinion on how to
link programs that use the Csound API.  One might consider making
CSoundVST into its own distinct package, one that is configured using
csound-config.

The wxWindows configure.in file contains advice on linking with MinGW.
In particular, it can be wrong to include -lm at link time.  As such,
I've changes the test for this library in configure.ac to:

  AC_SEARCH_LIBS([sin], [m])

--------------

It is time to begin planning for a revamped GNU build system for the
csound5 module.  There is no reason to delay work on a libtool-less
system.  The first issue that must be addressed is the directory
organization.  Perhaps the current one already meets the two rules
previously listed, however, now is the time introduce a top-level src
directory, a doc directory, and/or an include directory, or whatever
other changes you want that are independent of the reorganization in
support of automake.

The directory reorganization in support of automake should be directed
by someone with a vision of what Csound will be, i.e., not me.  I have
been able to succeed because I have been dealing with a static system,
but others must implement the csound5 changes.  I will continue to
make an effort to make libtool work in the csound module, but, I have
to admit, I'm kind of stuck now.

John