Re: Documenting tools necessary for GCC [draft]

[Alexandre Oliva <aoliva at redhat dot com>]

On Jun  1, 2003, Geert Bosch <bosch@gnat.com> wrote:

> One of the concrete issues that came up is the ability to use
> include files.

automake already has a macro that tests whether ${MAKE-make] supports
include, and it even supports both `include' and `.include' syntaxes.
We can do it without requiring GNU make.

> Another issue that we found with the GNAT front end, is that with
> the extra GNU make features one doesn't need to rely as much on shell
> capabilities.

You mean GNU make functions?  I'd much rather not start depending on
them.  I can see sometimes there may be benefits to doing so, but it
pretty much makes us entirely dependent on GNU make.  I could live
with that if the benefits are clearly worth it, but I don't want us to
use GNU make features just because we can.

> Personally, I have found it tremendously helpful to be able to go to
> one manual to find all constructs documented. Having the language
> used for Makefiles specified as the least common denominator of
> languages accepted by an open-ended set of "compatible" make
> utilities is a real problem.

Here's a (partial?) manual of the portable make features:

# <comments>
<MACRO> = <value>
<target> : [<dependency> ...] [ ; [@][-]<shell commands>]
[	[@][-]<shell commands> ...]

.SUFFIXES: [.<extension> ...]
.<extension>[.<extension>]:
[	[@][-]<shell commands> ...]

macros are referenced as $(MACRO) or ${MACRO}.  They may be referenced
in values and shell commands; their use in dependencies and targets is
also possible, but may have slightly different meanings; see below.
Other macros referenced in <value> are expanded at the location the
macro is expanded.  If a macro is defined more than once, the last
definition prevails, except when the macro is referenced in target or
dependencies, in which case the latest definition of the macro before
that point may be used.

Special macros such as $@ and $< denote the target and the
dependencies, respectively, and the latter should only be used in
shell commands in suffix rules.  $$ expands to the $ character.

Macros set in a Makefile may or may not be passed down to sub-makes.

Shell commands are written in whatever scripting language make starts
to run commands.  It can generally be assumed that this is some
variant of the Bourne Shell, but setting the SHELL macro may change
this.  Shell commands may take up multiple lines, as long as each
non-final line ends with a backslash, and each continuation line is
intended with a TAB.  For every occurrence of <shell commands>, a
separate shell interpreter is started, i.e., shell or environment
variables set in one <shell commands> aren't available in a separate
occurrence of <shell commands>.

> Requiring a specific version of make gives us instant documentation of
> what may be used in the GCC makefiles.

This is not entirely true.  See the manual above, and notice the
passage that discusses the syntax for shell commands.  That's where
most people introduce non-portable constructs, and choosing one
particular version of make won't help us in this regard.

-- 
Alexandre Oliva   Enjoy Guarana', see http://www.ic.unicamp.br/~oliva/
Red Hat GCC Developer                 aoliva@{redhat.com, gcc.gnu.org}
CS PhD student at IC-Unicamp        oliva@{lsd.ic.unicamp.br, gnu.org}
Free Software Evangelist                Professional serial bug killer