From 5c176e2f355cbc92885f3dcb929e71d12e143d0b Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Mon, 22 Apr 2002 18:25:05 +0000 Subject: [PATCH] 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. --- ChangeLog | 11 +++ automake.texi | 183 ++++++++++++++++++++++++++++++++++---------------- stamp-vti | 2 +- version.texi | 2 +- 4 files changed, 137 insertions(+), 61 deletions(-) diff --git a/ChangeLog b/ChangeLog index ee7b215b..7710feab 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2002-04-22 Alexandre Duret-Lutz + + 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. + 2002-04-19 Paul Eggert Fix some bugs when using "$@" when there might be zero positional diff --git a/automake.texi b/automake.texi index 555e2b66..f1233d6f 100644 --- a/automake.texi +++ b/automake.texi @@ -1793,7 +1793,22 @@ to build programs and libraries. @node A Program, A Library, Programs, Programs @section Building a program -@subsection 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}). + +@menu +* Program Sources:: Defining program sources +* Linking:: Linking with libraries or extra objects +* Conditional Sources:: Handling conditional sources +* Conditional Programs:: Building program conditionally +@end menu + +@node Program Sources, Linking, A Program, A Program +@subsection Defining program sources @cindex PROGRAMS, bindir @vindex bin_PROGRAMS @@ -1859,64 +1874,8 @@ should not include the header file generated by @file{configure} in a (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc and Lex}. -@subsection Conditional compilations - -You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a -@samp{_SOURCES} 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. - -@cindex 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 -@file{hello-linux.c} were conditionally included in @code{hello}, the -@file{Makefile.am} would contain: - -@example -EXTRA_hello_SOURCES = hello-linux.c -@end example - -In this case, @file{hello-linux.o} would be added, via a -@file{configure} 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}: - -@example -if LINUX -hello_SOURCES = hello-linux.c -else -hello_SOURCES = hello-generic.c -endif -@end example - -When using conditionals like this you don't need to use the -@samp{EXTRA_} 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 -@code{rmt} under special circumstances. - -@cindex 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 -@file{Makefile.in} to use the programs specified by @code{configure}. -This is done by having @code{configure} substitute values into each -@samp{_PROGRAMS} definition, while listing all optionally built programs -in @code{EXTRA_PROGRAMS}. -@vindex EXTRA_PROGRAMS - -Of course you can use Automake conditionals to determine the programs to -be built. +@node 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 @@ cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be generated. +@node Conditional Sources, Conditional Programs, Linking, A Program +@subsection Conditional compilation of sources + +You can't put a configure substitution (e.g., @samp{@@FOO@@}) into a +@samp{_SOURCES} 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. + +@subsubsection Conditional compilation using @code{_LDADD} substitutions + +@cindex 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 +@file{hello-linux.c} or @file{hello-generic.c} were conditionally included +in @code{hello}, the @file{Makefile.am} would contain: + +@example +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@@ +@end example + +@noindent +You can then setup the @code{@@HELLO_SYSTEM@@} substitution from +@file{configure.in}: + +@example +... +case $host in + *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;; + *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;; +esac +AC_SUBST([HELLO_SYSTEM]) +... +@end example + +In this case, @code{HELLO_SYSTEM} should be replaced by +@file{hello-linux.o} or @file{hello-bsd.o}, and added to +@code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be built +and linked in. + +@subsubsection 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 +@file{Makefile.am} construct to build the same @file{hello} example: + +@example +bin_PROGRAMS = hello +if LINUX +hello_SOURCES = hello-linux.c hello-common.c +else +hello_SOURCES = hello-generic.c hello-common.c +endif +@end 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 +@samp{EXTRA_} 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. + +@example +bin_PROGRAMS = hello +if LINUX +hello_cond = hello-linux.c +else +hello_cond = hello-generic.c +endif +hello_SOURCES = hello-common.c $(hello_cond) +@end example + +@node Conditional Programs, , Conditional Sources, A Program +@subsection 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 +@code{rmt} under special circumstances. + +@cindex 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 +@file{Makefile.in} to use the programs specified by @code{configure}. +This is done by having @code{configure} substitute values into each +@samp{_PROGRAMS} definition, while listing all optionally built programs +in @code{EXTRA_PROGRAMS}. +@vindex 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 @@ noinst_PROGRAMS = $(DBG) @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. diff --git a/stamp-vti b/stamp-vti index ed5cae0a..b5432b2f 100644 --- a/stamp-vti +++ b/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 19 April 2002 +@set UPDATED 22 April 2002 @set UPDATED-MONTH April 2002 @set EDITION 1.6a @set VERSION 1.6a diff --git a/version.texi b/version.texi index ed5cae0a..b5432b2f 100644 --- a/version.texi +++ b/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 19 April 2002 +@set UPDATED 22 April 2002 @set UPDATED-MONTH April 2002 @set EDITION 1.6a @set VERSION 1.6a -- 2.43.5