Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Joseph Myers]

There are some bug reports from people setting CFLAGS not including a
-O option and then being confused when the build fails.  This patch
addresses this by documenting the proper use of CC and CFLAGS in more
detail - saying what options should go where and specifying the
requirement to compile with optimization.

The previous text incorrectly used @var markup with CC and CFLAGS.
The correct markup for environment variables is @env, but it's also
the case that passing such variables explicitly on the configure
command line is preferred to passing them in the environment, so this
patch changes the documentation to describe passing them on the
command line (and uses @code).

In many cases putting options in the wrong place may in fact work, but
I believe what I've specified is the correct rule for which options to
put where.

2018-02-01  Joseph Myers  <joseph@codesourcery.com>

	[BZ #20980]
	[BZ #21234]
	* manual/install.texi (Configuring and compiling): Describe
	passing CC and CFLAGS on configure command line, not as
	environment variables.  Use @code markup on those variables.
	Specify what options go in CC and what go in CFLAGS.  Note the
	requirement to compile with optimization.
	* INSTALL: Regenerated.

diff --git a/INSTALL b/INSTALL
index 68b9252..912ff63 100644
--- a/INSTALL
+++ b/INSTALL
@@ -36,9 +36,16 @@ normal setting to install as the standard system library is
 '--prefix=/usr' for GNU/Linux systems and '--prefix=' (an empty prefix)
 for GNU/Hurd systems.
 
-   It may also be useful to set the CC and CFLAGS variables in the
-environment when running 'configure'.  CC selects the C compiler that
-will be used, and CFLAGS sets optimization options for the compiler.
+   It may also be useful to pass 'CC=COMPILER' and 'CFLAGS=FLAGS'
+arguments to 'configure'.  'CC' selects the C compiler that will be
+used, and 'CFLAGS' sets optimization options for the compiler.  Any
+compiler options required for all compilations, such as options
+selecting an ABI or a processor for which to generate code, should be
+included in 'CC'.  Options that may be overridden by the GNU C Library
+build system for particular files, such as for optimization and
+debugging, should go in 'CFLAGS'.  The default value of 'CFLAGS' is '-g
+-O2', and the GNU C Library cannot be compiled without optimization, so
+if 'CFLAGS' is specified it must enable optimization.
 
    The following list describes all of the available options for
 'configure':
@@ -210,7 +217,7 @@ will be used, and CFLAGS sets optimization options for the compiler.
      but you want to compile a library for 586es, give
      '--host=i586-pc-linux-gnu' or just '--host=i586-linux' and add the
      appropriate compiler flags ('-mcpu=i586' will do the trick) to
-     CFLAGS.
+     'CC'.
 
      If you specify just '--build', 'configure' will get confused.
 
@@ -304,7 +311,7 @@ makefiles.
 setting a few variables in 'configparms'.  Set 'CC' to the
 cross-compiler for the target you configured the library for; it is
 important to use this same 'CC' value when running 'configure', like
-this: 'CC=TARGET-gcc configure TARGET'.  Set 'BUILD_CC' to the compiler
+this: 'configure TARGET CC=TARGET-gcc'.  Set 'BUILD_CC' to the compiler
 to use for programs run on the build system as part of compiling the
 library.  You may need to set 'AR' to cross-compiling versions of 'ar'
 if the native tools are not configured to work with object files for the
diff --git a/manual/install.texi b/manual/install.texi
index efcd986..5cf8e16 100644
--- a/manual/install.texi
+++ b/manual/install.texi
@@ -59,10 +59,17 @@ but the normal setting to install as the standard system library is
 @samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an
 empty prefix) for @gnuhurdsystems{}.
 
-It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
-the environment when running @code{configure}.  @var{CC} selects the C
-compiler that will be used, and @var{CFLAGS} sets optimization options
-for the compiler.
+It may also be useful to pass @samp{CC=@var{compiler}} and
+@code{CFLAGS=@var{flags}} arguments to @code{configure}.  @code{CC}
+selects the C compiler that will be used, and @code{CFLAGS} sets
+optimization options for the compiler.  Any compiler options required
+for all compilations, such as options selecting an ABI or a processor
+for which to generate code, should be included in @code{CC}.  Options
+that may be overridden by the @glibcadj{} build system for particular
+files, such as for optimization and debugging, should go in
+@code{CFLAGS}.  The default value of @code{CFLAGS} is @samp{-g -O2},
+and @theglibc{} cannot be compiled without optimization, so if
+@code{CFLAGS} is specified it must enable optimization.
 
 The following list describes all of the available options for
  @code{configure}:
@@ -241,7 +248,7 @@ if @code{configure} guesses your machine as @code{i686-pc-linux-gnu} but
 you want to compile a library for 586es, give
 @samp{--host=i586-pc-linux-gnu} or just @samp{--host=i586-linux} and add
 the appropriate compiler flags (@samp{-mcpu=i586} will do the trick) to
-@var{CFLAGS}.
+@code{CC}.
 
 If you specify just @samp{--build}, @code{configure} will get confused.
 
@@ -339,8 +346,8 @@ It is easy to configure @theglibc{} for cross-compilation by
 setting a few variables in @file{configparms}.  Set @code{CC} to the
 cross-compiler for the target you configured the library for; it is
 important to use this same @code{CC} value when running
-@code{configure}, like this: @samp{CC=@var{target}-gcc configure
-@var{target}}.  Set @code{BUILD_CC} to the compiler to use for programs
+@code{configure}, like this: @samp{configure @var{target}
+CC=@var{target}-gcc}.  Set @code{BUILD_CC} to the compiler to use for programs
 run on the build system as part of compiling the library.  You may need to
 set @code{AR} to cross-compiling versions of @code{ar}
 if the native tools are not configured to work with

-- 
Joseph S. Myers
joseph@codesourcery.com

Ping Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Joseph Myers]

