This is
/es/build/frv-050408/1/frv550-uclinux/X-tools-build/gcc/doc/gccint.info,
produced by makeinfo version 4.0 from
/es/build/frv-050408/1/frv550-uclinux/sources/tools-src/gcc/doc/gccint.texi.

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below).  A copy of the license is
included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gccint: (gccint).            Internals of the GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the internals of the GNU compilers.

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

File: gccint.info,  Node: Filesystem,  Next: Host Misc,  Prev: Host Common,  Up: Host Config

Host Filesystem
===============

   GCC needs to know a number of things about the semantics of the host
machine's filesystem.  Filesystems with Unix and MS-DOS semantics are
automatically detected.  For other systems, you can define the
following macros in `xm-MACHINE.h'.

`HAVE_DOS_BASED_FILE_SYSTEM'
     This macro is automatically defined by `system.h' if the host file
     system obeys the semantics defined by MS-DOS instead of Unix.  DOS
     file systems are case insensitive, file specifications may begin
     with a drive letter, and both forward slash and backslash (`/' and
     `\') are directory separators.

`DIR_SEPARATOR'
`DIR_SEPARATOR_2'
     If defined, these macros expand to character constants specifying
     separators for directory names within a file specification.
     `system.h' will automatically give them appropriate values on Unix
     and MS-DOS file systems.  If your file system is neither of these,
     define one or both appropriately in `xm-MACHINE.h'.

     However, operating systems like VMS, where constructing a pathname
     is more complicated than just stringing together directory names
     separated by a special character, should not define either of these
     macros.

`PATH_SEPARATOR'
     If defined, this macro should expand to a character constant
     specifying the separator for elements of search paths.  The default
     value is a colon (`:').  DOS-based systems usually, but not
     always, use semicolon (`;').

`VMS'
     Define this macro if the host system is VMS.

`HOST_OBJECT_SUFFIX'
     Define this macro to be a C string representing the suffix for
     object files on your host machine.  If you do not define this
     macro, GCC will use `.o' as the suffix for object files.

`HOST_EXECUTABLE_SUFFIX'
     Define this macro to be a C string representing the suffix for
     executable files on your host machine.  If you do not define this
     macro, GCC will use the null string as the suffix for executable
     files.

`HOST_BIT_BUCKET'
     A pathname defined by the host operating system, which can be
     opened as a file and written to, but all the information written
     is discarded.  This is commonly known as a "bit bucket" or "null
     device".  If you do not define this macro, GCC will use
     `/dev/null' as the bit bucket.  If the host does not support a bit
     bucket, define this macro to an invalid filename.

`UPDATE_PATH_HOST_CANONICALIZE (PATH)'
     If defined, a C statement (sans semicolon) that performs
     host-dependent canonicalization when a path used in a compilation
     driver or preprocessor is canonicalized.  PATH is a malloc-ed path
     to be canonicalized.  If the C statement does canonicalize PATH
     into a different buffer, the old path should be freed and the new
     buffer should have been allocated with malloc.

`DUMPFILE_FORMAT'
     Define this macro to be a C string representing the format to use
     for constructing the index part of debugging dump file names.  The
     resultant string must fit in fifteen bytes.  The full filename
     will be the concatenation of: the prefix of the assembler file
     name, the string resulting from applying this format to an index
     number, and a string unique to each dump file kind, e.g. `rtl'.

     If you do not define this macro, GCC will use `.%02d.'.  You should
     define this macro if using the default will create an invalid file
     name.


File: gccint.info,  Node: Host Misc,  Prev: Filesystem,  Up: Host Config

Host Misc
=========

`FATAL_EXIT_CODE'
     A C expression for the status code to be returned when the compiler
     exits after serious errors.  The default is the system-provided
     macro `EXIT_FAILURE', or `1' if the system doesn't define that
     macro.  Define this macro only if these defaults are incorrect.

`SUCCESS_EXIT_CODE'
     A C expression for the status code to be returned when the compiler
     exits without serious errors.  (Warnings are not serious errors.)
     The default is the system-provided macro `EXIT_SUCCESS', or `0' if
     the system doesn't define that macro.  Define this macro only if
     these defaults are incorrect.

`USE_C_ALLOCA'
     Define this macro if GCC should use the C implementation of
     `alloca' provided by `libiberty.a'.  This only affects how some
     parts of the compiler itself allocate memory.  It does not change
     code generation.

     When GCC is built with a compiler other than itself, the C `alloca'
     is always used.  This is because most other implementations have
     serious bugs.  You should define this macro only on a system where
     no stack-based `alloca' can possibly work.  For instance, if a
     system has a small limit on the size of the stack, GCC's builtin
     `alloca' will not work reliably.

`COLLECT2_HOST_INITIALIZATION'
     If defined, a C statement (sans semicolon) that performs
     host-dependent initialization when `collect2' is being initialized.

`GCC_DRIVER_HOST_INITIALIZATION'
     If defined, a C statement (sans semicolon) that performs
     host-dependent initialization when a compilation driver is being
     initialized.

`SMALL_ARG_MAX'
     Define this macro if the host system has a small limit on the total
     size of an argument vector.  This causes the driver to take more
     care not to pass unnecessary arguments to subprocesses.

   In addition, if `configure' generates an incorrect definition of any
of the macros in `auto-host.h', you can override that definition in a
host configuration header.  If you need to do this, first see if it is
possible to fix `configure'.


File: gccint.info,  Node: Fragments,  Next: Collect2,  Prev: Host Config,  Up: Top

Makefile Fragments
******************

   When you configure GCC using the `configure' script, it will
construct the file `Makefile' from the template file `Makefile.in'.
When it does this, it can incorporate makefile fragments from the
`config' directory.  These are used to set Makefile parameters that are
not amenable to being calculated by autoconf.  The list of fragments to
incorporate is set by `config.gcc' (and occasionally `config.build' and
`config.host'); *Note System Config::.

   Fragments are named either `t-TARGET' or `x-HOST', depending on
whether they are relevant to configuring GCC to produce code for a
particular target, or to configuring GCC to run on a particular host.
Here TARGET and HOST are mnemonics which usually have some relationship
to the canonical system name, but no formal connection.

   If these files do not exist, it means nothing needs to be added for a
given target or host.  Most targets need a few `t-TARGET' fragments,
but needing `x-HOST' fragments is rare.

* Menu:

* Target Fragment:: Writing `t-TARGET' files.
* Host Fragment::   Writing `x-HOST' files.


File: gccint.info,  Node: Target Fragment,  Next: Host Fragment,  Up: Fragments

Target Makefile Fragments
=========================

   Target makefile fragments can set these Makefile variables.

`LIBGCC2_CFLAGS'
     Compiler flags to use when compiling `libgcc2.c'.

`LIB2FUNCS_EXTRA'
     A list of source file names to be compiled or assembled and
     inserted into `libgcc.a'.

`Floating Point Emulation'
     To have GCC include software floating point libraries in `libgcc.a'
     define `FPBIT' and `DPBIT' along with a few rules as follows:
          # We want fine grained libraries, so use the new code
          # to build the floating point emulation libraries.
          FPBIT = fp-bit.c
          DPBIT = dp-bit.c
          
          
          fp-bit.c: $(srcdir)/config/fp-bit.c
                  echo '#define FLOAT' > fp-bit.c
                  cat $(srcdir)/config/fp-bit.c >> fp-bit.c
          
          dp-bit.c: $(srcdir)/config/fp-bit.c
                  cat $(srcdir)/config/fp-bit.c > dp-bit.c

     You may need to provide additional #defines at the beginning of
     `fp-bit.c' and `dp-bit.c' to control target endianness and other
     options.

`CRTSTUFF_T_CFLAGS'
     Special flags used when compiling `crtstuff.c'.  *Note
     Initialization::.

`CRTSTUFF_T_CFLAGS_S'
     Special flags used when compiling `crtstuff.c' for shared linking.
     Used if you use `crtbeginS.o' and `crtendS.o' in `EXTRA-PARTS'.
     *Note Initialization::.

`MULTILIB_OPTIONS'
     For some targets, invoking GCC in different ways produces objects
     that can not be linked together.  For example, for some targets GCC
     produces both big and little endian code.  For these targets, you
     must arrange for multiple versions of `libgcc.a' to be compiled,
     one for each set of incompatible options.  When GCC invokes the
     linker, it arranges to link in the right version of `libgcc.a',
     based on the command line options used.

     The `MULTILIB_OPTIONS' macro lists the set of options for which
     special versions of `libgcc.a' must be built.  Write options that
     are mutually incompatible side by side, separated by a slash.
     Write options that may be used together separated by a space.  The
     build procedure will build all combinations of compatible options.

     For example, if you set `MULTILIB_OPTIONS' to `m68000/m68020
     msoft-float', `Makefile' will build special versions of `libgcc.a'
     using the following sets of options:  `-m68000', `-m68020',
     `-msoft-float', `-m68000 -msoft-float', and `-m68020 -msoft-float'.

`MULTILIB_DIRNAMES'
     If `MULTILIB_OPTIONS' is used, this variable specifies the
     directory names that should be used to hold the various libraries.
     Write one element in `MULTILIB_DIRNAMES' for each element in
     `MULTILIB_OPTIONS'.  If `MULTILIB_DIRNAMES' is not used, the
     default value will be `MULTILIB_OPTIONS', with all slashes treated
     as spaces.

     For example, if `MULTILIB_OPTIONS' is set to `m68000/m68020
     msoft-float', then the default value of `MULTILIB_DIRNAMES' is
     `m68000 m68020 msoft-float'.  You may specify a different value if
     you desire a different set of directory names.

`MULTILIB_MATCHES'
     Sometimes the same option may be written in two different ways.
     If an option is listed in `MULTILIB_OPTIONS', GCC needs to know
     about any synonyms.  In that case, set `MULTILIB_MATCHES' to a
     list of items of the form `option=option' to describe all relevant
     synonyms.  For example, `m68000=mc68000 m68020=mc68020'.

`MULTILIB_EXCEPTIONS'
     Sometimes when there are multiple sets of `MULTILIB_OPTIONS' being
     specified, there are combinations that should not be built.  In
     that case, set `MULTILIB_EXCEPTIONS' to be all of the switch
     exceptions in shell case syntax that should not be built.

     For example the ARM processor cannot execute both hardware floating
     point instructions and the reduced size THUMB instructions at the
     same time, so there is no need to build libraries with both of
     these options enabled.  Therefore `MULTILIB_EXCEPTIONS' is set to:
          *mthumb/*mhard-float*

`MULTILIB_EXTRA_OPTS'
     Sometimes it is desirable that when building multiple versions of
     `libgcc.a' certain options should always be passed on to the
     compiler.  In that case, set `MULTILIB_EXTRA_OPTS' to be the list
     of options to be used for all builds.  If you set this, you should
     probably set `CRTSTUFF_T_CFLAGS' to a dash followed by it.

`SPECS'
     Unfortunately, setting `MULTILIB_EXTRA_OPTS' is not enough, since
     it does not affect the build of target libraries, at least not the
     build of the default multilib.  One possible work-around is to use
     `DRIVER_SELF_SPECS' to bring options from the `specs' file as if
     they had been passed in the compiler driver command line.
     However, you don't want to be adding these options after the
     toolchain is installed, so you can instead tweak the `specs' file
     that will be used during the toolchain build, while you still
     install the original, built-in `specs'.  The trick is to set
     `SPECS' to some other filename (say `specs.install'), that will
     then be created out of the built-in specs, and introduce a
     `Makefile' rule to generate the `specs' file that's going to be
     used at build time out of your `specs.install'.


File: gccint.info,  Node: Host Fragment,  Prev: Target Fragment,  Up: Fragments

Host Makefile Fragments
=======================

   The use of `x-HOST' fragments is discouraged.  You should do so only
if there is no other mechanism to get the behavior desired.  Host
fragments should never forcibly override variables set by the configure
script, as they may have been adjusted by the user.

   Variables provided for host fragments to set include:

`X_CFLAGS'
`X_CPPFLAGS'
     These are extra flags to pass to the C compiler and preprocessor,
     respectively.  They are used both when building GCC, and when
     compiling things with the just-built GCC.

`XCFLAGS'
     These are extra flags to use when building the compiler.  They are
     not used when compiling `libgcc.a'.  However, they _are_ used when
     recompiling the compiler with itself in later stages of a
     bootstrap.

`BOOT_LDFLAGS'
     Flags to be passed to the linker when recompiling the compiler with
     itself in later stages of a bootstrap.  You might need to use this
     if, for instance, one of the front ends needs more text space than
     the linker provides by default.

`EXTRA_PROGRAMS'
     A list of additional programs required to use the compiler on this
     host, which should be compiled with GCC and installed alongside
     the front ends.  If you set this variable, you must also provide
     rules to build the extra programs.


File: gccint.info,  Node: Collect2,  Next: Header Dirs,  Prev: Fragments,  Up: Top

`collect2'
**********

   GCC uses a utility called `collect2' on nearly all systems to arrange
to call various initialization functions at start time.

   The program `collect2' works by linking the program once and looking
through the linker output file for symbols with particular names
indicating they are constructor functions.  If it finds any, it creates
a new temporary `.c' file containing a table of them, compiles it, and
links the program a second time including that file.

   The actual calls to the constructors are carried out by a subroutine
called `__main', which is called (automatically) at the beginning of
the body of `main' (provided `main' was compiled with GNU CC).  Calling
`__main' is necessary, even when compiling C code, to allow linking C
and C++ object code together.  (If you use `-nostdlib', you get an
unresolved reference to `__main', since it's defined in the standard
GCC library.  Include `-lgcc' at the end of your compiler command line
to resolve this reference.)

   The program `collect2' is installed as `ld' in the directory where
the passes of the compiler are installed.  When `collect2' needs to
find the _real_ `ld', it tries the following file names:

   * `real-ld' in the directories listed in the compiler's search
     directories.

   * `real-ld' in the directories listed in the environment variable
     `PATH'.

   * The file specified in the `REAL_LD_FILE_NAME' configuration macro,
     if specified.

   * `ld' in the compiler's search directories, except that `collect2'
     will not execute itself recursively.

   * `ld' in `PATH'.

   "The compiler's search directories" means all the directories where
`gcc' searches for passes of the compiler.  This includes directories
that you specify with `-B'.

   Cross-compilers search a little differently:

   * `real-ld' in the compiler's search directories.

   * `TARGET-real-ld' in `PATH'.

   * The file specified in the `REAL_LD_FILE_NAME' configuration macro,
     if specified.

   * `ld' in the compiler's search directories.

   * `TARGET-ld' in `PATH'.

   `collect2' explicitly avoids running `ld' using the file name under
which `collect2' itself was invoked.  In fact, it remembers up a list
of such names--in case one copy of `collect2' finds another copy (or
version) of `collect2' installed as `ld' in a second place in the
search path.

   `collect2' searches for the utilities `nm' and `strip' using the
same algorithm as above for `ld'.


File: gccint.info,  Node: Header Dirs,  Next: Type Information,  Prev: Collect2,  Up: Top

Standard Header File Directories
********************************

   `GCC_INCLUDE_DIR' means the same thing for native and cross.  It is
where GCC stores its private include files, and also where GCC stores
the fixed include files.  A cross compiled GCC runs `fixincludes' on
the header files in `$(tooldir)/include'.  (If the cross compilation
header files need to be fixed, they must be installed before GCC is
built.  If the cross compilation header files are already suitable for
GCC, nothing special need be done).

   `GPLUSPLUS_INCLUDE_DIR' means the same thing for native and cross.
It is where `g++' looks first for header files.  The C++ library
installs only target independent header files in that directory.

   `LOCAL_INCLUDE_DIR' is used only by native compilers.  GCC doesn't
install anything there.  It is normally `/usr/local/include'.  This is
where local additions to a packaged system should place header files.

   `CROSS_INCLUDE_DIR' is used only by cross compilers.  GCC doesn't
install anything there.

   `TOOL_INCLUDE_DIR' is used for both native and cross compilers.  It
is the place for other packages to install header files that GCC will
use.  For a cross-compiler, this is the equivalent of `/usr/include'.
When you build a cross-compiler, `fixincludes' processes any header
files in this directory.


File: gccint.info,  Node: Type Information,  Next: Funding,  Prev: Header Dirs,  Up: Top

Memory Management and Type Information
**************************************

   GCC uses some fairly sophisticated memory management techniques,
which involve determining information about GCC's data structures from
GCC's source code and using this information to perform garbage
collection and implement precompiled headers.

   A full C parser would be too overcomplicated for this task, so a
limited subset of C is interpreted and special markers are used to
determine what parts of the source to look at.  The parser can also
detect simple typedefs of the form `typedef struct ID1 *ID2;' and
`typedef int ID3;', and these don't need to be specially marked.

   The two forms that do need to be marked are:

struct ID1 GTY(([options]))
{
  [fields]
};

typedef struct ID2 GTY(([options]))
{
  [fields]
} ID3;

* Menu:

* GTY Options::		What goes inside a `GTY(())'.
* GGC Roots::		Making global variables GGC roots.
* Files::		How the generated files work.


File: gccint.info,  Node: GTY Options,  Next: GGC Roots,  Up: Type Information

The Inside of a `GTY(())'
=========================

   Sometimes the C code is not enough to fully describe the type
structure.  Extra information can be provided by using more `GTY'
markers.  These markers can be placed:
   * In a structure definition, before the open brace;

   * In a global variable declaration, after the keyword `static' or
     `extern'; and

   * In a structure field definition, before the name of the field.

   The format of a marker is

GTY (([name] ([param]), [name] ([param]) ...))
 The parameter is either a string or a type name.

   When the parameter is a string, often it is a fragment of C code.
Three special escapes may be available:

`%h'
     This expands to an expression that evaluates to the current
     structure.

`%1'
     This expands to an expression that evaluates to the structure that
     immediately contains the current structure.

`%0'
     This expands to an expression that evaluates to the outermost
     structure that contains the current structure.

`%a'
     This expands to the string of the form `[i1][i2]...' that indexes
     the array item currently being marked.  For instance, if the field
     being marked is `foo', then `%1.foo%a' is the same as `%h'.

   The available options are:

`length'
     There are two places the type machinery will need to be explicitly
     told the length of an array.  The first case is when a structure
     ends in a variable-length array, like this:

     struct rtvec_def GTY(()) {
       int num_elem;		/* number of elements */
       rtx GTY ((length ("%h.num_elem"))) elem[1];
     };
      In this case, the `length' option is used to override the
     specified array length (which should usually be `1').  The
     parameter of the option is a fragment of C code that calculates
     the length.

     The second case is when a structure or a global variable contains a
     pointer to an array, like this:
          tree *
            GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
     In this case, `regno_decl' has been allocated by writing something
     like
            x->regno_decl =
              ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
     and the `length' provides the length of the field.

     This second use of `length' also works on global variables, like:

       static GTY((length ("reg_base_value_size")))
         rtx *reg_base_value;

`skip'
     If `skip' is applied to a field, the type machinery will ignore it.
     This is somewhat dangerous; the only safe use is in a union when
     one field really isn't ever used.

`desc'
`tag'
`default'
     The type machinery needs to be told which field of a `union' is
     currently active.  This is done by giving each field a constant
     `tag' value, and then specifying a discriminator using `desc'.
     The value of the expression given by `desc' is compared against
     each `tag' value, each of which should be different.  If no `tag'
     is matched, the field marked with `default' is used if there is
     one, otherwise no field in the union will be marked.

     In the `desc' option, the "current structure" is the union that it
     discriminates.  Use `%1' to mean the structure containing it.
     (There are no escapes available to the `tag' option, since it's
     supposed to be a constant.)

     For example,
          struct tree_binding GTY(())
          {
            struct tree_common common;
            union tree_binding_u {
              tree GTY ((tag ("0"))) scope;
              struct cp_binding_level * GTY ((tag ("1"))) level;
            } GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
            tree value;
          };

     In this example, the value of BINDING_HAS_LEVEL_P when applied to a
     `struct tree_binding *' is presumed to be 0 or 1.  If 1, the type
     mechanism will treat the field `level' as being present and if 0,
     will treat the field `scope' as being present.

`param_is'
`use_param'
     Sometimes it's convenient to define some data structure to work on
     generic pointers (that is, `PTR') and then use it with a specific
     type.  `param_is' specifies the real type pointed to, and
     `use_param' says where in the generic data structure that type
     should be put.

     For instance, to have a `htab_t' that points to trees, one should
     write

       htab_t GTY ((param_is (union tree_node))) ict;

`paramN_is'
`use_paramN'
     In more complicated cases, the data structure might need to work on
     several different types, which might not necessarily all be
     pointers.  For this, `param1_is' through `param9_is' may be used to
     specify the real type of a field identified by `use_param1' through
     `use_param9'.

