FYI: FAQ entry for renamed objects

[Alexandre Duret-Lutz]

I'm installing this on HEAD and branch-1-7.

The `renamed objects' part is comes from a mail I sent to
address@hidden on April 13.

2003-05-11  Alexandre Duret-Lutz  <address@hidden>

        * 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.

Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.336
diff -u -r1.336 automake.texi
--- automake.texi       6 May 2003 12:07:22 -0000       1.336
+++ automake.texi       11 May 2003 19:51:41 -0000
@@ -2715,6 +2715,20 @@
 This variable is used to pass extra flags to the link step of a program
 or a shared library.
 
address@hidden 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
address@hidden, with most configure substitutions, @samp{-l}, @samp{-L},
address@hidden and @samp{-dlpreopen} options removed.  The configure
+substitutions that are left in are only @samp{$(LIBOBJS)} and
address@hidden(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 @@
 @itemx maude_OBJCFLAGS
 @itemx maude_RFLAGS
 @itemx maude_YFLAGS
address@hidden 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 @@
 @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 @@
 @end example
 
 
address@hidden 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
address@hidden, with most configure substitutions, @samp{-l}, @samp{-L},
address@hidden and @samp{-dlpreopen} options removed.  The configure
-substitutions that are left in are only @samp{$(LIBOBJS)} and
address@hidden(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
address@hidden to @samp{m}, then in the above per-program
-compilation flag example the object file would be named
address@hidden rather than @file{maude-sample.o}.  This facility is
-rarely needed in practice, and we recommend avoiding it until you find
-it is required.
address@hidden table
+how intermediate object files are named.  For instance, in the following
+example,
 
address@hidden
+bin_PROGRAMS = maude
+maude_CPPFLAGS = -DSOMEFLAG
+maude_SHORTNAME = m
+maude_SOURCES = sample.c @dots{}
address@hidden example
+
address@hidden
+the object file would be named @file{m-sample.o} rather than
address@hidden
+
+This facility is rarely needed in practice,
+and we recommend avoiding it until you find it is required.
address@hidden table
 
 @node LIBOBJS, Program variables, Program and Library Variables, Programs
 @section Special handling for LIBOBJS and ALLOCA
@@ -5620,6 +5631,7 @@
 * 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 @@
 You can get warnings about @code{$(wildcard ...}) constructs using the
 @code{-Wportability} flag.
 
address@hidden distcleancheck,  , wildcards, FAQ
address@hidden 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 @@
 complains before you do this.  @code{distcleancheck_listfiles} is a
 way to @emph{hide} errors, not to fix them.  You can always do better.
 
address@hidden renamed objects,  , distcleancheck, FAQ
address@hidden 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.
+
address@hidden
+bin_PROGRAMS = true false
+true_SOURCES = generic.c
+true_CPPFLAGS = -DEXIT_CODE=0
+false_SOURCES = generic.c
+false_CPPFLAGS = -DEXIT_CODE=1
address@hidden example
address@hidden
+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*
address@hidden  Therefore @command{automake} outputs rules to
+build two different objects: @file{true-generic.o} and
address@hidden
+
address@hidden 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
address@hidden in the following example.
+
address@hidden
+AM_CPPFLAGS = -DVERSION=1.0
+bin_PROGRAMS = true false
+true_SOURCES = true.c version.c
+false_SOURCES = false.c version.c
address@hidden example
+
+Note that the renaming of objects is also affected by the
address@hidden 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 @@
 @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
address@hidden  LocalWords:  DSOMEFLAG DVERSION

-- 
Alexandre Duret-Lutz