Re: doc system type usage revision

[Ralf Corsepius]

Hi,

some comments interspersed.

Preceding remark: IMO, the basic intention of this section should be to
discourage people from using $host and only to direct them to $host etc.
as "last escape if all else fail".

On Fri, 2003-11-14 at 20:57, Kevin Ryde wrote:
> 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
Why $host? How about $host_cpu? Has $host_cpu been deprecated?

>        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
s/good //

> 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.
+ ... or if they can be avoided.

>   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'.
IMO, this sentence is formulated too strong and also partially
questionable.

1. "best selected" -> "one possibility to select is" or "could be
selected".
"best", as I read it, implies a recommendation, which I would rather not
do in this case (I am not a native English speaker, so my interpretation
might be wrong.).

2. "the CPU part of $host" in autoconf terms is "$host_cpu".

3. Distinguishing between CPU-specific ASM-code on "$host" often is not
sufficient, because 
* ASM-code often is compiler/assembler depended (different ASM-dialects,
different calling conventions etc.).
* compilation flag depended (e.g. endianness and fpu-variant support are
compile-time features, not configuration-time features)
* Using $host assumes static "run-time and configuration-time feature"
to "$host" relationship. This often doesn't apply.

>    * 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.
Similar considerations as above here. I wouldn't want to use the word
"best", here. IMO, "best" would be to avoid such constructs whenever
possible.

>    `$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.

Ralf