`use_params'
     When a structure contains another structure that is parameterized,
     there's no need to do anything special, the inner structure
     inherits the parameters of the outer one.  When a structure
     contains a pointer to a parameterized structure, the type
     machinery won't automatically detect this (it could, it just
     doesn't yet), so it's necessary to tell it that the pointed-to
     structure should use the same parameters as the outer structure.
     This is done by marking the pointer with the `use_params' option.

`deletable'
     `deletable', when applied to a global variable, indicates that when
     garbage collection runs, there's no need to mark anything pointed
     to by this variable, it can just be set to `NULL' instead.  This
     is used to keep a list of free structures around for re-use.

`if_marked'
     Suppose you want some kinds of object to be unique, and so you put
     them in a hash table.  If garbage collection marks the hash table,
     these objects will never be freed, even if the last other
     reference to them goes away.  GGC has special handling to deal
     with this: if you use the `if_marked' option on a global hash
     table, GGC will call the routine whose name is the parameter to
     the option on each hash table entry.  If the routine returns
     nonzero, the hash table entry will be marked as usual.  If the
     routine returns zero, the hash table entry will be deleted.

     The routine `ggc_marked_p' can be used to determine if an element
     has been marked already; in fact, the usual case is to use
     `if_marked ("ggc_marked_p")'.

`maybe_undef'
     When applied to a field, `maybe_undef' indicates that it's OK if
     the structure that this fields points to is never defined, so long
     as this field is always `NULL'.  This is used to avoid requiring
     backends to define certain optional structures.  It doesn't work
     with language frontends.

