Improvements to docs for Gitian build process #9636

According to comments on the Web the Gitian Building doc could be better and I agree. I don't want to create a PR that will invite too many requests for changes, so I thought to check with others interested in fixing that doc.

My thoughts: the LXC approach isn't well documented and doesn't work. Related to containers, there's also a Docker-related link to an external repo that provides additional information which isn't helpful as it used to be since the external resource hasn't been updated for almost 2 years. Another issue is it appears that both the LXC and KVM approach work well, whereas in reality the LXC approach almost certainly doesn't.

Proposal:

• Make it obvious the KVM approach is the preferred approach, and slightly de-emphasize LXC until other contributors improve it. If there's a LXC or Docker enthusiast here who wants to work on this together, we don't have to de-emphasize LXC - we can just improve the existing document and make it usable for LXC and/or Docker. If somebody wants to write it, I'm willing to help with testing or feedback.
• Clarify and improve the KVM related procedure. I'm almost done with this part.

Make it obvious the KVM approach is the preferred approach, and slightly de-emphasize LXC until other contributors improve it.

I disagree - LXC has always worked better for me than KVM. I've followed the gitian-building.md guide many times and it works for me. It documents step by step what to do so I'm stumped at "isn't well documented and doesn't work".

If there are specific problems with it I'd like to know, but as-is, this issue is not helpful.

Okay, I'll create separate issues for LXC-related problems and submit a PR with KVM-related doc improvements before I close this one.

I've been trying to get Gitian builds to work as well and made some documentation improvements: https://github.com/bitcoin/bitcoin/compare/master...Sjors:gitian-doc-improvements?expand=1

This is very much work in progress. I got completely stuck with the LXC approach and noticed the automated script used KVM, which is why I sort of did what @unsystemizer suggested. Although I'm stuck there too...

Has any progress been made in "deciding" between these two options? I'll try the LXC approach again next week and will post specific questions on IRC / Stack Exchange.

@Sjors - the reason for LXC problems is the doc is written for v1 and now it's v2 so the doc isn't useful. KVM works for me (I got a working VM somewhere), but I haven't been able to anything in this regard (the little free time I have, I spend on UASF activism). If you want to work together on this, PM me on Bitcoin Core Slack.

Hi, @Sjors. @unsystemizer I went into the same trouble this weekend as Sjors ending up here this morning. I am installing this on OSX and maybe you can use some help in updating the doc. I managed to install lxc, executed the gitian-build.sh script already. Haven't figured out if it worked out well. The execution returned some lines '..[[:not found', but also 'Your branch up-to-date with 'origin/master'. Thus, my workarounds brought me almost to the finish and might be helpful to others to speed up this installation. Regards.

@testeriknl if you can document your steps here, that would be very useful. @unsystemizer my schedule is a bit unpredictable, but I'll try to see if you're on Slack next time I work on this

@Sjors. Ok, I will. I think i have finished though some errors occured I dont know if they turn out to be fatal or trivial. First I want to make sure i removed redundant or maybe in your opinion WTF? commands. I am not a linux guru. I executed some commands solving "package not found problems" underway -i changed rc.local for instance. Performed several apt-get and -updates afterwards. Later in the process Installed lxc again! As soon as I have a 'clean' install procedure I am back. I think of recording this stuff.

Going to close this, as the gitian build docs are now located in the bitcoin-core/docs repository. Improvements to the guide can be discussed there.

Personally I use kvm as well. Though that doesn't work in other setups, where you install a linux host (e.g. debian or fedora) in a virtual box first. Then you are only left with lxc, which is what the guide focuses on.

I use LXC exactly as-is from the gitian docs, and it seems to work fine anyway other than the issue fixed in #11391. Perhaps that fix is all that was needed anyway.