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

[Carlos O'Donell <carlos at redhat dot com>]

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.