Movatterモバイル変換

Previous:Option file format, Up:Option specification files [Contents][Index]

7.2 Option properties ¶

The second field of an option record can specify any of the followingproperties. When an option takes an argument, it is enclosed in parenthesesfollowing the option property name. The parser that handles option filesis quite simplistic, and will be tricked by any nested parentheses withinthe argument text itself; in this case, the entire option argument canbe wrapped in curly braces within the parentheses to demarcate it, e.g.:

Condition({defined (USE_CYGWIN_LIBSTDCXX_WRAPPERS)})

Common

The option is available for all languages and targets.

Target

The option is available for all languages but is target-specific.

Driver

The option is handled by the compiler driver using code not sharedwith the compilers proper (cc1 etc.).

language

The option is available when compiling for the given language.

It is possible to specify several different languages for the sameoption. Eachlanguage must have been declared by an earlierLanguage record. SeeOption file format.

RejectDriver

The option is only handled by the compilers proper (cc1 etc.)and should not be accepted by the driver.

RejectNegative

The option does not have a “no-” form. All options beginning with“f”, “g”, “W” or “m” are assumed to have a “no-” form unlessthis property is used.

Negative(othername)

The option will turn off another optionothername, which isthe option name with the leading “-” removed. This chain action willpropagate through theNegative property of the option to beturned off. The driver will prune options, removing those that areturned off by some later option. This pruning is not done for optionswithJoined orJoinedOrMissing properties, unless theoptions have both theRejectNegative property and theNegativeproperty mentions itself.

As a consequence, if you have a group of mutually-exclusiveoptions, theirNegative properties should form a circular chain.For example, if options-a,-b and-c are mutually exclusive, their respectiveNegativeproperties should be ‘Negative(b)’, ‘Negative(c)’and ‘Negative(a)’.

Joined

Separate

The option takes a mandatory argument.Joined indicatesthat the option and argument can be included in the sameargventry (as with-mflush-func=name, for example).Separate indicates that the option and argument can beseparateargv entries (as with-o). An option isallowed to have both of these properties.

JoinedOrMissing

The option takes an optional argument. If the argument is given,it will be part of the sameargv entry as the option itself.

This property cannot be used alongsideJoined orSeparate.

MissingArgError(message)

For an option markedJoined orSeparate, the messagemessage will be used as an error message if the mandatoryargument is missing; for options withoutMissingArgError, ageneric error message is used.message should contain a single‘%qs’ format, which will be used to format the name of the optionpassed.

Args(n)

For an option markedSeparate, indicate that it takesnarguments. The default is 1.

UInteger

The option’s argument is a non-negative integer consisting of eitherdecimal or hexadecimal digits interpreted asint. Hexadecimalintegers may optionally start with the0x or0X prefix.The option parser validates and converts the argument before passingit to the relevant option handler.UInteger should also be usedwith options like-falign-loops where both-falign-loopsand-falign-loops=n are supported to make sure the savedoptions are given a full integer. Positive values of the argument inexcess ofINT_MAX wrap around zero.

Host_Wide_Int

The option’s argument is a non-negative integer consisting of eitherdecimal or hexadecimal digits interpreted as the widest integer typeon the host. As with anUInteger argument, hexadecimal integersmay optionally start with the0x or0X prefix. The optionparser validates and converts the argument before passing it tothe relevant option handler.Host_Wide_Int should be used withoptions that need to accept very large values. Positive values ofthe argument in excess ofHOST_WIDE_INT_M1U are assignedHOST_WIDE_INT_M1U.

IntegerRange(n,m)

The options’s arguments are integers of typeint. The option’sparser validates that the value of an option integer argument is withinthe closed range [n,m].

ByteSize

A property applicable only toUInteger orHost_Wide_Intarguments. The option’s integer argument is interpreted as if in infiniteprecision using saturation arithmetic in the corresponding type. The argumentmay be followed by a ‘byte-size’ suffix designating a multiple of bytessuch askB andKiB for kilobyte and kibibyte, respectively,MB andMiB for megabyte and mebibyte,GB andGiBfor gigabyte and gigibyte, and so on.ByteSize should be used forwith options that take a very large argument representing a size in bytes,such as-Wlarger-than=.

ToLower

The option’s argument should be converted to lowercase as part ofputting it in canonical form, and before comparing with the stringsindicated by anyEnum property.

NoDriverArg

For an option markedSeparate, the option only takes anargument in the compiler proper, not in the driver. This is forcompatibility with existing options that are used both directly andvia-Wp,; new options should not have this property.

Var(var)

The state of this option should be stored in variablevar(actually a macro forglobal_options.x_var).The way that the state is stored depends on the type of option:

