| 1 | gold is an ELF linker. It is intended to have complete support for |
| 2 | ELF and to run as fast as possible on modern systems. For normal use |
| 3 | it is a drop-in replacement for the older GNU linker. |
| 4 | |
| 5 | gold is part of the GNU binutils. See ../binutils/README for more |
| 6 | general notes, including where to send bug reports. |
| 7 | |
| 8 | gold was originally developed at Google, and was contributed to the |
| 9 | Free Software Foundation in March 2008. At Google it was designed by |
| 10 | Ian Lance Taylor, with major contributions by Cary Coutant, Craig |
| 11 | Silverstein, and Andrew Chatham. |
| 12 | |
| 13 | The existing GNU linker manual is intended to be accurate |
| 14 | documentation for features which gold supports. gold supports most of |
| 15 | the features of the GNU linker for ELF targets. Notable |
| 16 | omissions--features of the GNU linker not currently supported in |
| 17 | gold--are: |
| 18 | * MEMORY regions in linker scripts |
| 19 | * MRI compatible linker scripts |
| 20 | * cross-reference reports (--cref) |
| 21 | * various other minor options |
| 22 | |
| 23 | |
| 24 | Notes on the code |
| 25 | ================= |
| 26 | |
| 27 | These are some notes which may be helpful to people working on the |
| 28 | source code of gold itself. |
| 29 | |
| 30 | gold is written in C++. It is a GNU program, and therefore follows |
| 31 | the GNU formatting standards as modified for C++. Source documents in |
| 32 | order of decreasing precedence: |
| 33 | http://www.gnu.org/prep/standards/ |
| 34 | http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE |
| 35 | http://www.zembu.com/eng/procs/c++style.html |
| 36 | |
| 37 | The linker is intended to have complete support for cross-compilation, |
| 38 | while still supporting the normal case of native linking as fast as |
| 39 | possible. In order to do this, many classes are actually templates |
| 40 | whose parameter is the ELF file class (e.g., 32 bits or 64 bits). The |
| 41 | C++ code is the same, but we don't pay the execution time cost of |
| 42 | always using 64-bit integers if the target is 32 bits. Many of these |
| 43 | class templates also have an endianness parameter: true for |
| 44 | big-endian, false for little-endian. |
| 45 | |
| 46 | The linker is multi-threaded. The Task class represents a single unit |
| 47 | of work. Task objects are stored on a single Workqueue object. Tasks |
| 48 | communicate via Task_token objects. Task_token objects are only |
| 49 | manipulated while holding the master Workqueue lock. Relatively few |
| 50 | mutexes are used. |
| 51 | |
| 52 | |
| 53 | Build requirements |
| 54 | ================== |
| 55 | |
| 56 | The gold source code uses templates heavily. Building it requires a |
| 57 | recent version of g++. g++ 4.0.3 is known to work. g++ 3.2 and g++ |
| 58 | 3.4.3 are known to fail. |
| 59 | |
| 60 | The linker script parser uses features which are only in newer |
| 61 | versions of bison. bison 2.3 is known to work. bison 1.26 is known |
| 62 | to fail. If you are building gold from an official binutils release, |
| 63 | the bison output should already be included. |