From patchwork Thu Feb 1 20:37:45 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joseph Myers X-Patchwork-Id: 25742 Received: (qmail 121142 invoked by alias); 1 Feb 2018 20:37:53 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 121130 invoked by uid 89); 1 Feb 2018 20:37:52 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-24.5 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, SPF_PASS, URIBL_RED autolearn=ham version=3.3.2 spammy= X-HELO: relay1.mentorg.com Date: Thu, 1 Feb 2018 20:37:45 +0000 From: Joseph Myers To: Subject: Document use of CC and CFLAGS in more detail (bug 20980, bug 21234) Message-ID: User-Agent: Alpine 2.20 (DEB 67 2015-01-07) MIME-Version: 1.0 X-ClientProxiedBy: svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) To svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) 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 [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. Reviewed-by: Carlos O'Donell 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