If the option uses theMask orInverseMask properties,var is the integer variable that contains the mask.
If the option is a normal on/off switch,var is an integervariable that is nonzero when the option is enabled. The optionsparser will set the variable to 1 when the positive form of theoption is used and 0 when the “no-” form is used.
If the option takes an argument and has theUInteger property,var is an integer variable that stores the value of the argument.
If the option takes an argument and has theEnum property,var is a variable (type given in theType property of the‘Enum’ record whoseName property has the same argument astheEnum property of this option) that stores the value of theargument.
If the option has theDefer property,var is a pointer toaVEC(cl_deferred_option,heap) that stores the option for laterprocessing. (var is declared with typevoid * and needsto be cast toVEC(cl_deferred_option,heap) before use.)
Otherwise, if the option takes an argument,var is a pointer tothe argument string. The pointer will be null if the argument is optionaland wasn’t given.

The option-processing script will usually zero-initializevar.You can modify this behavior usingInit.

Var(var,set)

The option controls an integer variablevar and is active whenvar equalsset. The option parser will setvar toset when the positive form of the option is used and!setwhen the “no-” form is used.

var is declared in the same way as for the single-argument formdescribed above.

Init(value)

The variable specified by theVar property should be staticallyinitialized tovalue. If more than one option using the samevariable specifiesInit, all must specify the same initializer.

WarnRemoved

The option is removed and every usage of such option willresult in a warning. We use it option backward compatibility.

Mask(name)

The option is associated with a bit in thetarget_flagsvariable (seeRun-time Target Specification) and is active when that bit is set.You may also specifyVar to select a variable other thantarget_flags.

The options-processing script will automatically allocate a unique bitfor the option. If the option is attached to ‘target_flags’ orVarwhich is defined byTargetVariable, the script will set the macroMASK_name to the appropriate bitmask. It will also declare aTARGET_name,TARGET_name_P andTARGET_name_OPTS_P:TARGET_name macros that has thevalue 1 when the option is active and 0 otherwise,TARGET_name_P issimilar toTARGET_name but take an argument as ‘target_flags’orTargetVariable, andTARGET_name_OPTS_P also similar toTARGET_name but take an argument asgcc_options.If you useVar to attach the option to a different variable which is notdefined byTargetVariable, the bitmask macro with be calledOPTION_MASK_name.

InverseMask(othername)

InverseMask(othername,thisname)

The option is the inverse of another option that has theMask(othername) property. Ifthisname is given,the options-processing script will declareTARGET_thisname,TARGET_name_P andTARGET_name_OPTS_P macros:TARGET_thisname is 1 when the option is active and 0 otherwise,TARGET_name_P is similar toTARGET_name but takes anargument as ‘target_flags’, andTARGET_name_OPTS_P is alsosimilar toTARGET_name but takes an argument asgcc_options.

Enum(name)

The option’s argument is a string from the set of strings associatedwith the corresponding ‘Enum’ record. The string is checked andconverted to the integer specified in the corresponding‘EnumValue’ record before being passed to option handlers.

EnumSet

Must be used together with theEnum(name) property.Corresponding ‘Enum’ record must useSet properties.The option’s argument is either a string from the set like forEnum(name), but with a slightly different behavior thatthe wholeVar isn’t overwritten, but only the bits in all theenumeration values with the same set bitwise ored together.Or option’s argument can be a comma separated list of strings whereeach string is from a differentSet(number).

EnumBitSet

Must be used together with theEnum(name) property.Similar to ‘EnumSet’, but corresponding ‘Enum’ record mustnot useSet properties, eachEnumValue should haveValue that is a power of 2, each value is treated as its ownset and its value as the set’s mask, so there are no mutuallyexclusive arguments.

Defer

The option should be stored in a vector, specified withVar,for later processing.

Alias(opt)

Alias(opt,arg)

Alias(opt,posarg,negarg)

The option is an alias for-opt (or the negative formof that option, depending onNegativeAlias). In the first form,any argument passed to the alias is considered to be passed to-opt, and-opt is considered to benegated if the alias is used in negated form. In the second form, thealias may not be negated or have an argument, andposarg isconsidered to be passed as an argument to-opt. In thethird form, the alias may not have an argument, if the alias is usedin the positive form thenposarg is considered to be passed to-opt, and if the alias is used in the negative formthennegarg is considered to be passed to-opt.

Aliases should not specifyVar orMask orUInteger. Aliases should normally specify the same languagesas the target of the alias; the flags on the target will be used todetermine any diagnostic for use of an option for the wrong language,while those on the alias will be used to identify what command-linetext is the option and what text is any argument to that option.

When anAlias definition is used for an option, driver specs donot need to handle it and no ‘OPT_’ enumeration value is definedfor it; only the canonical form of the option will be seen in thoseplaces.

