Add a LLVM_USE_LINKER that defines the linker to use when building LLVM

[mehdi_amini]

Summary

This string parameter is passed to -fuse-ld when linking. It can be
an absolute path to your custom linker, otherwise clang will look for
ld.{name}.

[mehdi_amini]

Fix missing endif()

[mehdi_amini]

Restore unintended removal of warning on Apple when using LLD and LTO, and fix tailing whitespace.

[davide]

This is a nice improvement. Some comments inline.

llvm/cmake/modules/HandleLLVMOptions.cmake

99–101

I think still emitting a diagnostic in this case would be good. In general, I think we should emit a diagnostic on every linker that can't do LTO when we try to do it. Why did you remove it?

llvm/docs/CMake.rst

385–389

Hmm, this can be expanded a bit. If clang is used as base compiler, what you say is perfectly fine.
But gcc has some limitations:

1. it doesn't support absoule paths.
2. it hardcodes a couple of values, bfd/gold and rejects everything else.

[mehdi_amini]

Expand a bit the doc as pointed by Davide.

[davide]

LGTM modulo nit.

llvm/cmake/modules/HandleLLVMOptions.cmake

156–158

I think the correct spelling is doesn't

llvm/cmake/modules/HandleLLVMOptions.cmake

 
 set(EXEEXT ${CMAKE_EXECUTABLE_SUFFIX})
 set(LTDL_SHLIB_EXT ${CMAKE_SHARED_LIBRARY_SUFFIX})
 
 # We use *.dylib rather than *.so on darwin.
 set(LLVM_PLUGIN_EXT ${CMAKE_SHARED_LIBRARY_SUFFIX})
 
 if(APPLE)
-  if(LLVM_ENABLE_LLD AND LLVM_ENABLE_LTO)
-    message(FATAL_ERROR "lld does not support LTO on Darwin")
-  endif()
   # Darwin-specific linker flags for loadable modules.
   set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} -Wl,-flat_namespace -Wl,-undefined -Wl,suppress")
 endif()
 
 # Pass -Wl,-z,defs. This makes sure all symbols are defined. Otherwise a DSO
 # build might work on ELF but fail on MachO/COFF.
 if(NOT (${CMAKE_SYSTEM_NAME} MATCHES "Darwin" OR WIN32 OR CYGWIN OR
         ${CMAKE_SYSTEM_NAME} MATCHES "FreeBSD" OR
if (C_SUPPORTS_${name} AND CXX_SUPPORTS_${name})
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${flag}" PARENT_SCOPE)
     set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${flag}" PARENT_SCOPE)
     set(CMAKE_ASM_FLAGS "${CMAKE_ASM_FLAGS} ${flag}" PARENT_SCOPE)
   else()
     message(WARNING "${flag} is not supported.")
   endif()
 endfunction()
 
-if(LLVM_ENABLE_LLD)
-  check_cxx_compiler_flag("-fuse-ld=lld" CXX_SUPPORTS_LLD)
-  append_if(CXX_SUPPORTS_LLD "-fuse-ld=lld"
+if( LLVM_ENABLE_LLD )
+  if ( LLVM_USE_LINKER )
+    message(FATAL_ERROR "LLVM_ENABLE_LLD and LLVM_USE_LINKER can't be set at the same time")
+  set(LLVM_USE_LINKER "lld")
+endif()
+
+if( LLVM_USE_LINKER )
+  check_cxx_compiler_flag("-fuse-ld=${LLVM_USE_LINKER}" CXX_SUPPORTS_CUSTOM_LINKER)
+  if ( NOT CXX_SUPPORTS_CUSTOM_LINKER )
+    message(FATAL_ERROR "Host compiler don't support '-fuse-ld=${LLVM_USE_LINKER}'")
+  endif()
+  append("-fuse-ld=${LLVM_USE_LINKER}"
     CMAKE_EXE_LINKER_FLAGS CMAKE_MODULE_LINKER_FLAGS CMAKE_SHARED_LINKER_FLAGS)
 endif()
 
 if( LLVM_ENABLE_PIC )
   if( XCODE )
     # Xcode has -mdynamic-no-pic on by default, which overrides -fPIC. I don't
     # know how to disable this, so just force ENABLE_PIC off for now.
     message(WARNING "-fPIC not supported with Xcode.")

llvm/docs/CMake.rst

**LLVM_USE_SANITIZER**:STRING
   are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
   and ``Address;Undefined``. Defaults to empty string.
 
 **LLVM_ENABLE_LTO**:STRING
   Add ``-flto`` or ``-flto=`` flags to the compile and link command
   lines, enabling link-time optimization. Possible values are ``Off``,
   ``On``, ``Thin`` and ``Full``. Defaults to OFF.
 
+**LLVM_USE_LINKER**:STRING
+  Add ``-fuse-ld={name}`` to the link invocation. The value can be an absolute
+  path to your custom linker, otherwise clang will prefix the name with ``ld.``
+  and apply its usual search. For example to link LLVM with the Gold linker, 
+  cmake can be invoked with ``-DLLVM_USE_LINKER=gold``.
+
+**LLVM_ENABLE_LLD**:BOOL
+  This option is equivalent to `-DLLVM_USE_LINKER=lld`, except during a 2-stage
+  build where a dependency is added from the first stage to the second ensuring
+  that lld is built before stage2 begins.
+
 **LLVM_PARALLEL_COMPILE_JOBS**:STRING
   Define the maximum number of concurrent compilation jobs.
 
 **LLVM_PARALLEL_LINK_JOBS**:STRING
   Define the maximum number of concurrent link jobs.
 
 **LLVM_BUILD_DOCS**:BOOL
   Adds all *enabled* documentation targets (i.e. Doxgyen and Sphinx targets) as