[docs] Corrected inaccuracies in Common Problems section

[e-leclercq]

Summary

Changed the language in LLVM_USE_LINKER to more strongly recommend LLD and to specify that the GNU gold linker is only useful if LLD is unavailable in binary form and it is the first build of LLVM. Added that LLD will help when used on ELF-based platforms. Corrected information in CMAKE_BUILD_TYPE regarding the Release build type and enabling assertions. Added option LLVM_ENABLE_ASSERTIONS and mentioned enabling this option with a Release build as an alternative to using a Debug build. Specified that the LLVM_OPTIMIZED_TABLEGEN option is only for Debug builds, that the LLVM_USE_SPLIT_DWARF option is only available on ELF host platforms, and that setting CLANG_ENABLE_STATIC_ANALYZER to OFF only slightly improves build time. These changes address comments made in D75425.

[Meinersbur]

In the summary, could you mention this addresses additional comments from D75425?

llvm/docs/GettingStarted.rst

1108–1111

Could you clarify that it reduces linking time for the LLVM excecutables (and not e.g. performance of programs compiled with clang)

1164

I am not sure this is Linux-only. It certainly requires DWARF debug information (.i.e no Windows PDB), but It will probably work on BSDs and maybe also using the target x86_64-w64-mingw32.

[e-leclercq]

llvm/docs/GettingStarted.rst

1164

I read up on this a bit more and it appears that this works on both UNIX and Linux, so I will definitely change that. I am not quite sure about Windows though, as I came across this article. Would changing this to "This option can be used on both UNIX and Linux" be adequate?

[Meinersbur]

llvm/docs/GettingStarted.rst

1164

Since the implementation is:

