gitian: "run it with the --setup command" needs example

[Sjors]

Current docs say:

If you are using the automated script, then run it with the --setup command. Afterwards, run it with the --build command (example: contrib/gitian-build.sh -b signer 0.15.0). Otherwise ignore this.

This leaves out details that confuse new developers (it confused me last summer, and still does).

It doesn't mention that this command should be run from ~, so it should be bitcoin/contrib/gitian-build.sh. It doesn't explain if you need to checkout the right tag of the bitcoin repository (afaik you shouldn't).

It doesn't explain how to use the --setup command, in particular whether arguments like singer are required (--help isn't clear on that either).

[Sjors]

The documentation says:

--kvm           Use KVM instead of LXC
--setup         Set up the Gitian building environment. Uses KVM.

This is confusing. Why would setup use a different default / setting? Not sure if that's a bug in the documentation on in the script.

[Sjors]

Someone pointed out on IRC a few months ago: "You can and should just copy the script out of the folder where you have the bitcoin source and use it from outside of that"

OSX stuff needs to be done first, see #13.

Script may throw errors if you don't configure your email address for Git:

git config --global user.email "you@example.com"

This seems to work for me:

cp bitcoin/contrib/gitian-build.sh .
./gitian-build.sh --setup -b sjors 0.16.0rc1

(leave out -b?)

Where sjors is my Github name, 0.16.0rc1 the release tag, but without v prefix.

If you see an error like lxc-execute: start.c: lxc_spawn: 1079 Failed to find gateway addresses, it's probably because of #15.

[Sjors]

This worked for me, without the need to configure my email in git:

./gitian-build.sh --setup --detach-sign --no-commit -b sjors 0.16.0rc2

[fivepiece]

Re. gitconfig in the host VM, what I did want to set up but did not have a chance yet is :

1. Fork the gitian.sigs on github
2. On the gitian host VM, clone the forked repo from github
3. On the "metal" host, clone the forked repo from github and set a second remote to the cloned repo in the gitian host VM or clone the repo from the gitian host VM and set a second remote to github
4. Run the gitian build process without signing, commit the unsigned asserts
5. On the metal host, pull the unsigned asserts from the VM remote
6. Sign and commit the signatures for the assert files
7. Push to the github remote
8. Create PR against Core's gitian.sigs

I think it should be possible to script this if using ssh keys

[Sjors]

That sounds more clean than the scp stuff I've been drafting. See also #18.

I assume you're amending the commit on the metal host? How do you prevent the VM host from being confused next time it pulls? Single use branches might help.

[fivepiece]

Ah I see, yes my comment is more related to that issue :)
I'll copy it there so it's all in one place.

[Sjors]

Although it's possible to run a build with --setup, it's probably more clear to only perform the once-only steps here. In that case, is it still necessary to specify a tag? Would be nice if --setup just uses master.

[fivepiece]

Right about using --setup once, though instead of master maybe it should default to the latest tag. Also git pulling of all the relevant repos for subsequent runs is probably needed, and specifically for the detached-sigs repo it should also checkout the same tag that's being built in case these changed (pretty sure it doesn't currently).

[Sjors]

In my experience it automatically pulls the relevant repos (without --setup).

[fivepiece]

Ah good to know, I only ran with --setup each time because I was using snapshots.

[Sjors]

Assuming the user runs gitian-build.sh from the bitcoin repo, I think it should just use whatever version is currently checked out, typically master. Someone also recommended copying the script out of the repo, maybe it should insist on that.

[fivepiece]

But what reason is there to build master with gitian?