[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Patch: More manual updates
From: |
Tom Tromey |
Subject: |
Patch: More manual updates |
Date: |
31 May 2001 23:30:29 -0600 |
I'm checking this in.
Feel free to make suggestions for the manual to-do list.
I'm trying to do a few items each night. I'm noticing that 1.5 is
hugely different from 1.4 :-)
2001-05-31 Tom Tromey <address@hidden>
* automake.texi (Alternative): New node.
(Macros): Use new name for gcc.
(Java Support): Likewise.
(Dependencies): Rewrote.
(Invoking Automake): (Re-)document -i, --ignore-deps, and
--include-deps.
Tom
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.212
diff -u -r1.212 automake.texi
--- automake.texi 2001/05/31 17:32:55 1.212
+++ automake.texi 2001/06/01 05:16:08
@@ -114,6 +114,7 @@
* Invoking Automake:: Creating a Makefile.in
* configure:: Scanning configure.ac or configure.in
* Top level:: The top-level Makefile.am
+* Alternative:: An alternative approach to subdirectories
* Rebuilding:: Automatic rebuilding of Makefile
* Programs:: Building programs and libraries
* Other objects:: Other derived objects
@@ -869,13 +870,15 @@
Print a summary of the command line options and exit.
@item -i
address@hidden --include-deps
address@hidden --ignore-deps
@opindex -i
+This disables the dependency tracking feature; see @ref{Dependencies}.
+
address@hidden --include-deps
@opindex --include-deps
-Include all automatically generated dependency information
-(@pxref{Dependencies}) in the generated
address@hidden This is generally done when making a distribution;
-see @ref{Dist}.
+This enables the dependency tracking feature. This feature is enabled
+by default. This option is provided for historical reasons only and
+probably should not be used.
@item --no-force
@opindex --no-force
@@ -1337,7 +1340,7 @@
@item AM_PROG_GCJ
This macro finds the @code{gcj} program or causes an error. It sets
@samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
-GNU C compiler.
+GNU Compiler Collection.
@cvindex AM_PROG_GCJ
@item AM_SANITY_CHECK
@@ -1409,7 +1412,7 @@
installed in @file{$(datadir)/aclocal}.
address@hidden Top level, Rebuilding, configure, Top
address@hidden Top level, Alternative, configure, Top
@chapter The top-level @file{Makefile.am}
@cindex SUBDIRS, explained
@@ -1497,8 +1500,47 @@
full list of subdirectories in the project. If this macro is not set,
Automake will attempt to set it for you.
+
address@hidden Alternative, Rebuilding, Top level, Top
address@hidden An Alternative Approach to Subdirectories
+
+If you've ever read Peter Miller's excellent paper,
address@hidden://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
+Recursive Make Considered Harmful}, the preceding section on the use of
+subdirectories will probably come as unwelcome advice. For those who
+haven't read the paper, Miller's main thesis is that recursive
address@hidden invocations are both slow and error-prone.
+
+Automake provides sufficient cross-directory support @footnote{We
+believe. This work is new and there are probably warts.
address@hidden, for information on reporting bugs.} to enable you
+to write a single @file{Makefile.am} for a complex multi-directory
+package.
+
+
+By default an installable file specified in a subdirectory will have its
+directory name stripped before installation. For instance, in this
+example, the header file will be installed as
address@hidden(includedir)/stdio.h}:
+
address@hidden
+include_HEADERS = inc/stdio.h
address@hidden example
+
address@hidden nobase_
address@hidden Path stripping, avoiding
address@hidden Avoiding path stripping
+
+However, the @samp{nobase_} prefix can be used to circumvent this path
+stripping. In this example, the header file will be installed as
address@hidden(includedir)/sys/types.h}:
address@hidden Rebuilding, Programs, Top level, Top
address@hidden
+nobase_include_HEADERS = sys/types.h
address@hidden example
+
+
address@hidden Rebuilding, Programs, Alternative, Top
@chapter Rebuilding Makefiles
Automake generates rules to automatically rebuild @file{Makefile}s,
@@ -1816,6 +1858,7 @@
@item maude_LIBADD
@item maude_LDADD
@item maude_LDFLAGS
+FIXME
@item maude_CFLAGS
Automake allows you to set compilation flags on a per-program (or
@@ -1833,7 +1876,7 @@
object file will be named, for instance, @file{maude-sample.o}.
@item maude_DEPENDENCIES
-
+FIXME
@item maude_SHORTNAME
On some platforms the allowable file names are very short. In order to
@@ -2373,7 +2416,7 @@
@cindex Support for Java
Automake includes support for compiled Java, using @code{gcj}, the Java
-front end to the GNU C compiler.
+front end to the GNU Compiler Collection.
Any package including Java code to be compiled must define the output
variable @samp{GCJ} in @file{configure.in}; the variable @samp{GCJFLAGS}
@@ -2469,56 +2512,42 @@
As a developer it is often painful to continually update the
@file{Makefile.in} whenever the include-file dependencies change in a
project. Automake supplies a way to automatically track dependency
-changes, and distribute the dependencies in the generated
address@hidden
+changes.
-Currently this support requires the use of GNU @code{make} and
address@hidden It might become possible in the future to supply a
-different dependency generating program, if there is enough demand. In
-the meantime, this mode is enabled by default if any C program or
-library is defined in the current directory, so you may get a @samp{Must
-be a separator} error from non-GNU make.
-
address@hidden dist
-
-When you decide to make a distribution, the @code{dist} target will
-re-run @code{automake} with @samp{--include-deps} and other options.
address@hidden Automake}, and @ref{Options}. This will cause the
-previously generated dependencies to be inserted into the generated
address@hidden, and thus into the distribution. This step also
-turns off inclusion of the dependency generation code, so that those who
-download your distribution but don't use GNU @code{make} and @code{gcc}
-will not get errors.
-
address@hidden OMIT_DEPENDENCIES
-
-When added to the @file{Makefile.in}, the dependencies have all
-system-specific dependencies automatically removed. This can be done by
-listing the files in @samp{OMIT_DEPENDENCIES}. For instance all
-references to system header files are removed by Automake. Sometimes it
-is useful to specify that a certain header file should be removed. For
-instance if your @file{configure.in} uses @samp{AM_WITH_REGEX}, then any
-dependency on @file{rx.h} or @file{regex.h} should be removed, because
-the correct one cannot be known until the user configures the package.
-
-As it turns out, Automake is actually smart enough to handle the
-particular case of the regular expression header. It will also
-automatically omit @file{libintl.h} if @samp{AM_GNU_GETTEXT} is used.
address@hidden Dependency tracking
address@hidden Automatic dependency tracking
+Automake always uses complete dependencies for a compilation, including
+system headers. Automake's model is that dependency computation should
+be a side effect of the build. To this end, dependencies are computed
+by running all compilations through a special wrapper program called
address@hidden @code{depcomp} understands how to coax many different C
+and C++ compilers into generating dependency information in the format
+it requires. @code{automake -a} will install @code{depcomp} into your
+source tree for you. If @code{depcomp} can't figure out how to properly
+invoke your compiler, dependency tracking will simply be disabled for
+your build.
+
address@hidden depcomp
+
+Experience with earlier versions of Automake taught us that it is not
+reliable to generate dependencies only on the maintainer's system, as
+configurations vary too much. So instead Automake implements dependency
+tracking at build time.
+
+Automatic dependency tracking can be suppressed by putting
address@hidden in the variable @code{AUTOMAKE_OPTIONS}. Or, you
+can invoke @code{automake} with the @code{-i} option. Dependency
+tracking is enabled by default.
+
@vindex AUTOMAKE_OPTIONS
@opindex no-dependencies
-Automatic dependency tracking can be suppressed by putting
address@hidden in the variable @code{AUTOMAKE_OPTIONS}.
+The person building your package also can choose to disable dependency
+tracking by configuring with @code{--disable-dependency-tracking}.
-If you unpack a distribution made by @code{make dist}, and you want to
-turn on the dependency-tracking code again, simply re-run
address@hidden
-
-The actual dependency files are put under the build directory, in a
-subdirectory named @file{.deps}. These dependencies are machine
-specific. It is safe to delete them if you like; they will be
-automatically recreated during the next build.
address@hidden Disabling dependency tracking
address@hidden Dependency tracking, disabling
@node Other objects, Other GNU Tools, Programs, Top
@@ -3097,11 +3126,9 @@
@cindex make install support
Naturally, Automake handles the details of actually installing your
-program once it has been built. All @code{PROGRAMS}, @code{SCRIPTS},
address@hidden, @code{LISP}, @code{DATA} and @code{HEADERS} are
-automatically installed in the appropriate places.
-
-Automake also handles installing any specified info and man pages.
+program once it has been built. All files named by the various
+primaries are automatically installed in the appropriate places when the
+user runs @code{make install}.
Automake generates separate @code{install-data} and @code{install-exec}
targets, in case the installer is installing on multiple machines which
- Patch: More manual updates,
Tom Tromey <=