doc system type usage revision

[Kevin Ryde]

This is a suggestion to tighten up the $host usage section.  The main
aim is to show $host, not $target.

        * doc/autoconf.texi (Using System Type): Revise, showing $host rather
        than $target since the latter is not usual, add guidelines on when to
        use or not use the system type.



Using the System Type
=====================

In `configure.ac' the system type is generally used by one or more
`case' statements to select system-specifics.  Shell wildcards can be
used to match a group of system types.

   For example, an extra assembler code object file giving access to a
CPU cycle counter register.  `$(CYCLE_OBJ)' in the following would be
used in a `Makefile' to add the object to a program or library.

     case $host in
       alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
       i?86-*-*)   CYCLE_OBJ=rdtsc.o ;;
       *)          CYCLE_OBJ= ;;
     esac
     AC_SUBST(CYCLE_OBJ)

   `AC_CONFIG_LINKS' (*note Configuration Links::) is another good way
to select variant source files, for example optimized code for some
CPUs.  The configured CPU type doesn't always indicate exact CPU types,
so some run-time capability checks may be necessary too.

     case $host in
       alpha*-*-*)   AC_CONFIG_LINKS(dither.c:alpha/dither.c) ;;
       powerpc*-*-*) AC_CONFIG_LINKS(dither.c:powerpc/dither.c) ;;
       *-*-*)        AC_CONFIG_LINKS(dither.c:generic/dither.c) ;;
     esac

   Another example is filenames made to vary according to system
conventions.  On Unix-like systems "dot" files are usual but on DOS
systems `ini' files are usual.  It may be worth allowing the user to
override such things though, if it's a matter of personal preference,
or in case a new DOS-like system comes along.

     case $host in
       *-*-msdos* | *-*-go32* | *-*-mingw32* | *-*-cygwin* | *-*-windows*)
         MUMBLE_INIT="mumble.ini"
         ;;
       *)
         MUMBLE_INIT=".mumbleinit"
         ;;
     esac
     AC_SUBST(MUMBLE_INIT)

   The host system type can also be used to find cross-compilation tools
with `AC_CHECK_TOOL' (*note Generic Programs::).

   The above examples all show `$host', since this is where the code is
going to run.  Only rarely is it necessary to test `$build' (which is
where the build is being done).

   Whenever you're tempted to use `$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 won't.  Here are some guidelines,

   * Availability of libraries and library functions should always be
     checked by probing.

   * Variant behaviour of system calls is best identified with runtime
     tests if possible, but bug workarounds or obscure difficulties
     might have to be driven from `$host'.

   * Assembler code is inevitably highly CPU-specific and is best
     selected according to the CPU part of `$host'.

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

   `$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.  `$target' generally selects various hard-coded CPU and
system conventions, since usually the compiler or tools under
construction will themselves determine how the target will work.

autoconf.texi.system-type.diff
Description: Text document