gcc/doc/gccint/collect2.rst

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