`chain_next'
`chain_prev'
     It's helpful for the type machinery to know if objects are often
     chained together in long lists; this lets it generate code that
     uses less stack space by iterating along the list instead of
     recursing down it.  `chain_next' is an expression for the next
     item in the list, `chain_prev' is an expression for the previous
     item.  The machinery requires that taking the next item of the
     previous item gives the original item.

`reorder'
     Some data structures depend on the relative ordering of pointers.
     If the type machinery needs to change that ordering, it will call
     the function referenced by the `reorder' option, before changing
     the pointers in the object that's pointed to by the field the
     option applies to.  The function must be of the type `void ()(void
     *, void *, gt_pointer_operator, void *)'.  The second parameter is
     the pointed-to object; the third parameter is a routine that,
     given a pointer, can update it to its new value.  The fourth
     parameter is a cookie to be passed to the third parameter.  The
     first parameter is the structure that contains the object, or the
     object itself if it is a structure.

     No data structure may depend on the absolute value of pointers.
     Even relying on relative orderings and using `reorder' functions
     can be expensive.  It is better to depend on properties of the
     data, like an ID number or the hash of a string instead.

`special'
     The `special' option is used for those bizarre cases that are just
     too hard to deal with otherwise.  Don't use it for new code.


File: gccint.info,  Node: GGC Roots,  Next: Files,  Prev: GTY Options,  Up: Type Information

