FYI: doc update for PR/151 and PR/314

[Alexandre Duret-Lutz]

I'm checking this on branch-1-6 and HEAD.

This make explicit that address@hidden@' requires
address@hidden@'.

It also shows how to define part of the some sources conditionally:

   bin_PROGRAMS = hello
   if LINUX
   hello_cond = hello-linux.c
   else
   hello_cond = hello-generic.c
   endif
   hello_SOURCES = hello-common.c $(hello_cond)

(Something people usually try to solve using +=.)

2002-04-22  Alexandre Duret-Lutz  <address@hidden>

        For PR automake/151 and PR automake/314:
        * automake.texi (A Program): Split into
        (Program Sources, Linking, Conditional Sources, Conditional
        Programs): ... these subsections; moving the Linking node
        before the Conditional discussions.
        (Conditional Sources): More details.  Notably, mention
        hello_DEPENDENCIES.
        (Conditionals): Adjust reference to Conditional Programs.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.273
diff -u -r1.273 automake.texi
--- automake.texi       19 Apr 2002 10:13:27 -0000      1.273
+++ automake.texi       22 Apr 2002 18:16:44 -0000
@@ -1793,7 +1793,22 @@
 @node A Program, A Library, Programs, Programs
 @section Building a program
 
address@hidden Introductory blathering
+In order to build a program, you need to tell Automake which sources
+are part of it, and which libraries it should be linked with.
+
+This section also covers conditional compilation of sources or
+programs.  Most of the comments about these also apply to libraries
+(@pxref{A Library}) and Libtool libraries (@pxref{A Shared Library}).
+
address@hidden
+* Program Sources::             Defining program sources
+* Linking::                     Linking with libraries or extra objects
+* Conditional Sources::         Handling conditional sources
+* Conditional Programs::        Building program conditionally
address@hidden menu
+
address@hidden Program Sources, Linking, A Program, A Program
address@hidden Defining program sources
 
 @cindex PROGRAMS, bindir
 @vindex bin_PROGRAMS
@@ -1859,64 +1874,8 @@
 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
 and Lex}.
 
address@hidden Conditional compilations
-
-You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
address@hidden variable.  The reason for this is a bit hard to explain,
-but suffice to say that it simply won't work.  Automake will give an
-error if you try to do this.
-
address@hidden EXTRA_prog_SOURCES, defined
-
-Automake must know all the source files that could possibly go into a
-program, even if not all the files are built in every circumstance.
-Any files which are only conditionally built should be listed in the
-appropriate @samp{EXTRA_} variable.  For instance, if
address@hidden were conditionally included in @code{hello}, the
address@hidden would contain:
-
address@hidden
-EXTRA_hello_SOURCES = hello-linux.c
address@hidden example
-
-In this case, @file{hello-linux.o} would be added, via a
address@hidden substitution, to @code{hello_LDADD} in order to cause
-it to be built and linked in.
-
-An often simpler way to compile source files conditionally is to use
-Automake conditionals.  For instance, you could use this construct to
-conditionally use @file{hello-linux.c} or @file{hello-generic.c} as the
-basis for your program @file{hello}:
-
address@hidden
-if LINUX
-hello_SOURCES = hello-linux.c
-else
-hello_SOURCES = hello-generic.c
-endif
address@hidden example
-
-When using conditionals like this you don't need to use the
address@hidden variable, because Automake will examine the contents of
-each variable to construct the complete list of source files.
-
-Sometimes it is useful to determine the programs that are to be built at
-configure time.  For instance, GNU @code{cpio} only builds @code{mt} and
address@hidden under special circumstances.
-
address@hidden EXTRA_PROGRAMS, defined
-
-In this case, you must notify Automake of all the programs that can
-possibly be built, but at the same time cause the generated
address@hidden to use the programs specified by @code{configure}.
-This is done by having @code{configure} substitute values into each
address@hidden definition, while listing all optionally built programs
-in @code{EXTRA_PROGRAMS}.
address@hidden EXTRA_PROGRAMS
-
-Of course you can use Automake conditionals to determine the programs to
-be built.
 
address@hidden Linking, Conditional Sources, Program Sources, A Program
 @subsection Linking the program
 
 If you need to link against libraries that are not found by
@@ -1984,6 +1943,112 @@
 generated.
 
 