Ping.  This patch 
<https://sourceware.org/ml/libc-alpha/2018-02/msg00037.html> is pending 
review.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[DJ Delorie]

Joseph Myers <joseph@codesourcery.com> writes:
> +   It may also be useful to pass 'CC=COMPILER' and 'CFLAGS=FLAGS'
> +arguments to 'configure'.  'CC' selects the C compiler that will be

The first example of how to do this is 270 lines later...

I suspect people familiar with GNU configure might assume you meant

$ CC=... configure

and not

$ configure CC=...

> -this: 'CC=TARGET-gcc configure TARGET'.  Set 'BUILD_CC' to the compiler
> +this: 'configure TARGET CC=TARGET-gcc'.  Set 'BUILD_CC' to the compiler

Unrelated, but "configure" is never right, nor is "./configure"... why
do these examples not include a valid ../src/configure or something?

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Joseph Myers]

On Tue, 6 Feb 2018, DJ Delorie wrote:

> 
> Joseph Myers <joseph@codesourcery.com> writes:
> > +   It may also be useful to pass 'CC=COMPILER' and 'CFLAGS=FLAGS'
> > +arguments to 'configure'.  'CC' selects the C compiler that will be
> 
> The first example of how to do this is 270 lines later...
> 
> I suspect people familiar with GNU configure might assume you meant
> 
> $ CC=... configure

The recommended approach has been "configure CC=..." not "CC=... 
configure" ever since autoconf 2.50 (released 2001).

Passing in the environment does tend to work (modulo possible errors if 
the value is different when config.status gets run) and I don't think it's 
necessary for the glibc-specific instructions to emphasise the existence 
of this deprecation, but I don't think the instructions should use the 
deprecated form either - they should use the preferred modern form.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[DJ Delorie]

Huh.  I've been around far longer than that, and this is the first time
I even knew that was *possible*.

> glibc-specific instructions to emphasise the existence 
> of this deprecation

Not what I meant.  I meant, include an example early, rather than later,
because people who are reading instructions are the people who *don't*
know what the right thing to do is already.

It's the general idea of "the first time you use a term, define it".
With your change, the first time an example of running configure is
needed, is now earlier in the document.

Agreed that there's no need to mention all the non-supported ways of
doing things.

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Joseph Myers]

On Tue, 6 Feb 2018, DJ Delorie wrote:

> It's the general idea of "the first time you use a term, define it".
> With your change, the first time an example of running configure is
> needed, is now earlier in the document.

I don't see anything unclear about "arguments to @code{configure}".  
Especially given that there is, shortly before I refer to such arguments, 
a generic example:

    From your object directory, run the shell script @file{configure} located
    at the top level of the source tree.  In the scenario above, you'd type

    @smallexample
    $ ../glibc-@var{version}/configure @var{args@dots{}}
    @end smallexample

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[DJ Delorie]

Well, I don't feel strongly about it, just trying to mis-read the
documentation as best I can ;-)

Ping^2 Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Joseph Myers]

Ping^2.  This patch 
<https://sourceware.org/ml/libc-alpha/2018-02/msg00037.html> is pending 
review.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Carlos O'Donell]

