FYI: _SCRIPTS doc retake

[Alexandre Duret-Lutz]

I'm checking this in.

2006-08-04  Alexandre Duret-Lutz  <address@hidden>

        * doc/automake.texi (Scripts): Revamp.  Show an example of script
        built from configure.ac.  Discuss CLEANFILES and EXTRA_DIST for
        other built scripts.

Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.138
diff -u -r1.138 automake.texi
--- doc/automake.texi   4 Aug 2006 10:23:14 -0000       1.138
+++ doc/automake.texi   4 Aug 2006 16:11:27 -0000
@@ -5298,22 +5298,47 @@
 @cindex @code{SCRIPTS} primary, defined
 @cindex Primary variable, @code{SCRIPTS}
 @vindex _SCRIPTS
address@hidden Installing scripts
 
 It is possible to define and install programs that are scripts.  Such
-programs are listed using the @code{SCRIPTS} primary name.  Automake
-doesn't define any dependencies for scripts; the @file{Makefile.am}
-should include the appropriate rules.
+programs are listed using the @code{SCRIPTS} primary name.  When the
+script is distributed in its final, installable form, the
address@hidden usually looks as follows:
 @vindex SCRIPTS
 
-Automake does not assume that scripts are derived objects; such objects
-must be deleted by hand (@pxref{Clean}).
address@hidden
+# Install my_script in $(bindir) and distribute it.
+dist_bin_SCRIPTS = my_script
address@hidden example
+
+Script are not distributed by default; as we have just seen, those
+that should be distributed can be specified using a @code{dist_}
+prefix as with other primaries.
+
address@hidden @code{SCRIPTS}, installation directories
address@hidden bin_SCRIPTS
address@hidden sbin_SCRIPTS
address@hidden libexec_SCRIPTS
address@hidden pkgdata_SCRIPTS
address@hidden noinst_SCRIPTS
address@hidden check_SCRIPTS
+
+Scripts can be installed in @code{bindir}, @code{sbindir},
address@hidden, or @code{pkgdatadir}.
+
+Scripts that need not being installed can be listed in
address@hidden, and among them, those which are needed only by
address@hidden check} should go in @code{check_SCRIPTS}.
 
-The @command{automake} program itself is a Perl script that is generated
-from @file{automake.in}.  Here is how this is handled:
+When a script needs to be built, the @file{Makefile.am} should include
+the appropriate rules.  For instance the @command{automake} program
+itself is a Perl script that is generated from @file{automake.in}.
+Here is how this is handled:
 
 @example
 bin_SCRIPTS = automake
 CLEANFILES = $(bin_SCRIPTS)
+EXTRA_DIST = automake.in
 
 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
             -e 's,[@@]PERL[@@],$(PERL),g' \
@@ -5326,34 +5351,38 @@
         chmod +x automake
 @end example
 
-Because---as we have just seen---scripts can be built, they are not
-distributed by default.  Scripts that should be distributed can be
-specified using a @code{dist_} prefix as in other primaries.  For
-instance, the following @file{Makefile.am} declares that
address@hidden should be distributed and installed in
address@hidden(sbindir)}.
+Such scripts for which a build rule has been supplied need to be
+deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
+sources have to be distributed, usually with @code{EXTRA_DIST}
+(@pxref{Dist}).
 
address@hidden
-dist_sbin_SCRIPTS = my_script
address@hidden example
+Another common way to build scripts is to process them from
address@hidden with @code{AC_CONFIG_FILES}.  In this situation
+Automake knows which files should be cleaned and distributed, and what
+the rebuild rules should look like.
 
address@hidden @code{SCRIPTS}, installation directories
address@hidden Installing scripts
+For instance if @file{configure.ac} contains
 
address@hidden bin_SCRIPTS
address@hidden sbin_SCRIPTS
address@hidden libexec_SCRIPTS
address@hidden pkgdata_SCRIPTS
address@hidden noinst_SCRIPTS
address@hidden check_SCRIPTS
address@hidden
+AC_CONFIG_FILES([src/my_script])
address@hidden example
 
-Script objects can be installed in @code{bindir}, @code{sbindir},
address@hidden, or @code{pkgdatadir}.
address@hidden
+to build @file{src/my_script} from @file{src/my_script}, then an
address@hidden/Makefile.am} to install this script in @code{$(bindir)} can
+be as simple as
 
-Scripts that need not being installed can be listed in
address@hidden, and among them, those which are needed only by
address@hidden check} should go in @code{check_SCRIPTS}.
address@hidden
+bin_SCRIPTS = my_script
address@hidden example
 
address@hidden
+There is no need for @code{EXTRA_DIST}, @code{CLEANFILES}, or any
+build rule: Automake infers them from @code{AC_CONFIG_FILES}
+(@pxref{Requirements}).  This looks simpler, however building scripts
+this way has one drawback: directory variables such as
address@hidden(datadir)} are not fully expanded and may refer to other
+directory variables.
 
 @node Headers
 @section Header files

-- 
Alexandre Duret-Lutz

Shared books are happy books.     http://www.bookcrossing.com/friend/gadl