On Fri, Sep 12, 2014 at 6:10 PM, Shawn H Corey <shawnhcorey@xxxxxxxxx> wrote:
> No, it's not a "natural" attitude. I have worked on open-source
> projects where this attitude is not present and on proprietary ones
> which had it in spades. It depends on the people involved. And it also
> drives people away from open-source projects.
>
Attitude is subject to interpretation. None of the autoconf
maintainers said they thought the documentation had to stay exactly as
it was. I am sure that there can be changes. I think that the best
chance for changes to happen is for the person seeing the problem to
make them themselves, and hope that other people agree. Unfortunately,
unless you give specific criticism, other people can easily overlook
the points you make and it tends to get forgotten about. As an
interested bystander, I hope you can work with the autoconf
maintainers to get a graphical flowchart into one of the manuals.
Remembering that "talk is cheap", here are my own changes that I made
to the autoconf manual, the "Manual Configuration" section, based on
the "autoconf.texi" file I got from the current git repository. If
anyone has any suggestions I will see about incorporating them. I
don't mind if someone else wants to use this to inspire their own
attempt.
(I have not updated cross-references to renamed nodes yet.)
Summary of changes:
Rename "Manual Configuration" to "Canonical System Types", as the old
name was meaningless
Rename "Canonicalization" to "Getting System Types"
Remove word "deliberately" from "Specifying Target Triplets" (it
doesn't matter to the reader what the motivation of the author was)
Move list of when to use system types from "Using System Types" to
higher-level node "Canonical System Types" to give a better overview
of this feature
Move explanation of when to use "target" from "Using System Type" to
"Getting System Types" so it is next to the presentation of the three
system types
Rewrite so that introducing "build_alias" etc. doesn't appear to be a
jarring change of subject
Change heading in "Getting the Canonical System Type" to "Getting
Canonical System Types in configure Scripts"
Change heading in "Using System Type" to "Examples of Using the System Type"
--- a/autoconf.texi
+++ b/autoconf.texi
@@ -288,7 +288,7 @@ entitled ``GNU Free Documentation License.''
* Portable Shell:: Shell script portability pitfalls
* Portable Make:: Makefile portability pitfalls
* Portable C and C++:: C and C++ portability pitfalls
-* Manual Configuration:: Selecting features that can't be guessed
+* Canonical System Types:: Selecting features that can't be guessed
* Site Configuration:: Local defaults for @command{configure}
* Running configure Scripts:: How to use the Autoconf output
* config.status Invocation:: Recreating a configuration
@@ -576,10 +576,10 @@ Integer Overflow
* Signed Overflow Advice:: Practical advice for signed overflow issues
* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
-Manual Configuration
+Canonical System Types
* Specifying Target Triplets:: Specifying target triplets
-* Canonicalizing:: Getting the canonical system type
+* Getting System Types:: Getting the canonical system type
* Using System Type:: What to do with the system type
Site Configuration
@@ -21662,22 +21662,53 @@ implementation to do whatever it pleases and this includes exiting
successfully.
-@c ================================================== Manual Configuration
+@c ================================================== System Type
-@node Manual Configuration
-@chapter Manual Configuration
+@node Canonical System Types
+@anchor{Manual Configuration} @c old node name
+@chapter Canonical System Types
A few kinds of features can't be guessed automatically by running test
programs. For example, the details of the object-file format, or
-special options that need to be passed to the compiler or linker. You
-can check for such features using ad-hoc means, such as having
-@command{configure} check the output of the @code{uname} program, or
-looking for libraries that are unique to particular systems. However,
-Autoconf provides a uniform method for handling unguessable features.
+special options that need to be passed to the compiler or linker.
+
+Autoconf provides a uniform method for getting a canonical name for
+the system type, which an Autoconf-generated @command{configure}
+script can base its decisions on. (This saves you from using ad-hoc means
+to determine the system type, such as having @command{configure} check
+the output of the @code{uname} program, or looking for libraries that
+are unique to particular systems.) A canonical name is called a
+@dfn{target triplet}, and has the form:
+@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
+@samp{@var{system}} or @samp{@var{kernel}-@var{system}}
+
+Whenever you're tempted to use this feature it's worth considering
+whether some sort of probe would be better. New system types come along
+periodically or previously missing features are added. Well-written
+probes can adapt themselves to such things, but hard-coded lists of
+names can't. Here are some guidelines,
+
+@itemize @bullet
+@item
+Availability of libraries and library functions should always be checked
+by probing.
+@item
+Variant behavior of system calls is best identified with runtime tests
+if possible, but bug workarounds or obscure difficulties might have to
+be driven from the system type.
+@item
+Assembler code is inevitably highly CPU-specific and is best selected
+according to @samp{$host_cpu} (@pxref{Getting System Types}).
+@item
+Assembler variations like underscore prefix on globals or ELF versus
+COFF type directives are however best determined by probing, perhaps
+even examining the compiler output.
+@end itemize
+
@menu
* Specifying Target Triplets:: Specifying target triplets
-* Canonicalizing:: Getting the canonical system type
+* Getting System Types:: Getting the canonical system type
* Using System Type:: What to do with the system type
@end menu
@@ -21689,41 +21720,42 @@ Autoconf provides a uniform method for handling unguessable features.
@c links to still work.
@anchor{Specifying Names}
-Autoconf-generated
-@command{configure} scripts can make decisions based on a canonical name
-for the system type, or @dfn{target triplet}, which has the form:
-@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
-@samp{@var{system}} or @samp{@var{kernel}-@var{system}}
-
@command{configure} can usually guess the canonical name for the type of
system it's running on. To do so it runs a script called
@command{config.guess}, which infers the name using the @code{uname}
command or symbols predefined by the C preprocessor.
Alternately, the user can specify the system type with command line
-arguments to @command{configure} (@pxref{System Type}. Doing so is
-necessary when
-cross-compiling. In the most complex case of cross-compiling, three
-system types are involved. The options to specify them are:
+arguments to @command{configure} (@pxref{System Type}). Doing so is
+necessary when cross-compiling. In the most complex case of
+cross-compiling, three system types are involved. The options to
+specify them are:
@table @option
@item --build=@var{build-type}
-the type of system on which the package is being configured and
+The type of system on which the package is being configured and
compiled. It defaults to the result of running @command{config.guess}.
Specifying a @var{build-type} that differs from @var{host-type} enables
cross-compilation mode.
@item --host=@var{host-type}
-the type of system on which the package runs. By default it is the
+The type of system on which the package runs. By default it is the
same as the build machine. Specifying a @var{host-type} that differs
from @var{build-type}, when @var{build-type} was also explicitly
specified, enables cross-compilation mode.
@item --target=@var{target-type}
-the type of system for which any compiler tools in the package
-produce code (rarely needed). By default, it is the same as host.
+The type of system for which any compiler tools in the package
+produce code. By default, it is the same as host.
@end table
+For ordinary packages the target is meaningless and should not be used.
+The target is for use by a package creating a compiler or similar,
+and indicates what the created compiler should generate code for, if it
+can cross-compile. It generally selects various hard-coded CPU and
+system conventions, since usually the compiler or tools under
+construction themselves determine how the target works.
+
If you mean to override the result of @command{config.guess}, use
@option{--build}, not @option{--host}, since the latter enables
cross-compilation. For historical reasons,
@@ -21760,33 +21792,30 @@ example, @samp{decstation} can be used instead of
@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
@command{config.sub} to canonicalize system type aliases.
-This section deliberately omits the description of the obsolete
-interface; see @ref{Hosts and Cross-Compilation}.
+This section omits the description of the obsolete interface; see
+@ref{Hosts and Cross-Compilation}.
-@node Canonicalizing
-@section Getting the Canonical System Type
+@node Getting System Types
+@anchor{Canonicalizing} @c old node name
+@section Getting Canonical System Types in @command{configure} Scripts
@cindex System type
@cindex Canonical system type
-The following macros make the system type available to @command{configure}
-scripts.
+If you need to recognize some special environments based on their system
+type, run the following macros to get canonical system names. These
+variables they set are not set before the macro call.
@ovindex build_alias
@ovindex host_alias
@ovindex target_alias
-
-The variables @samp{build_alias}, @samp{host_alias}, and
-@samp{target_alias} are always exactly the arguments of @option{--build},
-@option{--host}, and @option{--target}; in particular, they are left empty
-if the user did not use them, even if the corresponding
-@code{AC_CANONICAL} macro was run. Any configure script may use these
-variables anywhere. These are the variables that should be used when in
-interaction with the user.
-
-If you need to recognize some special environments based on their system
-type, run the following macros to get canonical system names. These
-variables are not set before the macro call.
+These macros can use the arguments of @option{--build}, @option{--host},
+and @option{--target}, which are available to configure scripts in the
+variables @samp{build_alias}, @samp{host_alias}, and @samp{target_alias}
+respectively. These are always the exact arguments given; in
+particular, they are left empty if the user did not use them, even if
+the corresponding @code{AC_CANONICAL} macro was run. These are the
+variables that should be used when in interaction with the user.
If you use these macros, you must distribute @command{config.guess} and
@command{config.sub} along with your source code. @xref{Output}, for
@@ -21843,7 +21872,7 @@ Note that there can be artifacts due to the backward compatibility
code. @xref{Hosts and Cross-Compilation}, for more.
@node Using System Type
-@section Using the System Type
+@section Examples of Using the System Type
In @file{configure.ac} the system type is generally used by one or more
@code{case} statements to select system-specifics. Shell wildcards can
@@ -21883,37 +21912,6 @@ The above examples all show @samp{$host}, since this is where the code
is going to run. Only rarely is it necessary to test @samp{$build}
(which is where the build is being done).
-Whenever you're tempted to use @samp{$host} it's worth considering
-whether some sort of probe would be better. New system types come along
-periodically or previously missing features are added. Well-written
-probes can adapt themselves to such things, but hard-coded lists of
-names can't. Here are some guidelines,
-
-@itemize @bullet
-@item
-Availability of libraries and library functions should always be checked
-by probing.
-@item
-Variant behavior of system calls is best identified with runtime tests
-if possible, but bug workarounds or obscure difficulties might have to
-be driven from @samp{$host}.
-@item
-Assembler code is inevitably highly CPU-specific and is best selected
-according to @samp{$host_cpu}.
-@item
-Assembler variations like underscore prefix on globals or ELF versus
-COFF type directives are however best determined by probing, perhaps
-even examining the compiler output.
-@end itemize
-
-@samp{$target} is for use by a package creating a compiler or similar.
-For ordinary packages it's meaningless and should not be used. It
-indicates what the created compiler should generate code for, if it can
-cross-compile. @samp{$target} generally selects various hard-coded CPU
-and system conventions, since usually the compiler or tools under
-construction themselves determine how the target works.
-
-
@c ===================================================== Site Configuration.
@node Site Configuration
_______________________________________________
Autoconf mailing list
Autoconf@xxxxxxx
https://lists.gnu.org/mailman/listinfo/autoconf