if (LLVM_USE_SPLIT_DWARF AND
    ((uppercase_CMAKE_BUILD_TYPE STREQUAL "DEBUG") OR
     (uppercase_CMAKE_BUILD_TYPE STREQUAL "RELWITHDEBINFO")))
  # Limit to clang and gcc so far. Add compilers supporting this option.
  if (CMAKE_CXX_COMPILER_ID MATCHES "Clang" OR
      CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
    add_compile_options(-gsplit-dwarf)
  endif()
endif()

AFAIK gcc only supports DWARF. Clang supports split-dwarf for ELF targets.

I'd make it a note saying that the option may not be supported on all platforms. On Windows the platform-standard is codeview (.pdb) which is always a separate file. I don't know about MacOS.

[aprantl]

llvm/docs/GettingStarted.rst

1164

Split DWARF is a DWARF+ELF thing, but not tied to an OS. It's specifically not needed/useful/available for Mach-O (Darwin) because debug info isn't processed by Mach-O linkers at all (instead there is dsymutil).

[Meinersbur]

Notable other platforms using ELF are the BSDs, Fuchsia, PlayStation, ...

[e-leclercq]

Corrected the LLVM_USE_SPLIT_DWARF option. Clarified that setting the LLVM_USE_LINKER option and using lld reduces linking time for LLVM executables.

[aprantl]

llvm/docs/GettingStarted.rst

1133

This is only true for ELF targets (I don't know about COFF). In the Mach-O case (i.e., on Darwin/macOS) the presence of de bug info has zero effect on the linker performance, since the linker doesn't touch the debug info at all. Can we prefix that with On Linux, or something similar?

[aprantl]

llvm/docs/GettingStarted.rst

1164

This option may not be supported on all platforms.

Why be so vague, if we know the answer? Can we just say that this only applies to ELF (e.g, Linux) host platforms?

[Meinersbur]

llvm/docs/GettingStarted.rst

1164

My thinking was that beginners may not necessarily know what ELF is. But clarifying in parens is a good idea.

[e-leclercq]

Added more information in CMAKE_BUILD_TYPE option. Specified that info under LLVM_USE_SPLIT_DWARF only applies to host platforms using ELF.

[aprantl]

llvm/docs/GettingStarted.rst

1132–1134

On platforms using ELF (such as Linux), this ...

[rnk]

llvm/docs/GettingStarted.rst

1108–1111

It occurs to me that these recommendations are not really applicable on platforms that don't use GNU binutils ld.bfd by default. Despite my comment below, it would make sense to add some kind of "... on platforms that use ELF, such as Linux" into this. =/

1132–1134

Actually, can I give the opposite feedback? I think adding platform specific admonitions can be confusing. Some day, someone will add an option to run dsymutil as a post-link step on Darwin, and then this statement will be true about Darwin as well as Linux. It is already true for Windows, whether using PDBs or DWARF.

Instead, would it be OK to soften it with This *can* cause high memory usage during the linking phase., so that we can simplify away the condition?

[aprantl]

llvm/docs/GettingStarted.rst

1109

This text also does not apply to Darwin at all, where you would always want to use the system linker (until lld supports Mach-O).

1132–1134

You can already run dsymutil as a post-processing step using the LLVM_EXTERNALIZE_DEBUGINFO cmake option. That's how the clang that ships with Xcode is being built. But it still doesn't come with the same kind of memory explosion that you would get on ELF without split dwarf, since dsymutil (generally speaking) only processes one file at a time and performs type uniquing. I just want to avoid developers cargo-culting configuration options that make sense on one platform to another. On Darwin, the cost of building with debug info is negligible and I want to encourage new developers to use all the great tools we have available in the LLVM project. I don't want people to be afraid of using a debugger on LLVM.

So much for my rant ;-)

I think this text might also benefit from distinguishing between optimizations and debug info (Debug/Release/RelWithDebInfo) which are two axes unfortunately rolled into one CMake setting.

[e-leclercq]

llvm/docs/GettingStarted.rst

1132–1134

Would clarifying what platforms use ELF in the first paragraph (lines 1098-1100), then marking which fixes are ELF specific in parentheses similar to this subsection in the LLD documentation, be agreeable?

[aprantl]

llvm/docs/GettingStarted.rst

1132–1134

I understand that this not supposed to be a full documentation, but a quick start guide, so let me know if this is going too far. What do you think about discussing all the options separately?

* -DCMAKE_BUILD_TYPE
 - Debug
   This is the default. It turns off optimizations (while compiling LLVM itself), enables assertions, and turns on debug info.
 - RelWithDebInfo
   Turns on optimizations, and enables debug info. This results in fast compiler that can still be inspected by a debugger.
 - Release
   Turns on optimizations, and disables debug info. On some platforms (e.g, ELF-based platforms, such as Linux) linking with debug info may consume a lot of memory ...

   Combining Release or RelWithDebInfo with -DLLVM_ENABLE_ASSERTIONS can be a good trade-off between speed and debugability during development, particularly for running the test suite.
 - MinSizeRel
   ...

[e-leclercq]

Reformatted CMAKE_BUILD_TYPE section, adding more specific information on build types. Specified that setting lld with -DLLVM_USE_LINKER helps with memory usage and build time on ELF-based platforms.

[Meinersbur]

llvm/docs/GettingStarted.rst

1132–1134

Quick guide is here already: https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code

1134

assertions are controlled by LLVM_ENABLE_ASSERTIONS, not CMAKE_BUILD_TYPE

1140–1143

I'd put the warning about lot's of memory at Debug (and RelWithDebInfo), which causes them.

1145–1146

MinSizeRel is for compiling with -Os yielding slighly smaller executables, but is not relevant for build times or memory consumption.

Think MinSizeRel or RelWithDebInfo should not be mentioned here. This is not a CMake guide, but intended to help in case of build problems.

[e-leclercq]

llvm/docs/GettingStarted.rst

1134

I read in the CMake.html doc here that LLVM_ENABLE_ASSERTIONS defaults to ON iff the build type is Debug

[e-leclercq]

Moved warning about memory consumption during linking on ELF-based platforms to Debug. Removed RelWithDebInfo and MinSizeRel, as they don't appear to be relevant to reducing build time or memory usage.

[Meinersbur]

llvm/docs/GettingStarted.rst

1134

Yes, it defaults to ON/OFF depending on CMAKE_BUILD_TYPE, but once the CMakeCache.txt has been created, it will not change when CMAKE_BUILD_TYPE is changed.

I recommend not to rely on the default value if you want to have it a specific value.

1139

Don't forget the =ON part for -DLLVM_ENABLE_ASSERTIONS. The cmake invocation will fail without an argument.

(btw, cmake interprets the empty string as false)

[aprantl]

I'm happy with the text changes now.

[e-leclercq]

Removed misleading information regarding both build type and enabling assertions under CMAKE_BUILD_TYPE option. Added =ON to -DLLVM_ENABLE_ASSERTIONS option in paragraph on Release build type to leave no room for confusion.

[Meinersbur]

LGTM.

Do you want me to commit this patch?

[e-leclercq]

@Meinersbur, sure. That would be great!

[Meinersbur]

It would be nice if you could remove trailing whitespace in your patches. I removed them before pushing.

llvm/docs/GettingStarted.rst

 following options with cmake:
 
  * -G Ninja
    Setting this option will allow you to build with ninja instead of make.
    Building with ninja significantly improves your build time, especially with
    incremental builds, and improves your memory usage.
 
  * -DLLVM_USE_LINKER
-   Setting this option to either gold or lld will significantly improve
-   performance. In the case that you are compiling lld, you may wish to use the
-   gold linker as a faster alternative.
+   Setting this option to lld will significantly reduce linking time for LLVM
+   executables on ELF-based platforms, such as Linux. If you are building LLVM
+   for the first time and lld is not available to you as a binary package, then
+   you may want to use the gold linker as a faster alternative to GNU ld.
 
  * -DCMAKE_BUILD_TYPE
-   This option defaults to Debug; however, this may consume more memory during
-   the linking phase. So, you may wish to use the build type Release. Another
-   build type you may wish to consider is release-with-asserts which compiles at
-   nearly the same rate as the Release build; however, it may not be as easy
-   to debug. MinSizeRel is another build type you may wish to consider, if you
-   are still having problems with slow build time.
+
+    - Debug --- This is the default build type. This disables optimizations while
+      compiling LLVM and enables debug info. On ELF-based platforms (e.g. Linux)
+      linking with debug info may consume a large amount of memory.
+
+    - Release --- Turns on optimizations and disables debug info. Combining the
+      Release build type with -DLLVM_ENABLE_ASSERTIONS=ON may be a good trade-off
+      between speed and debugability during development, particularly for running
+      the test suite.
+
+ * -DLLVM_ENABLE_ASSERTIONS
+   This option defaults to ON for Debug builds and defaults to OFF for Release
+   builds. As mentioned in the previous option, using the Release build type and
+   enabling assertions may be a good alternative to using the Debug build type.
 
  * -DLLVM_PARALLEL_LINK_JOBS
    Set this equal to number of jobs you wish to run simultaneously. This is
    similar to the -j option used with make, but only for link jobs. This option
-   is of course only meaningful if you plan to build with ninja. You may wish to
-   use a very low number of jobs, as this will greatly reduce the amount memory
-   used during the build process. If you have limited memory, you may wish to
-   set this to 1.
+   can only be used with ninja. You may wish to use a very low number of jobs,
+   as this will greatly reduce the amount of memory used during the build
+   process. If you have limited memory, you may wish to set this to 1.
 
  * -DLLVM_TARGETS_TO_BUILD
    Set this equal to the target you wish to build. You may wish to set this to
    X86; however, you will find a full list of targets within the
    llvm-project/llvm/lib/Target directory.
 
  * -DLLVM_OPTIMIZED_TABLEGEN
-   Set this to ON to generate a fully optimized tablegen during build. This will
-   significantly improve your build time.
+   Set this to ON to generate a fully optimized tablegen during your build. This
+   will significantly improve your build time. This is only useful if you are
+   using the Debug build type.
 
  * -DLLVM_ENABLE_PROJECTS
    Set this equal to the projects you wish to compile (e.g. clang, lld, etc.) If
-   compiling more than one project, deliniate the list with a semicolon. Should
+   compiling more than one project, separate the items with a semicolon. Should
    you run into issues with the semicolon, try surrounding it with single quotes.
 
  * -DCLANG_ENABLE_STATIC_ANALYZER
    Set this option to OFF if you do not require the clang static analyzer. This
-   should improve your build time significantly.
+   should improve your build time slightly.
 
  * -DLLVM_USE_SPLIT_DWARF
    Consider setting this to ON if you require a debug build, as this will ease
    memory pressure on the linker. This will make linking much faster, as the
    binaries will not contain any of the debug information; however, this will
    generate the debug information in the form of a DWARF object file (with the
-   extension .dwo).
+   extension .dwo). This only applies to host platforms using ELF, such as Linux.
 
 .. _links:
 
 Links
 =====
 
 This document is just an **introduction** on how to use LLVM to do some simple
 things... there are many more interesting and complicated things that you can do
 that aren't documented here (but we'll gladly accept a patch if you want to
 write something up!).  For more information about LLVM, check out:
 
 * `LLVM Homepage <https://llvm.org/>`_
 * `LLVM Doxygen Tree <https://llvm.org/doxygen/>`_
 * `Starting a Project that Uses LLVM <https://llvm.org/docs/Projects.html>`_
 
 .. _installing arcanist: https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/