Page MenuHomePhabricator

Adjust documentation for git migration.
ClosedPublic

Authored by jyknight on Jan 28 2019, 7:53 AM.

Details

Summary

This fixes most references to the paths:
llvm.org/svn/
llvm.org/git/
llvm.org/viewvc/
github.com/llvm-mirror/
github.com/llvm-project/
reviews.llvm.org/diffusion/

to instead point to https://github.com/llvm/llvm-project.

This is *not* a trivial substitution, because additionally, all the
checkout instructions had to be migrated to instruct users on how to
use the monorepo layout, setting LLVM_ENABLE_PROJECTS instead of
checking out various projects into various subdirectories.

I've attempted to *NOT* change any scripts here, only
documentation. The scripts will have to be addressed separately.

Event Timeline

jyknight created this revision.Jan 28 2019, 7:53 AM
jyknight updated this revision to Diff 183891.Jan 28 2019, 9:24 AM

Fix some warnings I added.

Restore TestSuiteMakefileGuide.rst, which apparently isn't 100%
obsolete. (But it is incorrect, and I'm not sure exactly how to fix
it, so I just left a FIXME).

smeenai accepted this revision.Jan 28 2019, 2:16 PM
smeenai added a subscriber: smeenai.

The amount of duplicated and out-of-date documentation makes me sad, but this is an awesome effort to clean that up.

lldb/packages/Python/lldbsuite/test/functionalities/command_source/TestCommandSource.py
4

Would you want to link to the corresponding GitHub commit?

lldb/packages/Python/lldbsuite/test/lang/objc/objc-optimized/TestObjcOptimized.py
4

Same here.

This revision is now accepted and ready to land.Jan 28 2019, 2:16 PM

LGTM, but for one comment that requires a fix I believe (lld on Windows)

libcxx/docs/BuildingLibcxx.rst
47

So nice to see these steps going away :)

57–58

Wonder if it is worth mentioning somewhere how to sparse-checkout?

libcxxabi/www/index.html
86

Do you now if prefixing with CC is equivalent to -DCMAKE_C_COMPILER?

lld/docs/getting_started.rst
71

Missing -DLLVM_ENABLE_PROJECTS=lld here I believe

labath added a subscriber: labath.Jan 29 2019, 1:34 AM

I am not sure we should be recommending to people to place the build folder under the llvm-project checkout. Is that how people use the monorepo build nowadays? This is not an full out-of-source build, since the build folder is still a subfolder of the repo root (and without a .gitignore file containing the right build folder name, git will complain about untracked files in the repository)...

libcxxabi/www/index.html
86

It usually is, but it can differ once you start using cache and toolchain files. In any case, using -DCMAKE_C(XX)_COMPILER is the preferred way to do things in cmake.

jyknight marked 8 inline comments as done.Jan 29 2019, 8:29 AM

I am not sure we should be recommending to people to place the build folder under the llvm-project checkout. Is that how people use the monorepo build nowadays? This is not an full out-of-source build, since the build folder is still a subfolder of the repo root (and without a .gitignore file containing the right build folder name, git will complain about untracked files in the repository)...

Well, it's certainly how I do it. I find it the least confusing, because then I don't get mixed up as to which source tree a given build directory belongs to (or directories, as I may also have build-release, build-debug, etc).

libcxx/docs/BuildingLibcxx.rst
57–58

Yes, I think it likely is worth mentioning that somewhere in the future -- but I'd rather not recommend it yet. There's two things that will impact that:

  1. We'll need to decide where we plan to keep shared infrastructure (e.g. cmake macros etc) used by multiple subprojects within the repository.
  2. It seems as though git is actually gaining new support for this kind of thing now, might be worth letting that mature a little bit.
libcxxabi/www/index.html
86

Changed to specify the cmake arguments.

lld/docs/getting_started.rst
71

Yep fixed.

lldb/packages/Python/lldbsuite/test/functionalities/command_source/TestCommandSource.py
4

After viewing said commit, I felt it wasn't actually useful to visit to understand this file, which is why I removed the link.

lldb/packages/Python/lldbsuite/test/lang/objc/objc-optimized/TestObjcOptimized.py
4

Felt the same in this case.

This revision was automatically updated to reflect the committed changes.
jyknight marked 2 inline comments as done.

This is not an full out-of-source build, since the build folder is still a subfolder of the repo root

My definition of what qualify an "out-of-source" build is that the build process won't touch anything outside of the build directory: i.e. the build directory itself is hermetic, self-contained, and can be destroyed without impacting anything else.
(I agree with you that polluting git status is annoying, and personally I usually have my build directories in parallel with the repo).

This is not an full out-of-source build, since the build folder is still a subfolder of the repo root

My definition of what qualify an "out-of-source" build is that the build process won't touch anything outside of the build directory: i.e. the build directory itself is hermetic, self-contained, and can be destroyed without impacting anything else.
(I agree with you that polluting git status is annoying, and personally I usually have my build directories in parallel with the repo).

You can avoid the git status pollution by adding the build directory to .git/info/exclude.

You can avoid the git status pollution by adding the build directory to .git/info/exclude.

Good to know! Should we include this in the doc?

You can avoid the git status pollution by adding the build directory to .git/info/exclude.

Good to know! Should we include this in the doc?

I can put that change up fore review. It probably makes most sense to add it to www/get_started.html? There's lots of different places which document building, but that seems like the canonical one.