address@hidden Conditional Sources, Conditional Programs, Linking, A Program
address@hidden Conditional compilation of sources
+
+You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a
address@hidden variable.  The reason for this is a bit hard to explain,
+but suffice to say that it simply won't work.  Automake will give an
+error if you try to do this.
+
+Fortunatly there are two other ways to achieve the same result.  One is
+to use configure substitutions in @code{_LDADD} variables, the other is
+to use an Automake conditional.
+
address@hidden Conditional compilation using @code{_LDADD} substitutions
+
address@hidden EXTRA_prog_SOURCES, defined
+
+Automake must know all the source files that could possibly go into a
+program, even if not all the files are built in every circumstance.  Any
+files which are only conditionally built should be listed in the
+appropriate @samp{EXTRA_} variable.  For instance, if
address@hidden or @file{hello-generic.c} were conditionally included
+in @code{hello}, the @file{Makefile.am} would contain:
+
address@hidden
+bin_PROGRAMS = hello
+hello_SOURCES = hello-common.c
+EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
+hello_LDADD = @@HELLO_SYSTEM@@
+hello_DEPENDENCIES = @@HELLO_SYSTEM@@
address@hidden example
+
address@hidden
+You can then setup the @code{@@HELLO_SYSTEM@@} substitution from
address@hidden:
+
address@hidden
+...
+case $host in
+  *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
+  *)       HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
+esac
+AC_SUBST([HELLO_SYSTEM])
+...
address@hidden example
+
+In this case, @code{HELLO_SYSTEM} should be replaced by
address@hidden or @file{hello-bsd.o}, and added to
address@hidden and @code{hello_LDADD} in order to be built
+and linked in.
+
address@hidden Conditional compilation using Automake conditionals
+
+An often simpler way to compile source files conditionally is to use
+Automake conditionals.  For instance, you could use this
address@hidden construct to build the same @file{hello} example:
+
address@hidden
+bin_PROGRAMS = hello
+if LINUX
+hello_SOURCES = hello-linux.c hello-common.c
+else
+hello_SOURCES = hello-generic.c hello-common.c
+endif
address@hidden example
+
+In this case, your @file{configure.in} should setup the @code{LINUX}
+conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
+
+When using conditionals like this you don't need to use the
address@hidden variable, because Automake will examine the contents of
+each variable to construct the complete list of source files.
+
+If your program uses a lot of files, you will probably prefer to use an
+intermediate variable to hold conditional sources.
+
address@hidden
+bin_PROGRAMS = hello
+if LINUX
+hello_cond = hello-linux.c
+else
+hello_cond = hello-generic.c
+endif
+hello_SOURCES = hello-common.c $(hello_cond)
address@hidden example
+
address@hidden Conditional Programs,  , Conditional Sources, A Program
address@hidden Conditional compilation of programs
+
+Sometimes it is useful to determine the programs that are to be built at
+configure time.  For instance, GNU @code{cpio} only builds @code{mt} and
address@hidden under special circumstances.
+
address@hidden EXTRA_PROGRAMS, defined
+
+In this case, you must notify Automake of all the programs that can
+possibly be built, but at the same time cause the generated
address@hidden to use the programs specified by @code{configure}.
+This is done by having @code{configure} substitute values into each
address@hidden definition, while listing all optionally built programs
+in @code{EXTRA_PROGRAMS}.
address@hidden EXTRA_PROGRAMS
+
+Of course you can use Automake conditionals to determine the programs to
+be built.
+
+
 @node A Library, A Shared Library, A Program, Programs
 @section Building a library
 
@@ -4375,7 +4440,7 @@
 @end example
 
 This trivial example could also be handled using EXTRA_PROGRAMS
-(@pxref{A Program}).
+(@pxref{Conditional Programs}).
 
 You may only test a single variable in an @code{if} statement, possibly
 negated using @samp{!}.  The @code{else} statement may be omitted.
Index: stamp-vti
===================================================================
RCS file: /cvs/automake/automake/stamp-vti,v
retrieving revision 1.174
diff -u -r1.174 stamp-vti
--- stamp-vti   19 Apr 2002 10:13:27 -0000      1.174
+++ stamp-vti   22 Apr 2002 18:16:44 -0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 19 April 2002
address@hidden UPDATED 22 April 2002
 @set UPDATED-MONTH April 2002
 @set EDITION 1.6a
 @set VERSION 1.6a
Index: version.texi
===================================================================
RCS file: /cvs/automake/automake/version.texi,v
retrieving revision 1.247
diff -u -r1.247 version.texi
--- version.texi        19 Apr 2002 10:13:28 -0000      1.247
+++ version.texi        22 Apr 2002 18:16:44 -0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 19 April 2002
address@hidden UPDATED 22 April 2002
 @set UPDATED-MONTH April 2002
 @set EDITION 1.6a
 @set VERSION 1.6a

-- 
Alexandre Duret-Lutz