FYI: Per-Object Flags doc

[Alexandre Duret-Lutz]

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

2004-12-11  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (Per-Object Flags): New node.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.73
diff -u -r1.73 automake.texi
--- doc/automake.texi   9 Dec 2004 21:48:20 -0000       1.73
+++ doc/automake.texi   11 Dec 2004 00:29:05 -0000
@@ -252,6 +252,7 @@
 * distcleancheck::              Files left in build directory after distclean
 * Flag Variables Ordering::     CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
 * renamed objects::             Why are object files sometimes renamed?
+* Per-Object Flags::            How to simulate per-object flags?
 * Multiple Outputs::            Writing rules for tools with many output files
 
 History of Automake
@@ -7448,6 +7449,7 @@
 * distcleancheck::              Files left in build directory after distclean
 * Flag Variables Ordering::     CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
 * renamed objects::             Why are object files sometimes renamed?
+* Per-Object Flags::            How to simulate per-object flags?
 * Multiple Outputs::            Writing rules for tools with many output files
 @end menu
 
@@ -8142,6 +8144,7 @@
 variable), and @code{mumble_LIBADD} exists only as a per-target
 variable.  (@pxref{Program and Library Variables}.)
 
+
 @node renamed objects
 @section Why are object files sometimes renamed?
 
@@ -8185,6 +8188,76 @@
 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
 
 
address@hidden Per-Object Flags
address@hidden Per-Object Flags Emulation
address@hidden Per-object flags, emulated
+
address@hidden
+One of my source files needs to be compiled with different flags.  How
+do I do?
address@hidden display
+
+Automake supports per-program and per-library compilation flags (see
address@hidden and Library Variables} and @ref{Flag Variables
+Ordering}).  With this you can define compilation flags that apply to
+all files compiled for a target.  For instance in
+
address@hidden
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c foo.h bar.c bar.h main.c
+foo_CFLAGS = -some -flags
address@hidden example
+
address@hidden
address@hidden, @file{foo-bar.o}, and @file{foo-main.o} will all be
+compiled with @code{-some -flags}.  (If you wonder about the names of
+these object files, see @ref{renamed objects}.)  Note that
address@hidden gives the flags to use when compiling all the C
+sources of the @emph{program} @code{foo}, it has nothing to do with
address@hidden or @file{foo-foo.o} specifically.
+
+What if @file{foo.c} needs to be compiled into @file{foo.o} using some
+specific flags, that none of the other files require?  Obviously
+per-program flags are not directly applicable here.  Something like
+per-object flags are expected, i.e., flags that would be used only
+when creating @file{foo-foo.o}.  Automake does not support that,
+however this is easy to simulate using a library that contains only
+that object, and compiling this library with per-library flags.
+
address@hidden
+bin_PROGRAMS = foo
+foo_SOURCES = bar.c bar.h main.c
+foo_CFLAGS = -some -flags
+foo_LDADD = libfoo.a
+noinst_LIBRARIES = libfoo.a
+libfoo_a_SOURCES = foo.c foo.h
+libfoo_a_CFLAGS = -some -other -flags
address@hidden example
+
+Here @file{foo-bar.o} and @file{foo-main.o} will all be
+compiled with @code{-some -flags}, while @file{libfoo_a-foo.o} will
+be compiled using @code{-some -other -flags}.  Eventually, all
+three objects will be linked to form @file{foo}.
+
+This trick can also be achieved using Libtool convenience libraries,
+i.e., @code{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
+Convenience Libraries}).
+
+Another tempting idea to implement per-object flags is to override the
+compile rules @command{automake} would output for these files.
+Automake will not define a rule for a target you have defined, so you
+could think about defining the @code{foo-foo.o: foo.c} rule yourself.
+We recommend against this, because this is error prone.  For instance
+if you add such a rule to the first example, it will break the day you
+decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
+compiled as @file{foo.o} instead of @file{foo-foo.o}, see @ref{renamed
+objects}).  Also in order to support dependency tracking, the two
address@hidden/@file{.obj} extensions, and all the other flags variables
+involved in a compilation, you will end up modifying a copy of the
+rule previously output by @command{automake} for this file.  If a new
+release of Automake generates a different rule, your copy will need to
+be updated by hand.
+
 @node Multiple Outputs
 @section Handling Tools that Produce Many Outputs
 @cindex multiple outputs, rules with
@@ -9623,5 +9696,5 @@
 @c  LocalWords:  syscalls perlhist acl pm multitable headitem fdl appendixsec
 @c  LocalWords:  LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
 @c  LocalWords:  unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
address@hidden  LocalWords:  LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir
address@hidden  LocalWords:  LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj
 @c  LocalWords:  barexec Pinard's
-- 
Alexandre Duret-Lutz