gdb: add target_ops::supports_displaced_step

[deliverable/binutils-gdb.git] / gold / README

diff --git a/gold/README b/gold/README
index aa318f2daa8e20eb04919d62e214d64dcb6d8ece..ee6c08f817ddda32ccac95f265f3f4e04ea092f4 100644 (file)
--- a/gold/README
+++ b/gold/README
@@ -1,18 +1,69 @@
 gold is an ELF linker.  It is intended to have complete support for
-ELF and to run as fast as possible on modern systems.
+ELF and to run as fast as possible on modern systems.  For normal use
+it is a drop-in replacement for the older GNU linker.
 
-It is written in C++.  It is (intended to be) a GNU program, and
-therefore follows the GNU formatting standards as modified for C++.
-Source documents in order of precedence:
+gold is part of the GNU binutils.  See ../binutils/README for more
+general notes, including where to send bug reports.
+
+gold was originally developed at Google, and was contributed to the
+Free Software Foundation in March 2008.  At Google it was designed by
+Ian Lance Taylor, with major contributions by Cary Coutant, Craig
+Silverstein, and Andrew Chatham.
+
+The existing GNU linker manual is intended to be accurate
+documentation for features which gold supports.  gold supports most of
+the features of the GNU linker for ELF targets.  Notable
+omissions--features of the GNU linker not currently supported in
+gold--are:
+  * MRI compatible linker scripts
+  * cross-reference reports (--cref)
+  * various other minor options
+
+
+Notes on the code
+=================
+
+These are some notes which may be helpful to people working on the
+source code of gold itself.
+
+gold is written in C++.  It is a GNU program, and therefore follows
+the GNU formatting standards as modified for C++.  Source documents in
+order of decreasing precedence:
     http://www.gnu.org/prep/standards/
-    http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE
+    http://gcc.gnu.org/onlinedocs/libstdc++/manual/source_code_style.html
     http://www.zembu.com/eng/procs/c++style.html
 
 The linker is intended to have complete support for cross-compilation,
-which still supporting the normal case of native linking as fast as
-possible.  This makes the code more complex.
+while still supporting the normal case of native linking as fast as
+possible.  In order to do this, many classes are actually templates
+whose parameter is the ELF file class (e.g., 32 bits or 64 bits).  The
+C++ code is the same, but we don't pay the execution time cost of
+always using 64-bit integers if the target is 32 bits.  Many of these
+class templates also have an endianness parameter: true for
+big-endian, false for little-endian.
+
+The linker is multi-threaded.  The Task class represents a single unit
+of work.  Task objects are stored on a single Workqueue object.  Tasks
+communicate via Task_token objects.  Task_token objects are only
+manipulated while holding the master Workqueue lock.  Relatively few
+mutexes are used.
+
+
+Build requirements
+==================
+
+The gold source code uses templates heavily.  Building it requires a
+recent version of g++.  g++ 4.0.3 and 4.1.3 are known to work.  g++
+3.2, 3.4.3, and 4.1.2 are known to fail.
+
+The linker script parser uses features which are only in newer
+versions of bison.  bison 2.3 is known to work.  bison 1.26 is known
+to fail.  If you are building gold from an official binutils release,
+the bison output should already be included.
+
+\f
+Copyright (C) 2012-2020 Free Software Foundation, Inc.
 
-Many functions are actually templates whose parameter is the ELF file
-class (e.g., 32 bits or 64 bits).  The code is the same, but we don't
-want to pay the execution time cost of always using 64-bit integers if
-the target is 32 bits.
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.