Marking Roots for the Garbage Collector
=======================================

   In addition to keeping track of types, the type machinery also
locates the global variables that the garbage collector starts at.
There are two syntaxes it accepts to indicate a root:

  1. extern GTY (([options])) [type] ID;

  2. static GTY (([options])) [type] ID;

   These are the only syntaxes that are accepted.  In particular, if you
want to mark a variable that is only declared as

int ID;
 or similar, you should either make it `static' or you should create a
`extern' declaration in a header file somewhere.


File: gccint.info,  Node: Files,  Prev: GGC Roots,  Up: Type Information

Source Files Containing Type Information
========================================

   Whenever you add `GTY' markers to a new source file, there are three
things you need to do:

  1. You need to add the file to the list of source files the type
     machinery scans.  There are three cases:

       a. For a back-end file, this is usually done automatically; if
          not, you should add it to `target_gtfiles' in the appropriate
          port's entries in `config.gcc'.

       b. For files shared by all front ends, this is done by adding the
          filename to the `GTFILES' variable in `Makefile.in'.

       c. For any other file used by a front end, this is done by
          adding the filename to the `gtfiles' variable defined in
          `config-lang.in'.  For C, the file is `c-config-lang.in'.
          This list should include all files that have GTY macros in
          them that are used in that front end, other than those
          defined in the previous list items.  For example, it is
          common for front end writers to use `c-common.c' and other
          files from the C front end, and these should be included in
          the `gtfiles' variable for such front ends.


  2. If the file was a header file, you'll need to check that it's
     included in the right place to be visible to the generated files.
     For a back-end header file, this should be done automatically.
     For a front-end header file, it needs to be included by the same
     file that includes `gtype-LANG.h'.  For other header files, it
     needs to be included in `gtype-desc.c', which is a generated file,
     so add it to `ifiles' in `open_base_file' in `gengtype.c'.

     For source files that aren't header files, the machinery will
     generate a header file that should be included in the source file
     you just changed.  The file will be called `gt-PATH.h' where PATH
     is the pathname relative to the `gcc' directory with slashes
     replaced by -, so for example the header file to be included in
     `objc/objc-parse.c' is called `gt-objc-objc-parse.c'.  The
     generated header file should be included after everything else in
     the source file.  Don't forget to mention this file as a
     dependency in the `Makefile'!

  3. If a new `gt-PATH.h' file is needed, you need to arrange to add a
     `Makefile' rule that will ensure this file can be built.  This is
     done by making it a dependency of `s-gtype', like this:

     gt-path.h : s-gtype ; @true

   For language frontends, there is another file that needs to be
