gcc/doc/collect2.texi

   1 @c Copyright (C) 1988-2017 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 a hard coded linker file name, if GCC was configured with the
  36 @option{--with-ld} option.
  37
  38 @item
  39 @file{real-ld} in the directories listed in the compiler's search
  40 directories.
  41
  42 @item
  43 @file{real-ld} in the directories listed in the environment variable
  44 @code{PATH}.
  45
  46 @item
  47 The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
  48 if specified.
  49
  50 @item
  51 @file{ld} in the compiler's search directories, except that
  52 @code{collect2} will not execute itself recursively.
  53
  54 @item
  55 @file{ld} in @code{PATH}.
  56 @end itemize
  57
  58 ``The compiler's search directories'' means all the directories where
  59 @command{gcc} searches for passes of the compiler.  This includes
  60 directories that you specify with @option{-B}.
  61
  62 Cross-compilers search a little differently:
  63
  64 @itemize @bullet
  65 @item
  66 @file{real-ld} in the compiler's search directories.
  67
  68 @item
  69 @file{@var{target}-real-ld} in @code{PATH}.
  70
  71 @item
  72 The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
  73 if specified.
  74
  75 @item
  76 @file{ld} in the compiler's search directories.
  77
  78 @item
  79 @file{@var{target}-ld} in @code{PATH}.
  80 @end itemize
  81
  82 @code{collect2} explicitly avoids running @code{ld} using the file name
  83 under which @code{collect2} itself was invoked.  In fact, it remembers
  84 up a list of such names---in case one copy of @code{collect2} finds
  85 another copy (or version) of @code{collect2} installed as @code{ld} in a
  86 second place in the search path.
  87
  88 @code{collect2} searches for the utilities @code{nm} and @code{strip}
  89 using the same algorithm as above for @code{ld}.