Merge branch 'vendor/GCC50' - gcc 5.0 snapshot 1 FEB 2015
[dragonfly.git] / contrib / gcc-5.0 / gcc / doc / collect2.texi
1 @c Copyright (C) 1988-2015 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}.