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
8GCC uses a utility called @code{collect2} on nearly all systems to arrange
9to call various initialization functions at start time.
10
11The program @code{collect2} works by linking the program once and
12looking through the linker output file for symbols with particular names
13indicating they are constructor functions.  If it finds any, it
14creates a new temporary @samp{.c} file containing a table of them,
15compiles it, and links the program a second time including that file.
16
17@findex __main
18@cindex constructors, automatic calls
19The actual calls to the constructors are carried out by a subroutine
20called @code{__main}, which is called (automatically) at the beginning
21of the body of @code{main} (provided @code{main} was compiled with GNU
22CC)@.  Calling @code{__main} is necessary, even when compiling C code, to
23allow linking C and C++ object code together.  (If you use
24@option{-nostdlib}, you get an unresolved reference to @code{__main},
25since it's defined in the standard GCC library.  Include @option{-lgcc} at
26the end of your compiler command line to resolve this reference.)
27
28The program @code{collect2} is installed as @code{ld} in the directory
29where the passes of the compiler are installed.  When @code{collect2}
30needs to find the @emph{real} @code{ld}, it tries the following file
31names:
32
33@itemize @bullet
34@item
35a 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
40directories.
41
42@item
43@file{real-ld} in the directories listed in the environment variable
44@code{PATH}.
45
46@item
47The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
48if 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
60directories that you specify with @option{-B}.
61
62Cross-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
72The file specified in the @code{REAL_LD_FILE_NAME} configuration macro,
73if 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
83under which @code{collect2} itself was invoked.  In fact, it remembers
84up a list of such names---in case one copy of @code{collect2} finds
85another copy (or version) of @code{collect2} installed as @code{ld} in a
86second place in the search path.
87
88@code{collect2} searches for the utilities @code{nm} and @code{strip}
89using the same algorithm as above for @code{ld}.
90