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

[Michael Kruse via Phabricator via llvm-commits]

Meinersbur added inline comments.


================
Comment at: llvm/docs/GettingStarted.rst:1114
  * -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. On Linux, this causes higher memory usage 
+   during the linking phase. So, you may wish to use the Release build type and 
----------------
aprantl wrote:
> e-leclercq wrote:
> > aprantl wrote:
> > > rnk wrote:
> > > > aprantl wrote:
> > > > > On platforms using ELF (such as Linux), this ...
> > > > 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?
> > > 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.
> > Would clarifying what platforms use ELF in the first paragraph (lines 1098-1100), then marking which fixes are ELF specific in parentheses similar to [[ https://lld.llvm.org/NewLLD.html#important-data-structures | this subsection ]] in the LLD documentation, be agreeable?
> 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
>     ...
> 
> ```
Quick guide is here already: https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code


================
Comment at: llvm/docs/GettingStarted.rst:1116
+    - Debug --- This is the default build type. This disables optimizations while
+      compiling LLVM, enables assertions, and enables debug info.
+    
----------------
assertions are controlled by `LLVM_ENABLE_ASSERTIONS`, not `CMAKE_BUILD_TYPE`


================
Comment at: llvm/docs/GettingStarted.rst:1122-1125
+      platforms (e.g. Linux) linking with debug info may consume a lot of memory.
+      Combining either Release or RelWithDebInfo with -DLLVM_ENABLE_ASSERTIONS 
+      may be a good trade-off between speed and debugability during development, 
+      particularly for running the test suite.
----------------
I'd put the warning about lot's of memory at `Debug` (and `RelWithDebInfo`), which causes them.


================
Comment at: llvm/docs/GettingStarted.rst:1127-1128
+    
+    - MinSizeRel --- If you are still having problems with slow build time or 
+      high memory usage, you may wish to try the MinSizeRel build type.
+
----------------
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.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D77346/new/

https://reviews.llvm.org/D77346