included somewhere.  It will be called `gtype-LANG.h', where LANG is
the name of the subdirectory the language is contained in.  It will
need `Makefile' rules just like the other generated files.


File: gccint.info,  Node: Funding,  Next: GNU Project,  Prev: Type Information,  Up: Top

Funding Free Software
*********************

   If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development.  The most effective approach known is to encourage
commercial redistributors to donate.

   Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers--the Free Software Foundation, and others.

   The way to convince distributors to do this is to demand it and
expect it from them.  So when you compare distributors, judge them
partly by how much they give to free software development.  Show
distributors they must compete to be the one who gives the most.

   To make this approach work, you must insist on numbers that you can
compare, such as, "We will donate ten dollars to the Frobnitz project
for each disk sold."  Don't be satisfied with a vague promise, such as
"A portion of the profits are donated," since it doesn't give a basis
for comparison.

   Even a precise fraction "of the profits from this disk" is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably less
than a dollar; it might be a few cents, or nothing at all.

   Some redistributors do development work themselves.  This is useful
too; but to keep everyone honest, you need to inquire how much they do,
and what kind.  Some kinds of development make much more long-term
difference than others.  For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much.  Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU Compiler Collection
contribute more; major new features or packages contribute the most.

   By establishing the idea that supporting further development is "the
proper thing to do" when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.

     Copyright (C) 1994 Free Software Foundation, Inc.
     Verbatim copying and redistribution of this section is permitted
     without royalty; alteration is not permitted.


File: gccint.info,  Node: GNU Project,  Next: Copying,  Prev: Funding,  Up: Top

The GNU Project and GNU/Linux
*****************************

   The GNU Project was launched in 1984 to develop a complete Unix-like
operating system which is free software: the GNU system.  (GNU is a
recursive acronym for "GNU's Not Unix"; it is pronounced "guh-NEW".)
Variants of the GNU operating system, which use the kernel Linux, are
now widely used; though these systems are often referred to as "Linux",
they are more accurately called GNU/Linux systems.

   For more information, see:
     `http://www.gnu.org/'
     `http://www.gnu.org/gnu/linux-and-gnu.html'