On 02/01/2018 12:37 PM, Joseph Myers wrote:
> There are some bug reports from people setting CFLAGS not including a
> -O option and then being confused when the build fails.  This patch
> addresses this by documenting the proper use of CC and CFLAGS in more
> detail - saying what options should go where and specifying the
> requirement to compile with optimization.
> 
> The previous text incorrectly used @var markup with CC and CFLAGS.
> The correct markup for environment variables is @env, but it's also
> the case that passing such variables explicitly on the configure
> command line is preferred to passing them in the environment, so this
> patch changes the documentation to describe passing them on the
> command line (and uses @code).
> 
> In many cases putting options in the wrong place may in fact work, but
> I believe what I've specified is the correct rule for which options to
> put where.
> 
> 2018-02-01  Joseph Myers  <joseph@codesourcery.com>
> 
> 	[BZ #20980]
> 	[BZ #21234]
> 	* manual/install.texi (Configuring and compiling): Describe
> 	passing CC and CFLAGS on configure command line, not as
> 	environment variables.  Use @code markup on those variables.
> 	Specify what options go in CC and what go in CFLAGS.  Note the
> 	requirement to compile with optimization.
> 	* INSTALL: Regenerated.

OK with additions suggested below.

Reviewed-by: Carlos O'Donell <carlos@redhat.com>

> --- a/manual/install.texi
> +++ b/manual/install.texi
> @@ -59,10 +59,17 @@ but the normal setting to install as the standard system library is
>  @samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an
>  empty prefix) for @gnuhurdsystems{}.
>  
> -It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
> -the environment when running @code{configure}.  @var{CC} selects the C
> -compiler that will be used, and @var{CFLAGS} sets optimization options
> -for the compiler.
> +It may also be useful to pass @samp{CC=@var{compiler}} and
> +@code{CFLAGS=@var{flags}} arguments to @code{configure}.  @code{CC}
> +selects the C compiler that will be used, and @code{CFLAGS} sets
> +optimization options for the compiler.  Any compiler options required
> +for all compilations, such as options selecting an ABI or a processor
> +for which to generate code, should be included in @code{CC}.  Options
> +that may be overridden by the @glibcadj{} build system for particular
> +files, such as for optimization and debugging, should go in
> +@code{CFLAGS}.  

Suggest adding:

@smallexample
$ ../glibc-@var{version}/configure CC="gcc -m32" CFLAGS="-O3"
@end smallexample

Just to make this perfectly clear.

The default value of @code{CFLAGS} is @samp{-g -O2},
> +and @theglibc{} cannot be compiled without optimization, so if
> +@code{CFLAGS} is specified it must enable optimization.

OK.

>  
>  The following list describes all of the available options for
>   @code{configure}:
> @@ -241,7 +248,7 @@ if @code{configure} guesses your machine as @code{i686-pc-linux-gnu} but
>  you want to compile a library for 586es, give
>  @samp{--host=i586-pc-linux-gnu} or just @samp{--host=i586-linux} and add
>  the appropriate compiler flags (@samp{-mcpu=i586} will do the trick) to
> -@var{CFLAGS}.
> +@code{CC}.

OK.

>  
>  If you specify just @samp{--build}, @code{configure} will get confused.
>  
> @@ -339,8 +346,8 @@ It is easy to configure @theglibc{} for cross-compilation by
>  setting a few variables in @file{configparms}.  Set @code{CC} to the
>  cross-compiler for the target you configured the library for; it is
>  important to use this same @code{CC} value when running
> -@code{configure}, like this: @samp{CC=@var{target}-gcc configure
> -@var{target}}.  Set @code{BUILD_CC} to the compiler to use for programs
> +@code{configure}, like this: @samp{configure @var{target}
> +CC=@var{target}-gcc}.  Set @code{BUILD_CC} to the compiler to use for programs

OK.

>  run on the build system as part of compiling the library.  You may need to
>  set @code{AR} to cross-compiling versions of @code{ar}
>  if the native tools are not configured to work with
> 


-- 
Cheers,
Carlos.

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Rical Jasan]

On 02/01/2018 12:37 PM, Joseph Myers wrote:
...
> diff --git a/manual/install.texi b/manual/install.texi
> index efcd986..5cf8e16 100644
> --- a/manual/install.texi
> +++ b/manual/install.texi
> @@ -59,10 +59,17 @@ but the normal setting to install as the standard system library is
>  @samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an
>  empty prefix) for @gnuhurdsystems{}.
>  
> -It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
> -the environment when running @code{configure}.  @var{CC} selects the C
> -compiler that will be used, and @var{CFLAGS} sets optimization options
> -for the compiler.
> +It may also be useful to pass @samp{CC=@var{compiler}} and

Is this a rogue @samp here, or was that intentional (everywhere else is
@code)?

Otherwise, I think this patch achieves the goal of more explicitly
documenting expected usage of CC and CFLAGS.  (I see it's been
committed, but hopefully an additional ACK doesn't hurt. :)

Rical

Re: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234)

[Joseph Myers]

On Fri, 16 Feb 2018, Rical Jasan wrote:

> On 02/01/2018 12:37 PM, Joseph Myers wrote:
> ...
> > diff --git a/manual/install.texi b/manual/install.texi
> > index efcd986..5cf8e16 100644
> > --- a/manual/install.texi
> > +++ b/manual/install.texi
> > @@ -59,10 +59,17 @@ but the normal setting to install as the standard system library is
> >  @samp{--prefix=/usr} for @gnulinuxsystems{} and @samp{--prefix=} (an
> >  empty prefix) for @gnuhurdsystems{}.
> >  
> > -It may also be useful to set the @var{CC} and @var{CFLAGS} variables in
> > -the environment when running @code{configure}.  @var{CC} selects the C
> > -compiler that will be used, and @var{CFLAGS} sets optimization options
> > -for the compiler.
> > +It may also be useful to pass @samp{CC=@var{compiler}} and
> 
> Is this a rogue @samp here, or was that intentional (everywhere else is
> @code)?

It's intentional, in that it matches (for example) the 
@samp{--prefix=/usr} quoted above.

-- 
Joseph S. Myers
joseph@codesourcery.com