From patchwork Tue Jan 19 20:52:53 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sandra Loosemore X-Patchwork-Id: 570131 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id C24C2140273 for ; Wed, 20 Jan 2016 07:53:19 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.b=kiZ574PS; dkim-atps=neutral DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; q=dns; s=default; b=yj0lV3CpkdEiccyCZgPh6xdOcAe+Rw+n8sUgCk8nWexauPs7OR GnHJIZJYBUNUEuxAYnRMephapx4fRrAjhPq3fXdXe903De/K2Av2WZcvSx1lRuAd 0FKmYP4TIbJVPUSk4ueMSwuYV3S227Q87nt/SV2PeJtQ5oDPix7zfrNlg= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:to :from:subject:message-id:date:mime-version:content-type; s= default; bh=sI2kXZdvujjV5f+BCqdbdRursCc=; b=kiZ574PSiB7JRb+ZcYcy s5C5tN1rsVjfWr4FqGaQRMOfpmJPGUQKbc1g1DH+R/hanETPUB57e0lJbe9fJEw9 ahzkb/F6Q2qnwlAtRBQFapGeHUEjNHmxCnjgTWQCMqVXoYR+QdiRyPcts15siIQn +5XFxEUsAAddb6rqpIOna/0= Received: (qmail 25439 invoked by alias); 19 Jan 2016 20:53:10 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 25423 invoked by uid 89); 19 Jan 2016 20:53:09 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.4 required=5.0 tests=AWL, BAYES_50, KAM_ASCII_DIVIDERS, RCVD_IN_DNSWL_NONE, SPF_PASS autolearn=no version=3.3.2 spammy=co, regional, wins, compliance X-HELO: relay1.mentorg.com Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 19 Jan 2016 20:53:04 +0000 Received: from svr-orw-fem-04.mgc.mentorg.com ([147.34.97.41]) by relay1.mentorg.com with esmtp id 1aLdGu-0006BF-5y from Sandra_Loosemore@mentor.com for gcc-patches@gcc.gnu.org; Tue, 19 Jan 2016 12:53:00 -0800 Received: from [IPv6:::1] (147.34.91.1) by svr-orw-fem-04.mgc.mentorg.com (147.34.97.41) with Microsoft SMTP Server id 14.3.224.2; Tue, 19 Jan 2016 12:52:59 -0800 To: GCC Patches From: Sandra Loosemore Subject: [doc] GCC manual copy-editing Message-ID: <569EA225.7090007@codesourcery.com> Date: Tue, 19 Jan 2016 13:52:53 -0700 User-Agent: Mozilla/5.0 (X11; Linux i686; rv:38.0) Gecko/20100101 Thunderbird/38.3.0 MIME-Version: 1.0 I've checked in this patch to address some copy-editing issues I noticed when I was working on re-ordering the content of invoke.texi last week. This is pretty boring content-free stuff, for the most part -- markup, hyphenation issues, typos, etc. I had also noticed that the standards.texi documentation for Objective-C had a broken link as well as needing markup fixes, so I made a pass through that file as well. -Sandra Index: gcc/doc/invoke.texi =================================================================== --- gcc/doc/invoke.texi (revision 232581) +++ gcc/doc/invoke.texi (working copy) @@ -2742,9 +2742,9 @@ This warning is enabled by default. @item -Wlto-type-mismatch @opindex Wlto-type-mismatch -@opindex Wno-lto-type-mistmach +@opindex Wno-lto-type-mismatch -During the link-time optimization warn about type mismatches in between +During the link-time optimization warn about type mismatches in global declarations from different compilation units. Requires @option{-flto} to be enabled. Enabled by default. @@ -3261,7 +3261,7 @@ a message which is too long to fit on a @item -fdiagnostics-color[=@var{WHEN}] @itemx -fno-diagnostics-color @opindex fdiagnostics-color -@cindex highlight, color, colour +@cindex highlight, color @vindex GCC_COLORS @r{environment variable} Use color in diagnostics. @var{WHEN} is @samp{never}, @samp{always}, or @samp{auto}. The default depends on how the compiler has been configured, @@ -3346,7 +3346,7 @@ option is known to the diagnostic machin @opindex fno-diagnostics-show-caret @opindex fdiagnostics-show-caret By default, each diagnostic emitted includes the original source line -and a caret '^' indicating the column. This option suppresses this +and a caret @samp{^} indicating the column. This option suppresses this information. The source line is truncated to @var{n} characters, if the @option{-fmessage-length=n} option is given. When the output is done to the terminal, the width is limited to the width given by the @@ -5049,7 +5049,7 @@ types. @option{-Wconversion-null} is ena @item -Wzero-as-null-pointer-constant @r{(C++ and Objective-C++ only)} @opindex Wzero-as-null-pointer-constant @opindex Wno-zero-as-null-pointer-constant -Warn when a literal '0' is used as null pointer constant. This can +Warn when a literal @samp{0} is used as null pointer constant. This can be useful to facilitate the conversion to @code{nullptr} in C++11. @item -Wsubobject-linkage @r{(C++ and Objective-C++ only)} @@ -5878,19 +5878,19 @@ except when selective scheduling is enab @item -gsplit-dwarf @opindex gsplit-dwarf -Separate as much dwarf debugging information as possible into a -separate output file with the extension .dwo. This option allows +Separate as much DWARF debugging information as possible into a +separate output file with the extension @file{.dwo}. This option allows the build system to avoid linking files with debug information. To -be useful, this option requires a debugger capable of reading .dwo +be useful, this option requires a debugger capable of reading @file{.dwo} files. @item -gpubnames @opindex gpubnames -Generate dwarf .debug_pubnames and .debug_pubtypes sections. +Generate DWARF @code{.debug_pubnames} and @code{.debug_pubtypes} sections. @item -ggnu-pubnames @opindex ggnu-pubnames -Generate .debug_pubnames and .debug_pubtypes sections in a format +Generate @code{.debug_pubnames} and @code{.debug_pubtypes} sections in a format suitable for conversion into a GDB@ index. This option is only useful with a linker that can produce GDB@ index version 7. @@ -5906,18 +5906,17 @@ and on some objects @code{.debug_types} debugging information. @item -grecord-gcc-switches +@item -gno-record-gcc-switches @opindex grecord-gcc-switches +@opindex gno-record-gcc-switches This switch causes the command-line options used to invoke the compiler that may affect code generation to be appended to the DW_AT_producer attribute in DWARF debugging information. The options are concatenated with spaces separating them from each other and from -the compiler version. See also @option{-frecord-gcc-switches} for another -way of storing compiler options into the object file. This is the default. - -@item -gno-record-gcc-switches -@opindex gno-record-gcc-switches -Disallow appending command-line options to the DW_AT_producer attribute -in DWARF debugging information. +the compiler version. +It is enabled by default. +See also @option{-frecord-gcc-switches} for another +way of storing compiler options into the object file. @item -gstrict-dwarf @opindex gstrict-dwarf @@ -7591,7 +7590,7 @@ The default is @samp{simple} at levels @ @opindex freorder-blocks-and-partition In addition to reordering basic blocks in the compiled function, in order to reduce number of taken branches, partitions hot and cold basic blocks -into separate sections of the assembly and .o files, to improve +into separate sections of the assembly and @file{.o} files, to improve paging and cache locality performance. This optimization is automatically turned off in the presence of @@ -7825,6 +7824,9 @@ had been part of the same translation un To use the link-time optimizer, @option{-flto} and optimization options should be specified at compile time and during the final link. +It is recommended that you compile all the files participating in the +same link with the same options and also specify those options at +link time. For example: @smallexample @@ -7855,15 +7857,15 @@ merges them together into a single GIMPL them as usual to produce @file{myprog}. The only important thing to keep in mind is that to enable link-time -optimizations you need to use the GCC driver to perform the link-step. +optimizations you need to use the GCC driver to perform the link step. GCC then automatically performs link-time optimization if any of the objects involved were compiled with the @option{-flto} command-line option. You generally should specify the optimization options to be used for link-time optimization though GCC tries to be clever at guessing an -optimization level to use from the options used at compile-time -if you fail to specify one at link-time. You can always override -the automatic decision to do link-time optimization at link-time +optimization level to use from the options used at compile time +if you fail to specify one at link time. You can always override +the automatic decision to do link-time optimization at link time by passing @option{-fno-lto} to the link command. To make whole program optimization effective, it is necessary to make @@ -7876,14 +7878,14 @@ the linker plugin is not available, @opt used to allow the compiler to make these assumptions, which leads to more aggressive optimization decisions. -When @option{-fuse-linker-plugin} is not enabled then, when a file is +When @option{-fuse-linker-plugin} is not enabled, when a file is compiled with @option{-flto}, the generated object file is larger than a regular object file because it contains GIMPLE bytecodes and the usual final code (see @option{-ffat-lto-objects}. This means that object files with LTO information can be linked as normal object files; if @option{-fno-lto} is passed to the linker, no interprocedural optimizations are applied. Note that when -@option{-fno-fat-lto-objects} is enabled the compile-stage is faster +@option{-fno-fat-lto-objects} is enabled the compile stage is faster but you cannot perform a regular, non-LTO link on them. Additionally, the optimization flags used to compile individual files @@ -7909,22 +7911,21 @@ further processing. There are some code generation flags preserved by GCC when generating bytecodes, as they need to be used during the final link -stage. Generally options specified at link-time override those -specified at compile-time. +stage. Generally options specified at link time override those +specified at compile time. If you do not specify an optimization level option @option{-O} at -link-time then GCC computes one based on the optimization levels -used when compiling the object files. The highest optimization -level wins here. +link time, then GCC uses the highest optimization level +used when compiling the object files. -Currently, the following options and their setting are take from -the first object file that explicitely specified it: +Currently, the following options and their settings are taken from +the first object file that explicitly specifies them: @option{-fPIC}, @option{-fpic}, @option{-fpie}, @option{-fcommon}, @option{-fexceptions}, @option{-fnon-call-exceptions}, @option{-fgnu-tm} and all the @option{-m} target flags. -Certain ABI changing flags are required to match in all compilation-units -and trying to override this at link-time with a conflicting value +Certain ABI-changing flags are required to match in all compilation units, +and trying to override this at link time with a conflicting value is ignored. This includes options such as @option{-freg-struct-return} and @option{-fpcc-struct-return}. @@ -7933,12 +7934,8 @@ Other options such as @option{-ffp-contr are passed through to the link stage and merged conservatively for conflicting translation units. Specifically @option{-fno-strict-overflow}, @option{-fwrapv} and @option{-fno-trapv} take -precedence and for example @option{-ffp-contract=off} takes precedence -over @option{-ffp-contract=fast}. You can override them at linke-time. - -It is recommended that you compile all the files participating in the -same link with the same options and also specify those options at -link time. +precedence; and for example @option{-ffp-contract=off} takes precedence +over @option{-ffp-contract=fast}. You can override them at link time. If LTO encounters objects with C linkage declared with incompatible types in separate translation units to be linked together (undefined @@ -8038,7 +8035,7 @@ the link-time optimization step directly @item -flto-odr-type-merging @opindex flto-odr-type-merging Enable streaming of mangled types names of C++ types and their unification -at linktime. This increases size of LTO object files, but enable +at link time. This increases size of LTO object files, but enables diagnostics about One Definition Rule violations. @item -flto-compression-level=@var{n} @@ -8259,7 +8256,7 @@ it might, and @option{-fno-math-errno} i Allow optimizations for floating-point arithmetic that (a) assume that arguments and results are valid and (b) may violate IEEE or -ANSI standards. When used at link-time, it may include libraries +ANSI standards. When used at link time, it may include libraries or startup files that change the default FPU control word or other similar optimizations. @@ -8922,7 +8919,7 @@ doing loop versioning for alias in the v @item vect-max-peeling-for-alignment The maximum number of loop peels to enhance access alignment -for vectorizer. Value -1 means 'no limit'. +for vectorizer. Value -1 means no limit. @item max-iterations-to-track The maximum number of iterations of a loop the brute-force algorithm @@ -9219,7 +9216,7 @@ redundancies for loads and stores. If t is aborted and the load or store is not considered redundant. The number of queries is algorithmically limited to the number of stores on all paths from the load to the function entry. -The default maxmimum number of queries is 1000. +The default maximum number of queries is 1000. @item ira-max-loops-num IRA uses regional register allocation by default. If a function @@ -9261,7 +9258,7 @@ motion optimization performed on them. parameter is 1000 for @option{-O1} and 10000 for @option{-O2} and above. @item loop-max-datarefs-for-datadeps -Building data dapendencies is expensive for very large loops. This +Building data dependencies is expensive for very large loops. This parameter limits the number of data references in loops that are considered for data dependence analysis. These large loops are no handled by the optimizations using loop data dependencies. @@ -9406,7 +9403,7 @@ The default value is 75. A small positi statements with memory operands as those are even more profitable so sink. @item max-stores-to-sink -The maximum number of conditional stores paires that can be sunk. Set to 0 +The maximum number of conditional store pairs that can be sunk. Set to 0 if either vectorization (@option{-ftree-vectorize}) or if-conversion (@option{-ftree-loop-if-convert}) is disabled. The default is 2. @@ -9674,7 +9671,7 @@ out-of-bounds and use-after-free bugs. See @uref{https://github.com/google/sanitizers/wiki/AddressSanitizer} for more details. The run-time behavior can be influenced using the @env{ASAN_OPTIONS} environment variable. When set to @code{help=1}, -the available options are shown at startup of the instrumended program. See +the available options are shown at startup of the instrumented program. See @url{https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags} for a list of supported options. @@ -9904,7 +9901,7 @@ is usable even in freestanding environme @item -fsanitize-coverage=trace-pc @opindex fsanitize-coverage=trace-pc Enable coverage-guided fuzzing code instrumentation. -Inserts call to __sanitizer_cov_trace_pc into every basic block. +Inserts a call to @code{__sanitizer_cov_trace_pc} into every basic block. @item -fbounds-check @opindex fbounds-check @@ -11765,8 +11762,8 @@ text / bss / data / heap / stack / dso s @item -freport-bug @opindex freport-bug -Collect and dump debug information into temporary file if ICE in C/C++ -compiler occured. +Collect and dump debug information into a temporary file if an +internal compiler error (ICE) occurs. @item -fdump-unnumbered @opindex fdump-unnumbered @@ -12798,7 +12795,7 @@ Do not assume that unaligned memory refe @itemx -mno-omit-leaf-frame-pointer @opindex momit-leaf-frame-pointer @opindex mno-omit-leaf-frame-pointer -Omit or keep the frame pointer in leaf functions. The former behaviour is the +Omit or keep the frame pointer in leaf functions. The former behavior is the default. @item -mtls-dialect=desc @@ -12983,7 +12980,7 @@ That allows code to run on hardware vari @item -mprefer-short-insn-regs @opindex mprefer-short-insn-regs -Preferrentially allocate registers that allow short instruction generation. +Preferentially allocate registers that allow short instruction generation. This can result in increased instruction count, so this may either reduce or increase overall code size. @@ -13275,31 +13272,31 @@ The following instructions are enabled: @item 2 @opindex wlh1 The multiply option is set to wlh1: 32x32 multiplier, fully -pipelined (1 stage). The following instructions are additionaly +pipelined (1 stage). The following instructions are additionally enabled: MPY, MPYU, MPYM, MPYMU, and MPY_S. @item 3 @opindex wlh2 The multiply option is set to wlh2: 32x32 multiplier, fully pipelined -(2 stages). The following instructions are additionaly enabled: MPY, +(2 stages). The following instructions are additionally enabled: MPY, MPYU, MPYM, MPYMU, and MPY_S. @item 4 @opindex wlh3 The multiply option is set to wlh3: Two 16x16 multiplier, blocking, -sequential. The following instructions are additionaly enabled: MPY, +sequential. The following instructions are additionally enabled: MPY, MPYU, MPYM, MPYMU, and MPY_S. @item 5 @opindex wlh4 The multiply option is set to wlh4: One 16x16 multiplier, blocking, -sequential. The following instructions are additionaly enabled: MPY, +sequential. The following instructions are additionally enabled: MPY, MPYU, MPYM, MPYMU, and MPY_S. @item 6 @opindex wlh5 The multiply option is set to wlh5: One 32x4 multiplier, blocking, -sequential. The following instructions are additionaly enabled: MPY, +sequential. The following instructions are additionally enabled: MPY, MPYU, MPYM, MPYMU, and MPY_S. @end table @@ -13521,7 +13518,7 @@ Indicate target register priority for r0 @item -mlra-priority-noncompact @opindex mlra-priority-noncompact -Reduce target regsiter priority for r0..r3 / r12..r15. +Reduce target register priority for r0..r3 / r12..r15. @item -mno-millicode @opindex mno-millicode @@ -14307,7 +14304,7 @@ the compiler and are subject to some lim The compiler never sets @code{EIND}. @item -The compiler uses @code{EIND} implicitely in @code{EICALL}/@code{EIJMP} +The compiler uses @code{EIND} implicitly in @code{EICALL}/@code{EIJMP} instructions or might read @code{EIND} directly in order to emulate an indirect call/jump by means of a @code{RET} instruction. @@ -16476,7 +16473,7 @@ to 64 bits. These are HP-UX specific fl (Dis/En)able data speculative scheduling before reload. This results in generation of @code{ld.a} instructions and the corresponding check instructions (@code{ld.c} / @code{chk.a}). -The default is 'disable'. +The default setting is disabled. @item -msched-ar-data-spec @itemx -mno-sched-ar-data-spec @@ -16485,7 +16482,7 @@ The default is 'disable'. (En/Dis)able data speculative scheduling after reload. This results in generation of @code{ld.a} instructions and the corresponding check instructions (@code{ld.c} / @code{chk.a}). -The default is 'enable'. +The default setting is enabled. @item -mno-sched-control-spec @itemx -msched-control-spec @@ -16495,7 +16492,7 @@ The default is 'enable'. available only during region scheduling (i.e.@: before reload). This results in generation of the @code{ld.s} instructions and the corresponding check instructions @code{chk.s}. -The default is 'disable'. +The default setting is disabled. @item -msched-br-in-data-spec @itemx -mno-sched-br-in-data-spec @@ -16504,7 +16501,7 @@ The default is 'disable'. (En/Dis)able speculative scheduling of the instructions that are dependent on the data speculative loads before reload. This is effective only with @option{-msched-br-data-spec} enabled. -The default is 'enable'. +The default setting is enabled. @item -msched-ar-in-data-spec @itemx -mno-sched-ar-in-data-spec @@ -16513,7 +16510,7 @@ The default is 'enable'. (En/Dis)able speculative scheduling of the instructions that are dependent on the data speculative loads after reload. This is effective only with @option{-msched-ar-data-spec} enabled. -The default is 'enable'. +The default setting is enabled. @item -msched-in-control-spec @itemx -mno-sched-in-control-spec @@ -16522,7 +16519,7 @@ The default is 'enable'. (En/Dis)able speculative scheduling of the instructions that are dependent on the control speculative loads. This is effective only with @option{-msched-control-spec} enabled. -The default is 'enable'. +The default setting is enabled. @item -mno-sched-prefer-non-data-spec-insns @itemx -msched-prefer-non-data-spec-insns @@ -16531,7 +16528,7 @@ The default is 'enable'. If enabled, data-speculative instructions are chosen for schedule only if there are no other choices at the moment. This makes the use of the data speculation much more conservative. -The default is 'disable'. +The default setting is disabled. @item -mno-sched-prefer-non-control-spec-insns @itemx -msched-prefer-non-control-spec-insns @@ -16540,7 +16537,7 @@ The default is 'disable'. If enabled, control-speculative instructions are chosen for schedule only if there are no other choices at the moment. This makes the use of the control speculation much more conservative. -The default is 'disable'. +The default setting is disabled. @item -mno-sched-count-spec-in-critical-path @itemx -msched-count-spec-in-critical-path @@ -16549,7 +16546,7 @@ The default is 'disable'. If enabled, speculative dependencies are considered during computation of the instructions priorities. This makes the use of the speculation a bit more conservative. -The default is 'disable'. +The default setting is disabled. @item -msched-spec-ldc @opindex msched-spec-ldc @@ -18512,7 +18509,7 @@ to undefined behavior. @opindex mrelax-pic-calls Try to turn PIC calls that are normally dispatched via register @code{$25} into direct calls. This is only possible if the linker can -resolve the destination at link-time and if the destination is within +resolve the destination at link time and if the destination is within range for a direct call. @option{-mrelax-pic-calls} is the default if GCC was configured to use @@ -18796,7 +18793,7 @@ This option is also passed on to the ass This option enables or disables warnings about conflicts between the MCU name specified by the @option{-mmcu} option and the ISA set by the @option{-mcpu} option and/or the hardware multiply support set by the -@option{-mhwmult} option. It also toggles warnings about unrecognised +@option{-mhwmult} option. It also toggles warnings about unrecognized MCU names. This option is on by default. @item -mcpu= @@ -18834,7 +18831,7 @@ for the original 16-bit-only multiply su A value of @samp{auto} can also be given. This tells GCC to deduce the hardware multiply support based upon the MCU name provided by the @option{-mmcu} option. If no @option{-mmcu} option is specified or if -the MCU name is not recognised then no hardware multiply support is +the MCU name is not recognized then no hardware multiply support is assumed. @code{auto} is the default setting. Hardware multiplies are normally performed by calling a library @@ -18863,8 +18860,8 @@ do not have one of the @code{lower}, @co @code{upper}, @code{either} or @code{any}. The first three behave like the corresponding attribute. The fourth possible value - @code{any} - is the default. It leaves placement entirely up to the -linker script and how it assigns the standard sections (.text, .data -etc) to the memory regions. +linker script and how it assigns the standard sections +(@code{.text}, @code{.data}, etc) to the memory regions. @item -msilicon-errata= @opindex msilicon-errata @@ -19018,14 +19015,14 @@ compiled with the same @option{-G} setti Generate GP-relative accesses for all data objects in the program. If you use this option, the entire data and BSS segments of your program must fit in 64K of memory and you must use an appropriate -linker script to allocate them within the addressible range of the +linker script to allocate them within the addressable range of the global pointer. @item all Generate GP-relative addresses for function pointers as well as data pointers. If you use this option, the entire text, data, and BSS segments of your program must fit in 64K of memory and you must use an appropriate -linker script to allocate them within the addressible range of the +linker script to allocate them within the addressable range of the global pointer. @end table @@ -19539,11 +19536,11 @@ support to use, unless this is overridde @option{-mmul=none} option on the command line. Thus specifying @option{-mcpu=g13} enables the use of the G13 hardware multiply peripheral and specifying @option{-mcpu=g10} disables the use of -hardware multipications altogether. +hardware multiplications altogether. Note, although the RL78/G14 core is the default target, specifying @option{-mcpu=g14} or @option{-mcpu=rl78} on the command line does -change the behaviour of the toolchain since it also enables G14 +change the behavior of the toolchain since it also enables G14 hardware multiply support. If these options are not specified on the command line then software multiplication routines will be used even though the code targets the RL78 core. This is for backwards @@ -19762,7 +19759,7 @@ the AltiVec instruction set. You may al enhancements. When @option{-maltivec} is used, rather than @option{-maltivec=le} or -@option{-maltivec=be}, the element order for Altivec intrinsics such +@option{-maltivec=be}, the element order for AltiVec intrinsics such as @code{vec_splat}, @code{vec_extract}, and @code{vec_insert} match array element order corresponding to the endianness of the target. That is, element zero identifies the leftmost element in a @@ -19772,23 +19769,23 @@ little-endian platform. @item -maltivec=be @opindex maltivec=be -Generate Altivec instructions using big-endian element order, +Generate AltiVec instructions using big-endian element order, regardless of whether the target is big- or little-endian. This is the default when targeting a big-endian platform. -The element order is used to interpret element numbers in Altivec +The element order is used to interpret element numbers in AltiVec intrinsics such as @code{vec_splat}, @code{vec_extract}, and @code{vec_insert}. By default, these match array element order corresponding to the endianness for the target. @item -maltivec=le @opindex maltivec=le -Generate Altivec instructions using little-endian element order, +Generate AltiVec instructions using little-endian element order, regardless of whether the target is big- or little-endian. This is the default when targeting a little-endian platform. This option is currently ignored when targeting a big-endian platform. -The element order is used to interpret element numbers in Altivec +The element order is used to interpret element numbers in AltiVec intrinsics such as @code{vec_splat}, @code{vec_extract}, and @code{vec_insert}. By default, these match array element order corresponding to the endianness for the target. @@ -21133,7 +21130,7 @@ define vector type variables and argumen available when GNU extensions are enabled. It will not be expanded when requesting strict standard compliance e.g. with @option{-std=c99}. In addition to the GCC low-level builtins @option{-mzvector} enables -a set of builtins added for compatibility with Altivec-style +a set of builtins added for compatibility with AltiVec-style implementations like Power and Cell. In order to make use of these builtins the header file @file{vecintrin.h} needs to be included. @option{-mzvector} is disabled by default. @@ -21487,7 +21484,7 @@ Control the IEEE compliance of floating- handling of cases where the result of a comparison is unordered. By default @option{-mieee} is implicitly enabled. If @option{-ffinite-math-only} is enabled @option{-mno-ieee} is implicitly set, which results in faster -floating-point greater-equal and less-equal comparisons. The implcit settings +floating-point greater-equal and less-equal comparisons. The implicit settings can be overridden by specifying either @option{-mieee} or @option{-mno-ieee}. @item -minline-ic_invalidate @@ -24176,9 +24173,9 @@ privileges, isn't available. @item -fwritable-relocated-rdata @opindex fno-writable-relocated-rdata This option is available for MinGW and Cygwin targets. It specifies -that relocated-data in read-only section is put into .data +that relocated-data in read-only section is put into the @code{.data} section. This is a necessary for older runtimes not supporting -modification of .rdata sections for pseudo-relocation. +modification of @code{.rdata} sections for pseudo-relocation. @item -mpe-aligned-commons @opindex mpe-aligned-commons @@ -24342,7 +24339,7 @@ strings to control their behavior. The be overridden by using the @option{-specs=} command-line switch to specify a spec file. -@dfn{Spec files} are plaintext files that are used to construct spec +@dfn{Spec files} are plain-text files that are used to construct spec strings. They consist of a sequence of directives separated by blank lines. The type of directive is determined by the first non-whitespace character on the line, which can be one of the following: Index: gcc/doc/standards.texi =================================================================== --- gcc/doc/standards.texi (revision 232581) +++ gcc/doc/standards.texi (working copy) @@ -50,9 +50,6 @@ with some exceptions, and possibly with @cindex hosted environment @findex __STDC_HOSTED__ -GCC supports three versions of the C standard, although support for -the most recent version is not yet complete. - @opindex std @opindex ansi @opindex pedantic @@ -62,10 +59,12 @@ published in 1990. This standard was ra (ISO/IEC 9899:1990) later in 1990. There were no technical differences between these publications, although the sections of the ANSI standard were renumbered and became clauses in the ISO standard. -This standard, in both its forms, is commonly known as @dfn{C89}, or -occasionally as @dfn{C90}, from the dates of ratification. The ANSI +The ANSI standard, but not the ISO standard, also came with a Rationale -document. To select this standard in GCC, use one of the options +document. +This standard, in both its forms, is commonly known as @dfn{C89}, or +occasionally as @dfn{C90}, from the dates of ratification. +To select this standard in GCC, use one of the options @option{-ansi}, @option{-std=c90} or @option{-std=iso9899:1990}; to obtain all the diagnostics required by the standard, you should also specify @option{-pedantic} (or @option{-pedantic-errors} if you want them to be @@ -85,35 +84,40 @@ as @dfn{AMD1}; the amended standard is s @option{-pedantic} to receive all required diagnostics). A new edition of the ISO C standard was published in 1999 as ISO/IEC -9899:1999, and is commonly known as @dfn{C99}. GCC has substantially +9899:1999, and is commonly known as @dfn{C99}. (While in +development, drafts of this standard version were referred to as +@dfn{C9X}.) GCC has substantially complete support for this standard version; see @uref{http://gcc.gnu.org/c99status.html} for details. To select this -standard, use @option{-std=c99} or @option{-std=iso9899:1999}. (While in -development, drafts of this standard version were referred to as -@dfn{C9X}.) +standard, use @option{-std=c99} or @option{-std=iso9899:1999}. Errors in the 1999 ISO C standard were corrected in three Technical Corrigenda published in 2001, 2004 and 2007. GCC does not support the uncorrected version. A fourth version of the C standard, known as @dfn{C11}, was published -in 2011 as ISO/IEC 9899:2011. GCC has substantially complete support -for this standard, enabled with @option{-std=c11} or -@option{-std=iso9899:2011}. (While in development, drafts of this +in 2011 as ISO/IEC 9899:2011. (While in development, drafts of this standard version were referred to as @dfn{C1X}.) +GCC has substantially complete support +for this standard, enabled with @option{-std=c11} or +@option{-std=iso9899:2011}. -By default, GCC provides some extensions to the C language that on +By default, GCC provides some extensions to the C language that, on rare occasions conflict with the C standard. @xref{C -Extensions,,Extensions to the C Language Family}. Use of the +Extensions,,Extensions to the C Language Family}. +Some features that are part of the C99 standard +are accepted as extensions in C90 mode, and some features that are part +of the C11 standard are accepted as extensions in C90 and C99 modes. +Use of the @option{-std} options listed above disables these extensions where they conflict with the C standard version selected. You may also select an extended version of the C language explicitly with @option{-std=gnu90} (for C90 with GNU extensions), @option{-std=gnu99} (for C99 with GNU extensions) or @option{-std=gnu11} (for C11 with GNU -extensions). The default, if no C language dialect options are given, -is @option{-std=gnu11}. Some features that are part of the C99 standard -are accepted as extensions in C90 mode, and some features that are part -of the C11 standard are accepted as extensions in C90 and C99 modes. +extensions). + +The default, if no C language dialect options are given, +is @option{-std=gnu11}. The ISO C standard defines (in clause 4) two classes of conforming implementation. A @dfn{conforming hosted implementation} supports the @@ -124,28 +128,30 @@ library facilities: those in @code{}; since C99, also those in @code{} and @code{}; and since C11, also those in @code{} and @code{}. In addition, complex types, added in C99, are not -required for freestanding implementations. The standard also defines -two environments for programs, a @dfn{freestanding environment}, -required of all implementations and which may not have library -facilities beyond those required of freestanding implementations, -where the handling of program startup and termination are -implementation-defined, and a @dfn{hosted environment}, which is not -required, in which all the library facilities are provided and startup -is through a function @code{int main (void)} or @code{int main (int, -char *[])}. An OS kernel would be a freestanding environment; a -program using the facilities of an operating system would normally be -in a hosted implementation. +required for freestanding implementations. + +The standard also defines two environments for programs, a +@dfn{freestanding environment}, required of all implementations and +which may not have library facilities beyond those required of +freestanding implementations, where the handling of program startup +and termination are implementation-defined; and a @dfn{hosted +environment}, which is not required, in which all the library +facilities are provided and startup is through a function @code{int +main (void)} or @code{int main (int, char *[])}. An OS kernel is an example +of a program running in a freestanding environment; +a program using the facilities of an +operating system is an example of a program running in a hosted environment. @opindex ffreestanding GCC aims towards being usable as a conforming freestanding implementation, or as the compiler for a conforming hosted -implementation. By default, it will act as the compiler for a hosted +implementation. By default, it acts as the compiler for a hosted implementation, defining @code{__STDC_HOSTED__} as @code{1} and presuming that when the names of ISO C functions are used, they have the semantics defined in the standard. To make it act as a conforming freestanding implementation for a freestanding environment, use the -option @option{-ffreestanding}; it will then define -@code{__STDC_HOSTED__} to @code{0} and not make assumptions about the +option @option{-ffreestanding}; it then defines +@code{__STDC_HOSTED__} to @code{0} and does not make assumptions about the meanings of function names from the standard library, with exceptions noted below. To build an OS kernel, you may well still need to make your own arrangements for linking and startup. @@ -153,8 +159,9 @@ your own arrangements for linking and st GCC does not provide the library facilities required only of hosted implementations, nor yet all the facilities required by C99 of -freestanding implementations on all platforms; to use the facilities of a hosted -environment, you will need to find them elsewhere (for example, in the +freestanding implementations on all platforms. +To use the facilities of a hosted +environment, you need to find them elsewhere (for example, in the GNU C library). @xref{Standard Libraries,,Standard Libraries}. Most of the compiler support routines used by GCC are present in @@ -162,7 +169,7 @@ Most of the compiler support routines us freestanding environment provide @code{memcpy}, @code{memmove}, @code{memset} and @code{memcmp}. Finally, if @code{__builtin_trap} is used, and the target does -not implement the @code{trap} pattern, then GCC will emit a call +not implement the @code{trap} pattern, then GCC emits a call to @code{abort}. For references to Technical Corrigenda, Rationale documents and @@ -225,7 +232,9 @@ select an extended version of the C++ la @option{-std=gnu++98} (for C++98 with GNU extensions), or @option{-std=gnu++11} (for C++11 with GNU extensions), or @option{-std=gnu++14} (for C++14 with GNU extensions), or -@option{-std=gnu++1z} (for C++1z with GNU extensions). The default, if +@option{-std=gnu++1z} (for C++1z with GNU extensions). + +The default, if no C++ language dialect options are given, is @option{-std=gnu++14}. @section Objective-C and Objective-C++ Languages @@ -251,34 +260,32 @@ works with the Apple/NeXT Objective-C ru There is no formal written standard for Objective-C or Objective-C++@. The authoritative manual on traditional Objective-C (1.0) is -``Object-Oriented Programming and the Objective-C Language'', -available at a number of web sites: +``Object-Oriented Programming and the Objective-C Language'': @itemize @item @uref{http://www.gnustep.org/@/resources/@/documentation/@/ObjectivCBook.pdf} is the original NeXTstep document; @item @uref{http://objc.toodarkpark.net} -is the same document in another format; -@item -@uref{http://developer.apple.com/@/mac/@/library/@/documentation/@/Cocoa/@/Conceptual/@/ObjectiveC/} -has an updated version but make sure you search for ``Object Oriented Programming and the Objective-C Programming Language 1.0'', -not documentation on the newer ``Objective-C 2.0'' language +is the same document in another format. @end itemize The Objective-C exception and synchronization syntax (that is, the -keywords @@try, @@throw, @@catch, @@finally and @@synchronized) is +keywords @code{@@try}, @code{@@throw}, @code{@@catch}, +@code{@@finally} and @code{@@synchronized}) is supported by GCC and is enabled with the option @option{-fobjc-exceptions}. The syntax is briefly documented in this manual and in the Objective-C 2.0 manuals from Apple. The Objective-C 2.0 language extensions and features are automatically -enabled; they include properties (via the @@property, @@synthesize and -@@dynamic keywords), fast enumeration (not available in -Objective-C++), attributes for methods (such as deprecated, noreturn, -sentinel, format), the unused attribute for method arguments, the -@@package keyword for instance variables and the @@optional and -@@required keywords in protocols. You can disable all these +enabled; they include properties (via the @code{@@property}, +@code{@@synthesize} and +@code{@@dynamic keywords}), fast enumeration (not available in +Objective-C++), attributes for methods (such as @code{deprecated}, +@code{noreturn}, @code{sentinel}, @code{format}), +the @code{unused} attribute for method arguments, the +@code{@@package} keyword for instance variables and the @code{@@optional} and +@code{@@required} keywords in protocols. You can disable all these Objective-C 2.0 language extensions with the option @option{-fobjc-std=objc1}, which causes the compiler to recognize the same Objective-C language syntax recognized by GCC 4.0, and to produce @@ -289,7 +296,7 @@ GCC has currently no support for non-fra The authoritative manual on Objective-C 2.0 is available from Apple: @itemize @item -@uref{http://developer.apple.com/@/mac/@/library/@/documentation/@/Cocoa/@/Conceptual/@/ObjectiveC/} +@uref{https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html} @end itemize For more information concerning the history of Objective-C that is