gcc/doc/collect2.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
   2 @c This is part of the GCC manual.
   3 @c For copying conditions, see the file gcc.texi.
   4
   5 @node Collect2
   6 @chapter @code{collect2}
   7
   8 GCC uses a utility called @code{collect2} on nearly all systems to arrange
   9 to call various initialization functions at start time.
  10
  11 The program @code{collect2} works by linking the program once and
  12 looking through the linker output file for symbols with particular names
  13 indicating they are constructor functions.  If it finds any, it
  14 creates a new temporary @samp{.c} file containing a table of them,
  15 compiles it, and links the program a second time including that file.
  16
  17 @findex __main
  18 @cindex constructors, automatic calls
  19 The actual calls to the constructors are carried out by a subroutine
  20 called @code{__main}, which is called (automatically) at the beginning
  21 of the body of @code{main} (provided @code{main} was compiled with GNU
  22 CC)@.  Calling @code{__main} is necessary, even when compiling C code, to
  23 allow linking C and C++ object code together.  (If you use
  24 @option{-nostdlib}, you get an unresolved reference to @code{__main},
  25 since it's defined in the standard GCC library.  Include @option{-lgcc} at
  26 the end of your compiler command line to resolve this reference.)
  27
  28 The program @code{collect2} is installed as @code{ld} in the directory
  29 where the passes of the compiler are installed.  When @code{collect2}
  30 needs to find the @emph{real} @code{ld}, it tries the following file
  31 names:
  32
  33 @itemize @bullet
  34 @item
  35 @file{real-ld} in the directories listed in the compiler's search
  36 directories.
  37
  38 @item
  39 @file{real-ld} in the directories listed in the environment variable
  40 @code{PATH}.
  41
  42 @item
  43 The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
  44 if specified.
  45
  46 @item
  47 @file{ld} in the compiler's search directories, except that
  48 @code{collect2} will not execute itself recursively.
  49
  50 @item
  51 @file{ld} in @code{PATH}.
  52 @end itemize
  53
  54 ``The compiler's search directories'' means all the directories where
  55 @command{gcc} searches for passes of the compiler.  This includes
  56 directories that you specify with @option{-B}.
  57
  58 Cross-compilers search a little differently:
  59
  60 @itemize @bullet
  61 @item
  62 @file{real-ld} in the compiler's search directories.
  63
  64 @item
  65 @file{@var{target}-real-ld} in @code{PATH}.
  66
  67 @item
  68 The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
  69 if specified.
  70
  71 @item
  72 @file{ld} in the compiler's search directories.
  73
  74 @item
  75 @file{@var{target}-ld} in @code{PATH}.
  76 @end itemize
  77
  78 @code{collect2} explicitly avoids running @code{ld} using the file name
  79 under which @code{collect2} itself was invoked.  In fact, it remembers
  80 up a list of such names---in case one copy of @code{collect2} finds
  81 another copy (or version) of @code{collect2} installed as @code{ld} in a
  82 second place in the search path.
  83
  84 @code{collect2} searches for the utilities @code{nm} and @code{strip}
  85 using the same algorithm as above for @code{ld}.