This is Info file gcc.info, produced by Makeinfo version 1.68 from the
input file ./gcc.texi.

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gcc: (gcc). The GNU Compiler Collection.
END-INFO-DIR-ENTRY
This file documents the use and the internals of the GNU compiler.

Published by the Free Software Foundation 59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License" and "Funding
for Free Software" are included exactly as in the original, and
provided that the entire resulting derived work is distributed under
the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License" and "Funding for Free Software", and this permission notice,
may be included in translations approved by the Free Software Foundation
instead of in the original English.

File: gcc.info, Node: Insn Lengths, Next: Constant Attributes, Prev: Attr Example, Up: Insn Attributes

Computing the Length of an Insn
-------------------------------

For many machines, multiple types of branch instructions are
provided, each for different length branch displacements. In most
cases, the assembler will choose the correct instruction to use.
However, when the assembler cannot do so, GCC can when a special
attribute, the `length' attribute, is defined. This attribute must be
defined to have numeric values by specifying a null string in its
`define_attr'.

In the case of the `length' attribute, two additional forms of
arithmetic terms are allowed in test expressions:

`(match_dup N)'
This refers to the address of operand N of the current insn, which
must be a `label_ref'.

`(pc)'
This refers to the address of the *current* insn. It might have
been more consistent with other usage to make this the address of
the *next* insn but this would be confusing because the length of
the current insn is to be computed.

For normal insns, the length will be determined by value of the
`length' attribute. In the case of `addr_vec' and `addr_diff_vec' insn
patterns, the length is computed as the number of vectors multiplied by
the size of each vector.

Lengths are measured in addressable storage units (bytes).

The following macros can be used to refine the length computation:

`FIRST_INSN_ADDRESS'
When the `length' insn attribute is used, this macro specifies the
value to be assigned to the address of the first insn in a
function. If not specified, 0 is used.

`ADJUST_INSN_LENGTH (INSN, LENGTH)'
If defined, modifies the length assigned to instruction INSN as a
function of the context in which it is used. LENGTH is an lvalue
that contains the initially computed length of the insn and should
be updated with the correct length of the insn.

This macro will normally not be required. A case in which it is
required is the ROMP. On this machine, the size of an `addr_vec'
insn must be increased by two to compensate for the fact that
alignment may be required.

The routine that returns `get_attr_length' (the value of the
`length' attribute) can be used by the output routine to determine the
form of the branch instruction to be written, as the example below
illustrates.

As an example of the specification of variable-length branches,
consider the IBM 360. If we adopt the convention that a register will
be set to the starting address of a function, we can jump to labels
within 4k of the start using a four-byte instruction. Otherwise, we
need a six-byte sequence to load the address from memory and then
branch to it.

On such a machine, a pattern for a branch instruction might be
specified as follows:

(define_insn "jump"
[(set (pc)
(label_ref (match_operand 0 "" "")))]
""
"*
{
return (get_attr_length (insn) == 4
? \"b %l0\" : \"l r15,=a(%l0); br r15\");
}"
[(set (attr "length") (if_then_else (lt (match_dup 0) (const_int 4096))
(const_int 4)
(const_int 6)))])

File: gcc.info, Node: Constant Attributes, Next: Delay Slots, Prev: Insn Lengths, Up: Insn Attributes

Constant Attributes
-------------------

A special form of `define_attr', where the expression for the
default value is a `const' expression, indicates an attribute that is
constant for a given run of the compiler. Constant attributes may be
used to specify which variety of processor is used. For example,

(define_attr "cpu" "m88100,m88110,m88000"
(const
(cond [(symbol_ref "TARGET_88100") (const_string "m88100")
(symbol_ref "TARGET_88110") (const_string "m88110")]
(const_string "m88000"))))

(define_attr "memory" "fast,slow"
(const
(if_then_else (symbol_ref "TARGET_FAST_MEM")
(const_string "fast")
(const_string "slow"))))

The routine generated for constant attributes has no parameters as it
does not depend on any particular insn. RTL expressions used to define
the value of a constant attribute may use the `symbol_ref' form, but
may not use either the `match_operand' form or `eq_attr' forms
involving insn attributes.

File: gcc.info, Node: Delay Slots, Next: Function Units, Prev: Constant Attributes, Up: Insn Attributes

Delay Slot Scheduling
---------------------

The insn attribute mechanism can be used to specify the requirements
for delay slots, if any, on a target machine. An instruction is said to
require a "delay slot" if some instructions that are physically after
the instruction are executed as if they were located before it.
Classic examples are branch and call instructions, which often execute
the following instruction before the branch or call is performed.

On some machines, conditional branch instructions can optionally
"annul" instructions in the delay slot. This means that the
instruction will not be executed for certain branch outcomes. Both
instructions that annul if the branch is true and instructions that
annul if the branch is false are supported.

Delay slot scheduling differs from instruction scheduling in that
determining whether an instruction needs a delay slot is dependent only
on the type of instruction being generated, not on data flow between the
instructions. See the next section for a discussion of data-dependent
instruction scheduling.

The requirement of an insn needing one or more delay slots is
indicated via the `define_delay' expression. It has the following form:

(define_delay TEST
[DELAY-1 ANNUL-TRUE-1 ANNUL-FALSE-1
DELAY-2 ANNUL-TRUE-2 ANNUL-FALSE-2
...])

TEST is an attribute test that indicates whether this `define_delay'
applies to a particular insn. If so, the number of required delay
slots is determined by the length of the vector specified as the second
argument. An insn placed in delay slot N must satisfy attribute test
DELAY-N. ANNUL-TRUE-N is an attribute test that specifies which insns
may be annulled if the branch is true. Similarly, ANNUL-FALSE-N
specifies which insns in the delay slot may be annulled if the branch
is false. If annulling is not supported for that delay slot, `(nil)'
should be coded.

For example, in the common case where branch and call insns require
a single delay slot, which may contain any insn other than a branch or
call, the following would be placed in the `md' file:

(define_delay (eq_attr "type" "branch,call")
[(eq_attr "type" "!branch,call") (nil) (nil)])

Multiple `define_delay' expressions may be specified. In this case,
each such expression specifies different delay slot requirements and
there must be no insn for which tests in two `define_delay' expressions
are both true.

For example, if we have a machine that requires one delay slot for
branches but two for calls, no delay slot can contain a branch or call
insn, and any valid insn in the delay slot for the branch can be
annulled if the branch is true, we might represent this as follows:

(define_delay (eq_attr "type" "branch")
[(eq_attr "type" "!branch,call")
(eq_attr "type" "!branch,call")
(nil)])

(define_delay (eq_attr "type" "call")
[(eq_attr "type" "!branch,call") (nil) (nil)
(eq_attr "type" "!branch,call") (nil) (nil)])

File: gcc.info, Node: Function Units, Prev: Delay Slots, Up: Insn Attributes

Specifying Function Units
-------------------------

On most RISC machines, there are instructions whose results are not
available for a specific number of cycles. Common cases are
instructions that load data from memory. On many machines, a pipeline
stall will result if the data is referenced too soon after the load
instruction.

In addition, many newer microprocessors have multiple function
units, usually one for integer and one for floating point, and often
will incur pipeline stalls when a result that is needed is not yet
ready.

The descriptions in this section allow the specification of how much
time must elapse between the execution of an instruction and the time
when its result is used. It also allows specification of when the
execution of an instruction will delay execution of similar instructions
due to function unit conflicts.

For the purposes of the specifications in this section, a machine is
divided into "function units", each of which execute a specific class
of instructions in first-in-first-out order. Function units that
accept one instruction each cycle and allow a result to be used in the
succeeding instruction (usually via forwarding) need not be specified.
Classic RISC microprocessors will normally have a single function unit,
which we can call `memory'. The newer "superscalar" processors will
often have function units for floating point operations, usually at
least a floating point adder and multiplier.

Each usage of a function units by a class of insns is specified with
a `define_function_unit' expression, which looks like this:

(define_function_unit NAME MULTIPLICITY SIMULTANEITY
TEST READY-DELAY ISSUE-DELAY
[CONFLICT-LIST])

NAME is a string giving the name of the function unit.

MULTIPLICITY is an integer specifying the number of identical units
in the processor. If more than one unit is specified, they will be
scheduled independently. Only truly independent units should be
counted; a pipelined unit should be specified as a single unit. (The
only common example of a machine that has multiple function units for a
single instruction class that are truly independent and not pipelined
are the two multiply and two increment units of the CDC 6600.)

SIMULTANEITY specifies the maximum number of insns that can be
executing in each instance of the function unit simultaneously or zero
if the unit is pipelined and has no limit.

All `define_function_unit' definitions referring to function unit
NAME must have the same name and values for MULTIPLICITY and
SIMULTANEITY.

TEST is an attribute test that selects the insns we are describing
in this definition. Note that an insn may use more than one function
unit and a function unit may be specified in more than one
`define_function_unit'.

READY-DELAY is an integer that specifies the number of cycles after
which the result of the instruction can be used without introducing any
stalls.

ISSUE-DELAY is an integer that specifies the number of cycles after
the instruction matching the TEST expression begins using this unit
until a subsequent instruction can begin. A cost of N indicates an N-1
cycle delay. A subsequent instruction may also be delayed if an
earlier instruction has a longer READY-DELAY value. This blocking
effect is computed using the SIMULTANEITY, READY-DELAY, ISSUE-DELAY,
and CONFLICT-LIST terms. For a normal non-pipelined function unit,
SIMULTANEITY is one, the unit is taken to block for the READY-DELAY
cycles of the executing insn, and smaller values of ISSUE-DELAY are
ignored.

CONFLICT-LIST is an optional list giving detailed conflict costs for
this unit. If specified, it is a list of condition test expressions to
be applied to insns chosen to execute in NAME following the particular
insn matching TEST that is already executing in NAME. For each insn in
the list, ISSUE-DELAY specifies the conflict cost; for insns not in the
list, the cost is zero. If not specified, CONFLICT-LIST defaults to
all instructions that use the function unit.

Typical uses of this vector are where a floating point function unit
can pipeline either single- or double-precision operations, but not
both, or where a memory unit can pipeline loads, but not stores, etc.

As an example, consider a classic RISC machine where the result of a
load instruction is not available for two cycles (a single "delay"
instruction is required) and where only one load instruction can be
executed simultaneously. This would be specified as:

(define_function_unit "memory" 1 1 (eq_attr "type" "load") 2 0)

For the case of a floating point function unit that can pipeline
either single or double precision, but not both, the following could be
specified:

(define_function_unit
"fp" 1 0 (eq_attr "type" "sp_fp") 4 4 [(eq_attr "type" "dp_fp")])
(define_function_unit
"fp" 1 0 (eq_attr "type" "dp_fp") 4 4 [(eq_attr "type" "sp_fp")])

*Note:* The scheduler attempts to avoid function unit conflicts and
uses all the specifications in the `define_function_unit' expression.
It has recently come to our attention that these specifications may not
allow modeling of some of the newer "superscalar" processors that have
insns using multiple pipelined units. These insns will cause a
potential conflict for the second unit used during their execution and
there is no way of representing that conflict. We welcome any examples
of how function unit conflicts work in such processors and suggestions
for their representation.

File: gcc.info, Node: Target Macros, Next: Config, Prev: Machine Desc, Up: Top

Target Description Macros
*************************

In addition to the file `MACHINE.md', a machine description includes
a C header file conventionally given the name `MACHINE.h'. This header
file defines numerous macros that convey the information about the
target machine that does not fit into the scheme of the `.md' file.
The file `tm.h' should be a link to `MACHINE.h'. The header file
`config.h' includes `tm.h' and most compiler source files include
`config.h'.

* Menu:

* Driver:: Controlling how the driver runs the compilation passes.
* Run-time Target:: Defining `-m' options like `-m68000' and `-m68020'.
* Storage Layout:: Defining sizes and alignments of data.
* Type Layout:: Defining sizes and properties of basic user data types.
* Registers:: Naming and describing the hardware registers.
* Register Classes:: Defining the classes of hardware registers.
* Stack and Calling:: Defining which way the stack grows and by how much.
* Varargs:: Defining the varargs macros.
* Trampolines:: Code set up at run time to enter a nested function.
* Library Calls:: Controlling how library routines are implicitly called.
* Addressing Modes:: Defining addressing modes valid for memory operands.
* Condition Code:: Defining how insns update the condition code.
* Costs:: Defining relative costs of different operations.
* Sections:: Dividing storage into text, data, and other sections.
* PIC:: Macros for position independent code.
* Assembler Format:: Defining how to write insns and pseudo-ops to output.
* Debugging Info:: Defining the format of debugging output.
* Cross-compilation:: Handling floating point for cross-compilers.
* Misc:: Everything else.

File: gcc.info, Node: Driver, Next: Run-time Target, Up: Target Macros

Controlling the Compilation Driver, `gcc'
=========================================

You can control the compilation driver.

`SWITCH_TAKES_ARG (CHAR)'
A C expression which determines whether the option `-CHAR' takes
arguments. The value should be the number of arguments that
option takes-zero, for many options.

By default, this macro is defined as `DEFAULT_SWITCH_TAKES_ARG',
which handles the standard options properly. You need not define
`SWITCH_TAKES_ARG' unless you wish to add additional options which
take arguments. Any redefinition should call
`DEFAULT_SWITCH_TAKES_ARG' and then check for additional options.

`WORD_SWITCH_TAKES_ARG (NAME)'
A C expression which determines whether the option `-NAME' takes
arguments. The value should be the number of arguments that
option takes-zero, for many options. This macro rather than
`SWITCH_TAKES_ARG' is used for multi-character option names.

By default, this macro is defined as
`DEFAULT_WORD_SWITCH_TAKES_ARG', which handles the standard options
properly. You need not define `WORD_SWITCH_TAKES_ARG' unless you
wish to add additional options which take arguments. Any
redefinition should call `DEFAULT_WORD_SWITCH_TAKES_ARG' and then
check for additional options.

`SWITCH_CURTAILS_COMPILATION (CHAR)'
A C expression which determines whether the option `-CHAR' stops
compilation before the generation of an executable. The value is
boolean, non-zero if the option does stop an executable from being
generated, zero otherwise.

By default, this macro is defined as
`DEFAULT_SWITCH_CURTAILS_COMPILATION', which handles the standard
options properly. You need not define
`SWITCH_CURTAILS_COMPILATION' unless you wish to add additional
options which affect the generation of an executable. Any
redefinition should call `DEFAULT_SWITCH_CURTAILS_COMPILATION' and
then check for additional options.

`SWITCHES_NEED_SPACES'
A string-valued C expression which enumerates the options for which
the linker needs a space between the option and its argument.

If this macro is not defined, the default value is `""'.

`CPP_SPEC'
A C string constant that tells the GNU CC driver program options to
pass to CPP. It can also specify how to translate options you
give to GNU CC into options for GNU CC to pass to the CPP.

Do not define this macro if it does not need to do anything.

`NO_BUILTIN_SIZE_TYPE'
If this macro is defined, the preprocessor will not define the
builtin macro `__SIZE_TYPE__'. The macro `__SIZE_TYPE__' must
then be defined by `CPP_SPEC' instead.

This should be defined if `SIZE_TYPE' depends on target dependent
flags which are not accessible to the preprocessor. Otherwise, it
should not be defined.

`NO_BUILTIN_PTRDIFF_TYPE'
If this macro is defined, the preprocessor will not define the
builtin macro `__PTRDIFF_TYPE__'. The macro `__PTRDIFF_TYPE__'
must then be defined by `CPP_SPEC' instead.

This should be defined if `PTRDIFF_TYPE' depends on target
dependent flags which are not accessible to the preprocessor.
Otherwise, it should not be defined.

`SIGNED_CHAR_SPEC'
A C string constant that tells the GNU CC driver program options to
pass to CPP. By default, this macro is defined to pass the option
`-D__CHAR_UNSIGNED__' to CPP if `char' will be treated as
`unsigned char' by `cc1'.

Do not define this macro unless you need to override the default
definition.

`CC1_SPEC'
A C string constant that tells the GNU CC driver program options to
pass to `cc1'. It can also specify how to translate options you
give to GNU CC into options for GNU CC to pass to the `cc1'.

Do not define this macro if it does not need to do anything.

`CC1PLUS_SPEC'
A C string constant that tells the GNU CC driver program options to
pass to `cc1plus'. It can also specify how to translate options
you give to GNU CC into options for GNU CC to pass to the
`cc1plus'.

Do not define this macro if it does not need to do anything.

`ASM_SPEC'
A C string constant that tells the GNU CC driver program options to
pass to the assembler. It can also specify how to translate
options you give to GNU CC into options for GNU CC to pass to the
assembler. See the file `sun3.h' for an example of this.

Do not define this macro if it does not need to do anything.

`ASM_FINAL_SPEC'
A C string constant that tells the GNU CC driver program how to
run any programs which cleanup after the normal assembler.
Normally, this is not needed. See the file `mips.h' for an
example of this.

Do not define this macro if it does not need to do anything.

`LINK_SPEC'
A C string constant that tells the GNU CC driver program options to
pass to the linker. It can also specify how to translate options
you give to GNU CC into options for GNU CC to pass to the linker.

Do not define this macro if it does not need to do anything.

`LIB_SPEC'
Another C string constant used much like `LINK_SPEC'. The
difference between the two is that `LIB_SPEC' is used at the end
of the command given to the linker.

If this macro is not defined, a default is provided that loads the
standard C library from the usual place. See `gcc.c'.

`LIBGCC_SPEC'
Another C string constant that tells the GNU CC driver program how
and when to place a reference to `libgcc.a' into the linker
command line. This constant is placed both before and after the
value of `LIB_SPEC'.

If this macro is not defined, the GNU CC driver provides a default
that passes the string `-lgcc' to the linker unless the `-shared'
option is specified.

`STARTFILE_SPEC'
Another C string constant used much like `LINK_SPEC'. The
difference between the two is that `STARTFILE_SPEC' is used at the
very beginning of the command given to the linker.

If this macro is not defined, a default is provided that loads the
standard C startup file from the usual place. See `gcc.c'.

`ENDFILE_SPEC'
Another C string constant used much like `LINK_SPEC'. The
difference between the two is that `ENDFILE_SPEC' is used at the
very end of the command given to the linker.

Do not define this macro if it does not need to do anything.

`EXTRA_SPECS'
Define this macro to provide additional specifications to put in
the `specs' file that can be used in various specifications like
`CC1_SPEC'.

The definition should be an initializer for an array of structures,
containing a string constant, that defines the specification name,
and a string constant that provides the specification.

Do not define this macro if it does not need to do anything.

`EXTRA_SPECS' is useful when an architecture contains several
related targets, which have various `..._SPECS' which are similar
to each other, and the maintainer would like one central place to
keep these definitions.

For example, the PowerPC System V.4 targets use `EXTRA_SPECS' to
define either `_CALL_SYSV' when the System V calling sequence is
used or `_CALL_AIX' when the older AIX-based calling sequence is
used.

The `config/rs6000/rs6000.h' target file defines:

#define EXTRA_SPECS \
{ "cpp_sysv_default", CPP_SYSV_DEFAULT },

#define CPP_SYS_DEFAULT ""

The `config/rs6000/sysv.h' target file defines:
#undef CPP_SPEC
#define CPP_SPEC \
"%{posix: -D_POSIX_SOURCE } \
%{mcall-sysv: -D_CALL_SYSV } %{mcall-aix: -D_CALL_AIX } \
%{!mcall-sysv: %{!mcall-aix: %(cpp_sysv_default) }} \
%{msoft-float: -D_SOFT_FLOAT} %{mcpu=403: -D_SOFT_FLOAT}"

#undef CPP_SYSV_DEFAULT
#define CPP_SYSV_DEFAULT "-D_CALL_SYSV"

while the `config/rs6000/eabiaix.h' target file defines
`CPP_SYSV_DEFAULT' as:

#undef CPP_SYSV_DEFAULT
#define CPP_SYSV_DEFAULT "-D_CALL_AIX"

`LINK_LIBGCC_SPECIAL'
Define this macro if the driver program should find the library
`libgcc.a' itself and should not pass `-L' options to the linker.
If you do not define this macro, the driver program will pass the
argument `-lgcc' to tell the linker to do the search and will pass
`-L' options to it.

`LINK_LIBGCC_SPECIAL_1'
Define this macro if the driver program should find the library
`libgcc.a'. If you do not define this macro, the driver program
will pass the argument `-lgcc' to tell the linker to do the search.
This macro is similar to `LINK_LIBGCC_SPECIAL', except that it does
not affect `-L' options.

`LINK_COMMAND_SPEC'
A C string constant giving the complete command line need to
execute the linker. When you do this, you will need to update
your port each time a change is made to the link command line
within `gcc.c'. Therefore, define this macro only if you need to
completely redefine the command line for invoking the linker and
there is no other way to accomplish the effect you need.

`MULTILIB_DEFAULTS'
Define this macro as a C expression for the initializer of an
array of string to tell the driver program which options are
defaults for this target and thus do not need to be handled
specially when using `MULTILIB_OPTIONS'.

Do not define this macro if `MULTILIB_OPTIONS' is not defined in
the target makefile fragment or if none of the options listed in
`MULTILIB_OPTIONS' are set by default. *Note Target Fragment::.

`RELATIVE_PREFIX_NOT_LINKDIR'
Define this macro to tell `gcc' that it should only translate a
`-B' prefix into a `-L' linker option if the prefix indicates an
absolute file name.

`STANDARD_EXEC_PREFIX'
Define this macro as a C string constant if you wish to override
the standard choice of `/usr/local/lib/gcc-lib/' as the default
prefix to try when searching for the executable files of the
compiler.

`MD_EXEC_PREFIX'
If defined, this macro is an additional prefix to try after
`STANDARD_EXEC_PREFIX'. `MD_EXEC_PREFIX' is not searched when the
`-b' option is used, or the compiler is built as a cross compiler.
If you define `MD_EXEC_PREFIX', then be sure to add it to the
list of directories used to find the assembler in `configure.in'.

`STANDARD_STARTFILE_PREFIX'
Define this macro as a C string constant if you wish to override
the standard choice of `/usr/local/lib/' as the default prefix to
try when searching for startup files such as `crt0.o'.

`MD_STARTFILE_PREFIX'
If defined, this macro supplies an additional prefix to try after
the standard prefixes. `MD_EXEC_PREFIX' is not searched when the
`-b' option is used, or when the compiler is built as a cross
compiler.

`MD_STARTFILE_PREFIX_1'
If defined, this macro supplies yet another prefix to try after the
standard prefixes. It is not searched when the `-b' option is
used, or when the compiler is built as a cross compiler.

`INIT_ENVIRONMENT'
Define this macro as a C string constant if you wish to set
environment variables for programs called by the driver, such as
the assembler and loader. The driver passes the value of this
macro to `putenv' to initialize the necessary environment
variables.

`LOCAL_INCLUDE_DIR'
Define this macro as a C string constant if you wish to override
the standard choice of `/usr/local/include' as the default prefix
to try when searching for local header files. `LOCAL_INCLUDE_DIR'
comes before `SYSTEM_INCLUDE_DIR' in the search order.

Cross compilers do not use this macro and do not search either
`/usr/local/include' or its replacement.

`SYSTEM_INCLUDE_DIR'
Define this macro as a C string constant if you wish to specify a
system-specific directory to search for header files before the
standard directory. `SYSTEM_INCLUDE_DIR' comes before
`STANDARD_INCLUDE_DIR' in the search order.

Cross compilers do not use this macro and do not search the
directory specified.

`STANDARD_INCLUDE_DIR'
Define this macro as a C string constant if you wish to override
the standard choice of `/usr/include' as the default prefix to try
when searching for header files.

Cross compilers do not use this macro and do not search either
`/usr/include' or its replacement.

`STANDARD_INCLUDE_COMPONENT'
The "component" corresponding to `STANDARD_INCLUDE_DIR'. See
`INCLUDE_DEFAULTS', below, for the description of components. If
you do not define this macro, no component is used.

`INCLUDE_DEFAULTS'
Define this macro if you wish to override the entire default
search path for include files. For a native compiler, the default
search path usually consists of `GCC_INCLUDE_DIR',
`LOCAL_INCLUDE_DIR', `SYSTEM_INCLUDE_DIR',
`GPLUSPLUS_INCLUDE_DIR', and `STANDARD_INCLUDE_DIR'. In addition,
`GPLUSPLUS_INCLUDE_DIR' and `GCC_INCLUDE_DIR' are defined
automatically by `Makefile', and specify private search areas for
GCC. The directory `GPLUSPLUS_INCLUDE_DIR' is used only for C++
programs.

The definition should be an initializer for an array of structures.
Each array element should have four elements: the directory name (a
string constant), the component name, and flag for C++-only
directories, and a flag showing that the includes in the directory
don't need to be wrapped in `extern `C'' when compiling C++. Mark
the end of the array with a null element.

The component name denotes what GNU package the include file is
part of, if any, in all upper-case letters. For example, it might
be `GCC' or `BINUTILS'. If the package is part of the a
vendor-supplied operating system, code the component name as `0'.

For example, here is the definition used for VAX/VMS:

#define INCLUDE_DEFAULTS \
{ \
{ "GNU_GXX_INCLUDE:", "G++", 1, 1}, \
{ "GNU_CC_INCLUDE:", "GCC", 0, 0}, \
{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0}, \
{ ".", 0, 0, 0}, \
{ 0, 0, 0, 0} \
}

Here is the order of prefixes tried for exec files:

1. Any prefixes specified by the user with `-B'.

2. The environment variable `GCC_EXEC_PREFIX', if any.

3. The directories specified by the environment variable
`COMPILER_PATH'.

4. The macro `STANDARD_EXEC_PREFIX'.

5. `/usr/lib/gcc/'.

6. The macro `MD_EXEC_PREFIX', if any.

Here is the order of prefixes tried for startfiles:

1. Any prefixes specified by the user with `-B'.

2. The environment variable `GCC_EXEC_PREFIX', if any.

3. The directories specified by the environment variable
`LIBRARY_PATH' (native only, cross compilers do not use this).

4. The macro `STANDARD_EXEC_PREFIX'.

5. `/usr/lib/gcc/'.

6. The macro `MD_EXEC_PREFIX', if any.

7. The macro `MD_STARTFILE_PREFIX', if any.

8. The macro `STANDARD_STARTFILE_PREFIX'.

9. `/lib/'.

10. `/usr/lib/'.

File: gcc.info, Node: Run-time Target, Next: Storage Layout, Prev: Driver, Up: Target Macros

Run-time Target Specification
=============================

Here are run-time target specifications.

`CPP_PREDEFINES'
Define this to be a string constant containing `-D' options to
define the predefined macros that identify this machine and system.
These macros will be predefined unless the `-ansi' option is
specified.

In addition, a parallel set of macros are predefined, whose names
are made by appending `__' at the beginning and at the end. These
`__' macros are permitted by the ANSI standard, so they are
predefined regardless of whether `-ansi' is specified.

For example, on the Sun, one can use the following value:

"-Dmc68000 -Dsun -Dunix"

The result is to define the macros `__mc68000__', `__sun__' and
`__unix__' unconditionally, and the macros `mc68000', `sun' and
`unix' provided `-ansi' is not specified.

`extern int target_flags;'
This declaration should be present.

`TARGET_...'
This series of macros is to allow compiler command arguments to
enable or disable the use of optional features of the target
machine. For example, one machine description serves both the
68000 and the 68020; a command argument tells the compiler whether
it should use 68020-only instructions or not. This command
argument works by means of a macro `TARGET_68020' that tests a bit
in `target_flags'.

Define a macro `TARGET_FEATURENAME' for each such option. Its
definition should test a bit in `target_flags'; for example:

#define TARGET_68020 (target_flags & 1)

One place where these macros are used is in the
condition-expressions of instruction patterns. Note how
`TARGET_68020' appears frequently in the 68000 machine description
file, `m68k.md'. Another place they are used is in the
definitions of the other macros in the `MACHINE.h' file.

`TARGET_SWITCHES'
This macro defines names of command options to set and clear bits
in `target_flags'. Its definition is an initializer with a
subgrouping for each command option.

Each subgrouping contains a string constant, that defines the
option name, a number, which contains the bits to set in
`target_flags', and a second string which is the description
displayed by -help. If the number is negative then the bits
specified by the number are cleared instead of being set. If the
description string is present but empty, then no help information
will be displayed for that option, but it will not count as an
undocumented option. The actual option name is made by appending
`-m' to the specified name.

One of the subgroupings should have a null string. The number in
this grouping is the default value for `target_flags'. Any target
options act starting with that value.

Here is an example which defines `-m68000' and `-m68020' with
opposite meanings, and picks the latter as the default:

#define TARGET_SWITCHES \
{ { "68020", 1, "" }, \
{ "68000", -1, "Compile for the 68000" }, \
{ "", 1, "" }}

`TARGET_OPTIONS'
This macro is similar to `TARGET_SWITCHES' but defines names of
command options that have values. Its definition is an
initializer with a subgrouping for each command option.

Each subgrouping contains a string constant, that defines the
fixed part of the option name, the address of a variable, and a
description string. The variable, type `char *', is set to the
variable part of the given option if the fixed part matches. The
actual option name is made by appending `-m' to the specified name.

Here is an example which defines `-mshort-data-NUMBER'. If the
given option is `-mshort-data-512', the variable `m88k_short_data'
will be set to the string `"512"'.

extern char *m88k_short_data;
#define TARGET_OPTIONS \
{ { "short-data-", &m88k_short_data, "Specify the size of the short data section" } }

`TARGET_VERSION'
This macro is a C statement to print on `stderr' a string
describing the particular machine description choice. Every
machine description should define `TARGET_VERSION'. For example:

#ifdef MOTOROLA
#define TARGET_VERSION \
fprintf (stderr, " (68k, Motorola syntax)");
#else
#define TARGET_VERSION \
fprintf (stderr, " (68k, MIT syntax)");
#endif

`OVERRIDE_OPTIONS'
Sometimes certain combinations of command options do not make
sense on a particular target machine. You can define a macro
`OVERRIDE_OPTIONS' to take account of this. This macro, if
defined, is executed once just after all the command options have
been parsed.

Don't use this macro to turn on various extra optimizations for
`-O'. That is what `OPTIMIZATION_OPTIONS' is for.

`OPTIMIZATION_OPTIONS (LEVEL, SIZE)'
Some machines may desire to change what optimizations are
performed for various optimization levels. This macro, if
defined, is executed once just after the optimization level is
determined and before the remainder of the command options have
been parsed. Values set in this macro are used as the default
values for the other command line options.

LEVEL is the optimization level specified; 2 if `-O2' is
specified, 1 if `-O' is specified, and 0 if neither is specified.

SIZE is non-zero if `-Os' is specified and zero otherwise.

You should not use this macro to change options that are not
machine-specific. These should uniformly selected by the same
optimization level on all supported machines. Use this macro to
enable machine-specific optimizations.

*Do not examine `write_symbols' in this macro!* The debugging
options are not supposed to alter the generated code.

`CAN_DEBUG_WITHOUT_FP'
Define this macro if debugging can be performed even without a
frame pointer. If this macro is defined, GNU CC will turn on the
`-fomit-frame-pointer' option whenever `-O' is specified.