[PATCH] D77346: [docs] Corrected inaccuracies in Common Problems section

[Evan LeClercq via Phabricator via llvm-commits]

e-leclercq created this revision.
e-leclercq added reviewers: Meinersbur, tstellar, rnk, t.p.northover, dim, fhahn, gbedwell.
Herald added subscribers: llvm-commits, aprantl.
Herald added a project: LLVM.

Changed the language in LLVM_USE_LINKER to more strongly recommend LLD and to specify that the gold linker is only useful if LLD is unavailable in binary form and it is the first build of LLVM. Corrected information in CMAKE_BUILD_TYPE regarding the Release build type and enabling assertions, also added the MinSizeRel build type. Added option LLVM_ENABLE_ASSERTIONS and mentioned enabling this option with the Release build as an alternative to using the 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 Linux, and CLANG_ENABLE_STATIC_ANALYZER only slightly improves build time.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D77346

Files:
  llvm/docs/GettingStarted.rst


Index: llvm/docs/GettingStarted.rst
===================================================================
--- llvm/docs/GettingStarted.rst
+++ llvm/docs/GettingStarted.rst
@@ -1105,34 +1105,39 @@
    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 improve performance. 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.
-
- * -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.
+   This option defaults to Debug, but this causes higher memory usage during the
+   linking phase. So, you may wish to use the Release build type and to enable 
+   assertions. This may not be as easy to debug; however, this may be a good 
+   middle ground. If you are still having problems with slow build time or high 
+   memory usage, then you might try the MinSizeRel build type.
+
+ * -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 
+   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.
+ * -DLLVM_OPTIMIZED_TABLEGEN  
+   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
@@ -1141,14 +1146,14 @@
 
  * -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).
+   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). This option is only available on Linux.
 
 .. _links:
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D77346.254640.patch
Type: text/x-patch
Size: 4454 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20200402/0b6cd6cf/attachment.bin>