Document `LLVM_USE_SPLIT_DWARF` option

[beanz]

Summary

This patch adds a documentation note about the LLVM_USE_SPLIT_DWARF CMake option which is useful to reduce linker memory usage.

[dblaikie]

FWIW, the current support is incomplete - if you just turn on -gsplit-dwarf, gdb may misbehave owing to a lack of index. (you'd need to add -Wl,-gdb-index to CMAKE_*_LINKER_FLAGS)

Arguably we could/should fix LLVM itself to pass that flag when using -gsplit-dwarf while tuning for gdb and/or improve the LLVM CMake build to add the flag.

[anton-afanasyev]

In D68556#1698442, @dblaikie wrote:

FWIW, the current support is incomplete - if you just turn on -gsplit-dwarf, gdb may misbehave owing to a lack of index. (you'd need to add -Wl,-gdb-index to CMAKE_*_LINKER_FLAGS)

Arguably we could/should fix LLVM itself to pass that flag when using -gsplit-dwarf while tuning for gdb and/or improve the LLVM CMake build to add the flag.

Since --gdb-index option is added to LLVM_USE_SPLIT_DWARF (https://reviews.llvm.org/D108776) I think this could be landed with a couple of words added about --gdb-index.

BTW, the LLVM_USE_SPLIT_DWARF option is even documented at "GettingStarted" (https://reviews.llvm.org/D75425) already, but it's still not represented here, at full list.

[dblaikie]

In D68556#2971997, @anton-afanasyev wrote:

In D68556#1698442, @dblaikie wrote:

FWIW, the current support is incomplete - if you just turn on -gsplit-dwarf, gdb may misbehave owing to a lack of index. (you'd need to add -Wl,-gdb-index to CMAKE_*_LINKER_FLAGS)

Arguably we could/should fix LLVM itself to pass that flag when using -gsplit-dwarf while tuning for gdb and/or improve the LLVM CMake build to add the flag.

Since --gdb-index option is added to LLVM_USE_SPLIT_DWARF (https://reviews.llvm.org/D108776) I think this could be landed with a couple of words added about --gdb-index.

Yeah, sounds about right.

[aprantl]

llvm/docs/CMake.rst

624

meory -> memory

625

should this be: platforms using the ELF object format, like Linux
I suppose this also works on FreeBSD?

[dblaikie]

llvm/docs/CMake.rst

625

Should do, yeah - though I've not tried it.

[xgupta]

This comment was removed by xgupta.

[anton-afanasyev]

Reverse ping :) Just a gentle reminder this is ready to land (with minor nits).

[xgupta]

rebase, address nits, and committed in https://reviews.llvm.org/rGb2544fb9c5b38339572d50048563e8b6e72bf0ad, Thanks.

llvm/docs/CMake.rst

 
 **LLVM_ENABLE_BINDINGS**:BOOL
   If disabled, do not try to build the OCaml and go bindings.
 
 **LLVM_ENABLE_Z3_SOLVER**:BOOL
   If enabled, the Z3 constraint solver is activated for the Clang static analyzer.
   A recent version of the z3 library needs to be available on the system.
 
+**LLVM_USE_SPLIT_DWARF**:BOOL
+  If enabled CMake will pass ``-gsplit-dwarf`` to the compiler. This option
+  reduces link-time meory usage by reducing the amount of debug information that
+  the linker needs to resolve. It is recommended for use on Linux systems when
+  linker memory usage is too high.
+
 CMake Caches
 ============
 
 Recently LLVM and Clang have been adding some more complicated build system
 features. Utilizing these new features often involves a complicated chain of
 CMake variables passed on the command line. Clang provides a collection of CMake
 cache scripts to make these features more approachable.