[LLD][DOCS][ELF]Add initial LLD LinkerScript docs page

[psmith]

Summary

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 linker script implementation policy and will contain intentional deviations from GNU ld. The first patch that will add concrete details to this file is D75724

[grimar]

Nice!

lld/docs/ELF/linker_script.rst

6

index.rst uses a different formar of URL:

`Getting Started with the LLVM System
<http://llvm.org/docs/GettingStarted.html>`

(I just do not know is it important or not, I guess it can be)

[psmith]

Thanks for spotting that. I've used the same style as the other file. I've checked the resulting html and link works.

[MaskRay]

lld/docs/ELF/linker_script.rst

6

Missing a trailing _

See https://docutils.sourceforge.io/docs/user/rst/quickref.html#external-hyperlink-targets

Configure with -DLLVM_ENABLE_SPHINX=on, then ninja -C /path/to/build docs-lld-html.

It currently fails for me probably because of the version problem:

Theme error:
An error happened in rendering the page index.
Reason: TemplateNotFound()
ninja: build stopped: subcommand failed.

lld/docs/ELF/linker_script.rst

+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 different implementation choices where
+it is appropriate for LLD. Intentional deviations will be documented in this
+file.

lld/docs/index.rst

.. toctree::
 
    NewLLD
    AtomLLD
    WebAssembly
    windows_support
    missingkeyfunction
    Partitions
    ReleaseNotes
+   ELF/linker_script