[PATCH] D53598: Add docs+a script for building clang/LLVM with PGO

[George Burgess IV via Phabricator via llvm-commits]

george.burgess.iv added a comment.

Thank you!

> For most users I think maybe that's also the most important part, because I think many folks build quite differently

Agreed. The script is only really made to cover simple builds/cases where users just want a general profile and are happy to pipe that through their own build logic.

If users can't use the script itself, my hope is that `--dry-run` will serve as a more easily executable form of documentation, and that the script itself ends up being a gentle reminder to update the docs when it breaks. :)



================
Comment at: docs/HowToBuildWithPGO.rst:43
+
+- solid coverage of building C++,
+- good coverage of building C,
----------------
hans wrote:
> Including solid coverage for emitting all kinds of C++ diagnostics, whereas in many user builds none would be emitted. This is just a nit-pick, I'm not sure if there's a better way, but that might be one downside of using these kinds of tests for training.
Not quite; I think I worded the above badly.

We basically do two things to "train" the instrumented clang/llvm:
- In the instrumented clang/llvm's build directory, run all lit/unit tests
- In a new build directory, build everything with the instrumented clang/llvm

The hope is that "build everything" will strongly bias hot paths toward the common-ish "your code is pretty OK" paths. The other tests may bias some colder branches the wrong way, but I'd imagine that:

- That's not really an issue in practice, hence "colder"
- For cases that aren't e.g. building code for the host arch, we'll still get some coverage for what's hot/not, as long as we have the relevant backends enabled.

Tried to clarify above a bit. Please let me know if it's still unclear


================
Comment at: docs/HowToBuildWithPGO.rst:69
+3. Build your "benchmark" (detailed above) with the second Clang that you built
+4. Generate a profile from the benchmark runs
+5. Build a final release Clang (along with whatever other binaries you need)
----------------
hans wrote:
> 3 and 4 kind of go together? I guess the outputs have to be merged, but the profile really is built while running the benchmarks, or that's how I think about it.
*shrug* 

I'm not strongly opinionated, so SGTM :)


================
Comment at: docs/HowToBuildWithPGO.rst:92
+3. Build your benchmark using the Clang generated in step 2. The 'standard'
+   benchmark recommended is to build Clang. So, create yet another build
+   directory, with the following CMake arguments
----------------
hans wrote:
> But the text says its running the test suite instead?
Tried to address this above as part of my response to your second comment


https://reviews.llvm.org/D53598