From 26e9dd5314fdfe693144c8c6ada5fa32f7e1d800 Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Sun, 11 May 2003 19:56:59 +0000 Subject: [PATCH] * automake.texi (renamed objects): New node. (Program and Library Variables): Move maude_DEPENDENCIES closer to maude_LDADD. Define and use `per-target compilation flags' in the explanation for maude_CFLAGS et al. Link to the `renamed objects' node. Illustrate maude_SHORTNAME. --- ChangeLog | 8 ++++ automake.texi | 107 ++++++++++++++++++++++++++++++++++++++------------ stamp-vti | 2 +- version.texi | 2 +- 4 files changed, 91 insertions(+), 28 deletions(-) diff --git a/ChangeLog b/ChangeLog index a603863a..9b1a1761 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2003-05-11 Alexandre Duret-Lutz + + * automake.texi (renamed objects): New node. + (Program and Library Variables): Move maude_DEPENDENCIES closer + to maude_LDADD. Define and use `per-target compilation flags' in the + explanation for maude_CFLAGS et al. Link to the `renamed objects' + node. Illustrate maude_SHORTNAME. + 2003-05-09 Alexandre Duret-Lutz * lib/install-sh: Update copyright notice and license to that of diff --git a/automake.texi b/automake.texi index 0b5d7c3d..256d53b0 100644 --- a/automake.texi +++ b/automake.texi @@ -2715,6 +2715,20 @@ maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS) This variable is used to pass extra flags to the link step of a program or a shared library. +@item maude_DEPENDENCIES +It is also occasionally useful to have a program depend on some other +target which is not actually part of that program. This can be done +using the @samp{_DEPENDENCIES} variable. Each program depends on the +contents of such a variable, but no further interpretation is done. + +If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake. +The automatically-assigned value is the contents of @samp{_LDADD} or +@samp{_LIBADD}, with most configure substitutions, @samp{-l}, @samp{-L}, +@samp{-dlopen} and @samp{-dlpreopen} options removed. The configure +substitutions that are left in are only @samp{$(LIBOBJS)} and +@samp{$(ALLOCA)}; these are left because it is known that they will not +cause an invalid value for @samp{_DEPENDENCIES} to be generated. + @item maude_LINK You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. For @@ -2738,11 +2752,12 @@ maude_LINK = $(CCLD) -magic -o $@@ @itemx maude_OBJCFLAGS @itemx maude_RFLAGS @itemx maude_YFLAGS +@cindex per-target compilation flags, defined Automake allows you to set compilation flags on a per-program (or per-library) basis. A single source file can be included in several programs, and it will potentially be compiled with different flags for each program. This works for any language directly supported by -Automake. The flags are +Automake. These @dfn{per-target compilation flags} are @samp{_CCASFLAGS}, @samp{_CFLAGS}, @samp{_CPPFLAGS}, @@ -2754,13 +2769,14 @@ Automake. The flags are @samp{_RFLAGS}, and @samp{_YFLAGS}. -When using a per-program compilation flag, Automake will choose a +When using a per-target compilation flag, Automake will choose a different name for the intermediate object files. Ordinarily a file like @file{sample.c} will be compiled to produce @file{sample.o}. However, if the program's @samp{_CFLAGS} variable is set, then the object file will be named, for instance, @file{maude-sample.o}. +(See also @ref{renamed objects}.) -In compilations with per-program flags, the ordinary @samp{AM_} form of +In compilations with per-target flags, the ordinary @samp{AM_} form of the flags variable is @emph{not} automatically included in the compilation (however, the user form of the variable @emph{is} included). So for instance, if you want the hypothetical @file{maude} compilations @@ -2771,32 +2787,27 @@ maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS) @end example -@item maude_DEPENDENCIES -It is also occasionally useful to have a program depend on some other -target which is not actually part of that program. This can be done -using the @samp{_DEPENDENCIES} variable. Each program depends on the -contents of such a variable, but no further interpretation is done. - -If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake. -The automatically-assigned value is the contents of @samp{_LDADD} or -@samp{_LIBADD}, with most configure substitutions, @samp{-l}, @samp{-L}, -@samp{-dlopen} and @samp{-dlpreopen} options removed. The configure -substitutions that are left in are only @samp{$(LIBOBJS)} and -@samp{$(ALLOCA)}; these are left because it is known that they will not -cause an invalid value for @samp{_DEPENDENCIES} to be generated. - @item maude_SHORTNAME On some platforms the allowable file names are very short. In order to -support these systems and per-program compilation flags at the same +support these systems and per-target compilation flags at the same time, Automake allows you to set a ``short name'' which will influence -how intermediate object files are named. For instance, if you set -@samp{maude_SHORTNAME} to @samp{m}, then in the above per-program -compilation flag example the object file would be named -@file{m-sample.o} rather than @file{maude-sample.o}. This facility is -rarely needed in practice, and we recommend avoiding it until you find -it is required. -@end table +how intermediate object files are named. For instance, in the following +example, + +@example +bin_PROGRAMS = maude +maude_CPPFLAGS = -DSOMEFLAG +maude_SHORTNAME = m +maude_SOURCES = sample.c @dots{} +@end example + +@noindent +the object file would be named @file{m-sample.o} rather than +@file{maude-sample.o}. +This facility is rarely needed in practice, +and we recommend avoiding it until you find it is required. +@end table @node LIBOBJS, Program variables, Program and Library Variables, Programs @section Special handling for LIBOBJS and ALLOCA @@ -5620,6 +5631,7 @@ lists. * maintainer-mode:: missing and AM_MAINTAINER_MODE * wildcards:: Why doesn't Automake support wildcards? * distcleancheck:: Files left in build directory after distclean +* renamed objects:: Why are object files sometimes renamed? @end menu @node CVS, maintainer-mode, FAQ, FAQ @@ -5940,7 +5952,7 @@ variables as far Automake is concerned. You can get warnings about @code{$(wildcard ...}) constructs using the @code{-Wportability} flag. -@node distcleancheck, , wildcards, FAQ +@node distcleancheck, renamed objects, wildcards, FAQ @section Files left in build directory after distclean @cindex distclean, diagnostic @cindex dependencies and distributed files @@ -6087,6 +6099,48 @@ Make sure you do understand the reason why @code{make distcheck} complains before you do this. @code{distcleancheck_listfiles} is a way to @emph{hide} errors, not to fix them. You can always do better. +@node renamed objects, , distcleancheck, FAQ +@section Why are object files sometimes renamed? + +This happens when per-target compilation flags are used. Object +files need to be renamed just in case they would clash with object +files compiled from the same sources, but with different flags. +Consider the following example. + +@example +bin_PROGRAMS = true false +true_SOURCES = generic.c +true_CPPFLAGS = -DEXIT_CODE=0 +false_SOURCES = generic.c +false_CPPFLAGS = -DEXIT_CODE=1 +@end example +@noindent +Obviously the two programs are built from the same source, but it +would be bad if they shared the same object, because @file{generic.o} +cannot be built with both @code{-DEXIT_CODE=0} *and* +@code{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to +build two different objects: @file{true-generic.o} and +@file{false-generic.o}. + +@command{automake} doesn't actually look whether sources files are +shared to decide if it must rename objects. It will just rename all +objects of a target as soon as it sees per-target compilation flags +are used. + +It's OK to share object files when per-target compilation flags are not +used. For instance @file{true} and @file{false} will both use +@file{version.o} in the following example. + +@example +AM_CPPFLAGS = -DVERSION=1.0 +bin_PROGRAMS = true false +true_SOURCES = true.c version.c +false_SOURCES = false.c version.c +@end example + +Note that the renaming of objects is also affected by the +@code{_SHORTNAME} variable (@pxref{Program and Library Variables}). + @page @node Macro and Variable Index, General Index, FAQ, Top @unnumbered Macro and Variable Index @@ -6161,3 +6215,4 @@ way to @emph{hide} errors, not to fix them. You can always do better. @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex +@c LocalWords: DSOMEFLAG DVERSION diff --git a/stamp-vti b/stamp-vti index 4018951a..193293f7 100644 --- a/stamp-vti +++ b/stamp-vti @@ -1,4 +1,4 @@ -@set UPDATED 5 May 2003 +@set UPDATED 11 May 2003 @set UPDATED-MONTH May 2003 @set EDITION 1.7a @set VERSION 1.7a diff --git a/version.texi b/version.texi index 4018951a..193293f7 100644 --- a/version.texi +++ b/version.texi @@ -1,4 +1,4 @@ -@set UPDATED 5 May 2003 +@set UPDATED 11 May 2003 @set UPDATED-MONTH May 2003 @set EDITION 1.7a @set VERSION 1.7a -- 2.43.5