Re: autoconf: AC_SYS_LARGEFILE documentation misleading

[Eric Blake]

On 01/25/2017 11:30 AM, Thorsten Glaser wrote:
> On Wed, 25 Jan 2017, Eric Blake wrote:
> 
>> Please propose a patch to the documentation, rather than just telling me
>> that it is wrong, so that we have a concrete proposal for a wording
>> improvement that we can discuss.
> Oh okay, I’ll cater for lazy upstreams this time ;-)

It's not necessarily laziness :)

> See the attached git format-patch.
> 

Thanks; that's helpful.  I'm still thinking we may want to iterate on
the wording, in particular:

> +++ b/doc/autoconf.texi
> @@ -8584,8 +8584,8 @@ if the system supports @samp{#!}, @samp{no} if not.
>  Arrange for 64-bit file offsets, known as
>  @uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html,
>  large-file support}.  On some hosts, one must use special compiler
> -options to build programs that can access large files.  Append any such
> -options to the output variable @code{CC}.  Define

You're deleting all mention that the macro may modify CC (true, it
doesn't do it on most platforms, but the code is still there that does
it for Irix); I don't think we want the change to be that drastic.

> +options to build programs that can access large files.  Define,
> +by calling @code{AC_DEFINE_UNQUOTED},
>  @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.

I also think we can try harder to point out the need for config.h to
appear first.  How about the following counter-proposal:

diff --git i/doc/autoconf.texi w/doc/autoconf.texi
index 55f96a3..2901937 100644
--- i/doc/autoconf.texi
+++ w/doc/autoconf.texi
@@ -8584,9 +8584,10 @@ System Services
 Arrange for 64-bit file offsets, known as
 @uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html,
 large-file support}.  On some hosts, one must use special compiler
-options to build programs that can access large files.  Define,
-by calling @code{AC_DEFINE_UNQUOTED},
address@hidden and @code{_LARGE_FILES} if necessary.
+options to build programs that can access large files, and this macro
+modifies the output variable @code{CC} in that case.  This macro will
+additionally define @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if
+necessary, by calling @code{AC_DEFINE_UNQUOTED}.

 Large-file support can be disabled by configuring with the
 @option{--disable-largefile} option.
@@ -8595,7 +8596,9 @@ System Services
 @code{off_t} is wider than @code{long int}, since this is common when
 large-file support is enabled.  For example, it is not correct to print
 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
-(long int) X)}.
+(long int) X)}.  Also, when using this macro in concert with
address@hidden, be sure that @file{config.h} is included
+before any system header.

 The LFS introduced the @code{fseeko} and @code{ftello} functions to
 replace their C counterparts @code{fseek} and @code{ftell} that do not


-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature