This is an archive of the discontinued LLVM Phabricator instance.

[lldb][docs] Update documentation for monorepo and CMake caches
ClosedPublic

Authored by sgraenitz on Jul 26 2019, 5:22 AM.

Details

Summary

The lldb build system made good progress in the last months, but documentation was still lacking behind. Here's a patch to catch up. It would be nice to get an update also to the release/9.x branch. What do you think?

Event Timeline

sgraenitz created this revision.Jul 26 2019, 5:22 AM
Herald added a project: Restricted Project. · View Herald TranscriptJul 26 2019, 5:22 AM
sgraenitz added a subscriber: friss.

LGTM (beside the standalone build section which I have no experience with).

Looks good to me.

In general, this looks great overall! I added few comments on things that would be good to clarify.

lldb/docs/resources/build.rst
108

Nit: It would be nice to have this link to the CMake Options paragraph.

147

Is the casing of Clang_DIR important here? (In most cases, CMake defines are all upper case, but perhaps this one is special?) If the casing is important, I would suggest noting that here. If it's not important, it's probably simpler go all upper case to match other usages.

248

It's unclear from reading the paragraph if using these caches is recommended for most users. If it is, it would helpful to state that. In general, some kind of statement that answers "who should use this" would help.

266

Nit: Standalone -> standalone perhaps?

sgraenitz updated this revision to Diff 211922.Jul 26 2019, 6:06 AM
sgraenitz marked 2 inline comments as done.

Add links to sections

sgraenitz updated this revision to Diff 211930.Jul 26 2019, 6:37 AM
sgraenitz marked an inline comment as done.

Polish section Standalone builds

sgraenitz updated this revision to Diff 211931.Jul 26 2019, 6:41 AM
sgraenitz marked 2 inline comments as done.

Polish section CMake caches

jryans accepted this revision.Jul 26 2019, 6:42 AM

Great! 😁 Thanks for working on this!

This revision is now accepted and ready to land.Jul 26 2019, 6:42 AM

Since Visual Studio is the only section in Building LLDB with CMake and Other Generators now, I would like to:

  • move it merge it with another one, preferably Common CMake options > Windows
  • rename Building LLDB with CMake & Ninja into Building LLDB with CMake (analog and with a link to http://llvm.org/docs/CMake.html)

Would that be acceptable?

Since Visual Studio is the only section in Building LLDB with CMake and Other Generators now, I would like to:

  • move it merge it with another one, preferably Common CMake options > Windows
  • rename Building LLDB with CMake & Ninja into Building LLDB with CMake (analog and with a link to http://llvm.org/docs/CMake.html)

Would that be acceptable?

Yes, this sounds like a good plan.

sgraenitz updated this revision to Diff 211951.Jul 26 2019, 8:53 AM

Merge Visual Studio build instructions into Common CMake options > Windows

Since Visual Studio is the only section in Building LLDB with CMake and Other Generators now, ...

Yes, this sounds like a good plan.

Cool, patch Diff 211951 has the change. Here's the difference in generated output:
https://weliveindetail.github.io/blog/res/lldb-docs/resources/build.html
https://weliveindetail.github.io/blog/res/lldb-docs/resources/build-merged-vs.html

sgraenitz added a comment.EditedJul 26 2019, 9:24 AM

I added a few links to LLVM documentation here and wondered what to do with them, if this gets cherry-picked to release/9.x, e.g. https://llvm.org/docs/CMake.html Ideally they would point to their 9.x counterparts, e.g. https://releases.llvm.org/9.0.0/docs/CMake.html and with 9.0.1 it should become https://releases.llvm.org/9.0.1/docs/CMake.html

llvm/docs/AdvancedBuilds.rst links within one build directory using ":doc:CMake", but apparently this doesn't work cross-project?

I could imaging to patch it once for the release and use configure_file from CMake to import the current version, but I am no sure if it's worth the effort =)

Is there a simple way to do this in Sphinx? Ideas / opinions?

Thanks, this looks good to me.

jryans accepted this revision.Jul 26 2019, 9:41 AM

I added a few links to LLVM documentation here and wondered what to do with them, if this gets cherry-picked to release/9.x, e.g. https://llvm.org/docs/CMake.html Ideally they would point to their 9.x counterparts, e.g. https://releases.llvm.org/9.0.0/docs/CMake.html and with 9.0.1 it should become https://releases.llvm.org/9.0.1/docs/CMake.html

llvm/docs/AdvancedBuilds.rst links within one build directory using ":doc:CMake", but apparently this doesn't work cross-project?

I could imaging to patch it once for the release and use configure_file from CMake to import the current version, but I am no sure if it's worth the effort =)

Is there a simple way to do this in Sphinx? Ideas / opinions?

Hmm, are there the LLDB docs archived per release? For LLVM overall, there's https://releases.llvm.org/ with links to say https://releases.llvm.org/8.0.0/docs/index.html, but LLDB doesn't seem to appear in sub-project list of versioned docs... I would say it's fine to not worry about this for now, and we can improve in a separate patch if needed.

Looks good. Thanks for doing these updates!

lldb/docs/resources/build.rst
86

"Check out" should be two words here.

lldb/docs/resources/build.rst
94

Is Ninja the recommended build tool on Windows as well?

105

I thought some of the tests need lld as well

234

We retired VS2015 support

Hmm, are there the LLDB docs archived per release? [...] LLDB doesn't seem to appear in sub-project list of versioned docs

Right, Clang docs are here: https://releases.llvm.org/8.0.0/tools/clang/docs/index.html, but it's not the same as http://clang.llvm.org/
Apparently, LLDB docs aren't archived. Where did you find the sub-project list of versioned docs?

Where did you find the sub-project list of versioned docs?

On http://releases.llvm.org/, for some recent versions like 8.0.0, the "Documentation" column has separate versioned links for "llvm clang lld clang-extra libc++ polly", but lldb doesn't appear there.

On http://releases.llvm.org/, for some recent versions like 8.0.0, the "Documentation" column has separate versioned links for "llvm clang lld clang-extra libc++ polly", but lldb doesn't appear there.

Interesting. Thks!

lldb/docs/resources/build.rst
94

Well it's recommended for LLVM and I used it for LLDB on Windows in the past.
Maybe @zturner knows more about it?

105

So far, the documentation didn't mention lld. I would recommend using lld to build LLDB on Linux, but AFAIK it's not required to build lld along with LLDB.

234

What generator string would you like to see here instead? (So far I just kept what was there.)

lldb/docs/resources/build.rst
94

LLDB does build with both Ninja and VS on Windows. I don't know that either one is "recommended" though and we usually build with VS.

105

For example, lldb\lit\SymbolFile\DWARF\debug-types-basic.test contains this:

REQUIRES: lld

There are other tests as well that require lld.

234

cmake -G "Visual Studio 15 2017 Win64" -Thost=x64

amccarth added inline comments.Jul 26 2019, 11:06 AM
lldb/docs/resources/build.rst
94

I use Ninja exclusively for both LLVM in general and LLDB in particular, regardless of whether I'm building with MSVC or bootstrapping with Clang.

Having a VS solution is great for finding your way around the repo and debugging. But Ninja seems to build much faster.

Can we add a section for "Building LLDB with Xcode"? We had a shell script patch that was going to be checked in, not sure if it made it. But it did a two part thing where it built LLVM and clang and then generated an Xcode project. I would rather just produce the Xcode project using cmake, very similar to other instructions. My mac cmake line has:

cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;libcxx;lldb" -DCMAKE_BUILD_TYPE:STRING=Debug -DLLVM_ENABLE_ASSERTIONS:BOOL=TRUE -DLLDB_BUILD_FRAMEWORK:BOOL=TRUE -DLLDB_USE_SYSTEM_DEBUGSERVER=ON /path/to/llvm-project/llvm

Important bits are the projects being set to "clang;libcxx;lldb" (include libcxx) and building the framework and using the system debugserver

sgraenitz updated this revision to Diff 212051.Jul 27 2019, 5:34 AM
sgraenitz marked 11 inline comments as done.

Address recent feedback

sgraenitz marked an inline comment as done.Jul 27 2019, 6:13 AM

Hi Greg, thanks for your feedback.

Can we add a section for "Building LLDB with Xcode"? We had a shell script patch that was going to be checked in, not sure if it made it. But it did a two part thing where it built LLVM and clang and then generated an Xcode project.

"Build LLDB standalone for development with Xcode" describes it, see http://tiny.cc/i5ncaz#common-configurations-on-macos

I would rather just produce the Xcode project using cmake, very similar to other instructions.

This means changing the generator from Ninja to Xcode. I added a short note that other generators like Xcode or Visual Studio may be used as well (maybe we can avoid calling it "support", because in fact multi-config generators cause a lot of trouble).

My mac cmake line has:

cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;libcxx;lldb" -DCMAKE_BUILD_TYPE:STRING=Debug -DLLVM_ENABLE_ASSERTIONS:BOOL=TRUE -DLLDB_BUILD_FRAMEWORK:BOOL=TRUE -DLLDB_USE_SYSTEM_DEBUGSERVER=ON /path/to/llvm-project/llvm

LLVM_ENABLE_ASSERTIONS and many other important flags are documented in LLVM (linked from http://tiny.cc/i5ncaz#building-lldb-with-cmake).
CMAKE_BUILD_TYPE=Debug is the default
LLDB_BUILD_FRAMEWORK and LLDB_USE_SYSTEM_DEBUGSERVER are explained in the macOS section, see http://tiny.cc/i5ncaz#id2.

Important bits are the projects being set to "clang;libcxx;lldb" (include libcxx) and building the framework and using the system debugserver

Added an explanation for the test suite libcxx dependency to the macOS section too.

lldb/docs/resources/build.rst
94

I added a short note that other generators like Xcode or Visual Studio may be used as well (please see my answer to Greg).

sgraenitz updated this revision to Diff 212052.Jul 27 2019, 6:15 AM

Feedback and polishing; latest rendered output here: http://tiny.cc/i5ncaz

jryans accepted this revision.Jul 29 2019, 3:12 AM

Current version looks great to me! 😁

lldb/docs/resources/build.rst
91

This could be done in a separate patch, but I happened to notice that Get Involved section on the LLDB main page currently suggests Subversion at the moment. It would be nice to have this updated to Git as well.

If we're going to be mentioning test dependencies, then it probably makes sense to mention lld too. AFAIK, lld is required for running the (dotest) test suite on windows. On other platforms it is not required, but there are tests which will only get run if lld is enabled.

Thanks for your feedback.

lld is required for running the (dotest) test suite on windows. On other platforms it is not required, but there are tests which will only get run if lld is enabled.

I mentioned this in Regular in-tree builds as: Parts of the LLDB test suite require lld. Add it to the list in order to run all tests.

lldb/docs/resources/build.rst
91

+1 (in a separate patch)

labath accepted this revision.Jul 29 2019, 8:43 AM

Thanks for putting this together.

I think you need one small change for lld still - to make it clear that it is required on Windows in the Windows section, but it looks good otherwise. Please fix that before committing.

lldb/docs/resources/build.rst
189

The windows section should include a similar note to the macOS section for libcxx - but for lld.

sgraenitz updated this revision to Diff 212304.Jul 30 2019, 3:16 AM

Add lld note to Windows section

sgraenitz marked an inline comment as done.Jul 30 2019, 3:16 AM
This revision was automatically updated to reflect the committed changes.
Herald added a project: Restricted Project. · View Herald TranscriptJul 30 2019, 3:21 AM
sgraenitz marked 3 inline comments as done.Jul 30 2019, 4:49 AM
sgraenitz added inline comments.
lldb/docs/resources/build.rst
91