[lld] 6d5603e - [LLD][ELF] Add initial LLD LinkerScript docs page

[Peter Smith via llvm-commits]

Author: Peter Smith
Date: 2020-03-11T10:56:12Z
New Revision: 6d5603e2d22041c4873da4daebab3386a462c3e0

URL: https://github.com/llvm/llvm-project/commit/6d5603e2d22041c4873da4daebab3386a462c3e0
DIFF: https://github.com/llvm/llvm-project/commit/6d5603e2d22041c4873da4daebab3386a462c3e0.diff

LOG: [LLD][ELF] Add initial LLD LinkerScript docs page

LLD implements Linker Scripts as they are described in the GNU ld manual.
This description is far from a specification, with the only true reference
the GNU ld implementation, which has undocumented behaviour that can vary
from release to release.

To make it easy for people to switch between linkers we try to follow GNU
ld implementation details wherever possible. We reserve the right to make
our own decisions where the undocumented GNU ld behaviour is not
appropriate for LLD. We don't have a place to document these decisions and
it can be difficult for users to find out this information.

This file is a statement of the LLD implementation policy and will contain
intentional deviations from GNU ld.

The first patch that will add concrete details to this file is D75724

Differential Revision: https://reviews.llvm.org/D75921

Added: 
    lld/docs/ELF/linker_script.rst

Modified: 
    lld/docs/index.rst

Removed: 
    


################################################################################
diff  --git a/lld/docs/ELF/linker_script.rst b/lld/docs/ELF/linker_script.rst
new file mode 100644
index 000000000000..aebefeca9d5e
--- /dev/null
+++ b/lld/docs/ELF/linker_script.rst
@@ -0,0 +1,18 @@
+Linker Script implementation notes and policy
+=============================================
+
+LLD implements a large subset of the GNU ld linker script notation. The LLD
+implementation policy is to implement linker script features as they are
+documented in the ld `manual <https://sourceware.org/binutils/docs/ld/Scripts.html>`_
+We consider it a bug if the lld implementation does not agree with the manual
+and it is not mentioned in the exceptions below.
+
+The ld manual is not a complete specification, and is not sufficient to build
+an implementation. In particular some features are only defined by the
+implementation and have changed over time.
+
+The lld implementation policy for properties of linker scripts that are not
+defined by the documentation is to follow the GNU ld implementation wherever
+possible. We reserve the right to make 
diff erent implementation choices where
+it is appropriate for LLD. Intentional deviations will be documented in this
+file.

diff  --git a/lld/docs/index.rst b/lld/docs/index.rst
index 68604c27f95a..b001f884f0bd 100644
--- a/lld/docs/index.rst
+++ b/lld/docs/index.rst
@@ -176,3 +176,4 @@ document soon.
    missingkeyfunction
    Partitions
    ReleaseNotes
+   ELF/linker_script