NegativeAlias

For an option marked withAlias(opt), the option isconsidered to be an alias for the positive form of-optif negated and for the negative form of-opt if notnegated.NegativeAlias may not be used with the forms ofAlias taking more than one argument.

Ignore

This option is ignored apart from printing any warning specified usingWarn. The option will not be seen by specs and no ‘OPT_’enumeration value is defined for it.

SeparateAlias

For an option marked withJoined,Separate andAlias, the option only acts as an alias when passed a separateargument; with a joined argument it acts as a normal option, with an‘OPT_’ enumeration value. This is for compatibility with theJava-d option and should not be used for new options.

Warn(message)

If this option is used, output the warningmessage.message is a format string, either taking a single operand witha ‘%qs’ format which is the option name, or not taking anyoperands, which is passed to the ‘warning’ function. If an aliasis markedWarn, the target of the alias must not also be markedWarn.

Warning

This is a warning option and should be shown as such in--help output. This flag does not currently affect anythingother than--help.

Optimization

This is an optimization option. It should be shown as such in--help output, and any associated variable named usingVar should be saved and restored when the optimization level ischanged withoptimize attributes.

PerFunction

This is an option that can be overridden on a per-function basis.Optimization impliesPerFunction, but options that do notaffect executable code generation may use this flag instead, so that theoption is not taken into account in ways that might affect executablecode generation.

Param

This is an option that is a parameter.

NoOffload

This option will not be passed through from the host compiler to any offloadtarget compilers via the LTO mechanism. It is intended for use withoptimization tuning parameters where settings appropriate for the host systemare likely to harm the performance of the offload device.

Undocumented

The option is deliberately missing documentation and should notbe included in the--help output.

Condition(cond)

The option should only be accepted if preprocessor conditioncond is true. Note that any C declarations associated with theoption will be present even ifcond is false;cond simplycontrols whether the option is accepted and whether it is printed inthe--help output.

Save

Build thecl_target_option structure to hold a copy of theoption, add the functionscl_target_option_save andcl_target_option_restore to save and restore the options.

SetByCombined

The option may also be set by a combined option such as-ffast-math. This causes thegcc_options struct tohave a fieldfrontend_set_name, wherenameis the name of the field holding the value of this option (without theleadingx_). This gives the front end a way to indicate thatthe value has been set explicitly and should not be changed by thecombined option. For example, some front ends use this to prevent-ffast-math and-fno-fast-math from changing thevalue of-fmath-errno for languages that do not useerrno.

EnabledBy(opt)

EnabledBy(opt ||opt2)

EnabledBy(opt &&opt2)

If not explicitly set, the option is set to the value of-opt; multiple options can be given, separated by||. The third form using&& specifies that the option isonly set if bothopt andopt2 are set. The optionsoptandopt2 must have theCommon property; otherwise, useLangEnabledBy.

LangEnabledBy(language,opt)

LangEnabledBy(language,opt,posarg,negarg)

When compiling for the given language, the option is set to the valueof-opt, if not explicitly set.opt can be also a listof|| separated options. In the second form, ifopt is used in the positive form thenposarg is consideredto be passed to the option, and ifopt is used in the negativeform thennegarg is considered to be passed to the option. Itis possible to specify several different languages. Eachlanguage must have been declared by an earlierLanguagerecord. SeeOption file format.

NoDWARFRecord

The option is omitted from the producer string written by-grecord-gcc-switches.

PchIgnore

Even if this is a target option, this option will not be recorded / comparedto determine if a precompiled header file matches.

CPP(var)

The state of this option should be kept in sync with the preprocessoroptionvar. If this property is set, then propertiesVarandInit must be set as well.

CppReason(CPP_W_Enum)

This warning option corresponds tocpplib.h warning reason codeCPP_W_Enum. This should only be used for warning options of theC-family front-ends.

UrlSuffix(url_suffix)

Adjacent to each human-written.opt file in the source tree isa corresponding file with a.opt.urls extension. These filescontainUrlSuffix directives giving the ending part of the URLfor the documentation of the option, such as:

Wabi-tagUrlSuffix(gcc/C_002b_002b-Dialect-Options.html#index-Wabi-tag)

These URL suffixes are relative toDOCUMENTATION_ROOT_URL.

There files are generated from the.opt files and the generatedHTML documentation byregenerate-opt-urls.py, and should beregenerated when adding new options, via manually invokingmake regenerate-opt-urls.

LangUrlSuffix_lang(url_suffix)

In addition toUrlSuffix directives,regenerate-opt-urls.pycan generate language-specific URLs, such as:

LangUrlSuffix_D(gdc/Code-Generation.html#index-MMD)