diff options
Diffstat (limited to 'doc/gitian-building.md')
| -rw-r--r-- | doc/gitian-building.md | 98 |
1 files changed, 42 insertions, 56 deletions
diff --git a/doc/gitian-building.md b/doc/gitian-building.md index 23059a0506..b356a5d88d 100644 --- a/doc/gitian-building.md +++ b/doc/gitian-building.md @@ -4,8 +4,8 @@ Gitian building *Setup instructions for a gitian build of Bitcoin using a Debian VM or physical system.* Gitian is the deterministic build process that is used to build the Bitcoin -Core executables [1]. It provides a way to be reasonably sure that the -executables are really built from source on github. It also makes sure that +Core executables. It provides a way to be reasonably sure that the +executables are really built from source on GitHub. It also makes sure that the same, tested dependencies are used and statically built into the executable. Multiple developers build the source code by following a specific descriptor @@ -17,9 +17,6 @@ More independent gitian builders are needed, which is why I wrote this guide. It is preferred to follow these steps yourself instead of using someone else's VM image to avoid 'contaminating' the build. -[1] For all platforms except for MacOSX, at this point. Work for deterministic -builds for Mac is under way here: https://github.com/theuni/osx-cross-depends . - Table of Contents ------------------ @@ -34,19 +31,22 @@ Table of Contents - [Signing externally](#signing-externally) - [Uploading signatures](#uploading-signatures) -Create a new VirtualBox VM ---------------------------- +Preparing the Gitian builder host +--------------------------------- + +The first step is to prepare the host environment that will be used to perform the Gitian builds. +This guide explains how to set up the environment, and how to start the builds. -The first step is to create a new Virtual Machine, which will be explained in -this section. This VM will be used to do the Gitian builds. In this guide it -will be explained how to set up the environment, and how to get the builds -started. +Debian Linux was chosen as the host distribution because it has a lightweight install (in contrast to Ubuntu) and is readily available. +Any kind of virtualization can be used, for example: +- [VirtualBox](https://www.virtualbox.org/), covered by this guide +- [KVM](http://www.linux-kvm.org/page/Main_Page) +- [LXC](https://linuxcontainers.org/), see also [Gitian host docker container](https://github.com/gdm85/tenku/tree/master/docker/gitian-bitcoin-host/README.md). -Debian Linux was chosen as the host distribution because it has a lightweight install (in -contrast to Ubuntu) and is readily available. We here show the steps for -VirtualBox [1], but any kind of virtualization can be used. You can also install -on actual hardware instead of using a VM, in this case you can skip this section. +You can also install on actual hardware instead of using virtualization. +Create a new VirtualBox VM +--------------------------- In the VirtualBox GUI click "Create" and choose the following parameters in the wizard:  @@ -74,11 +74,11 @@ In the VirtualBox GUI click "Create" and choose the following parameters in the - Disk size: at least 40GB; as low as 20GB *may* be possible, but better to err on the safe side - Push the `Create` button -Get the [Debian 7.4 net installer](http://cdimage.debian.org/debian-cd/7.4.0/amd64/iso-cd/debian-7.4.0-amd64-netinst.iso). +Get the [Debian 7.4 net installer](http://ftp.at.debian.org/debian-jigdo/current/amd64/iso-cd/debian-7.4.0-amd64-netinst.iso) (a more recent minor version should also work, see also [Debian Network installation](https://www.debian.org/CD/netinst/)). This DVD image can be validated using a SHA256 hashing tool, for example on Unixy OSes by entering the following in a terminal: - echo "b712a141bc60269db217d3b3e456179bd6b181645f90e4aac9c42ed63de492e9 /home/orion/Downloads/debian-7.4.0-amd64-netinst.iso" | sha256sum -c + echo "b712a141bc60269db217d3b3e456179bd6b181645f90e4aac9c42ed63de492e9 debian-7.4.0-amd64-netinst.iso" | sha256sum -c # (must return OK) After creating the VM, we need to configure it. @@ -106,8 +106,6 @@ Then start the VM. On the first launch you will be asked for a CD or DVD image.  -[1] https://www.virtualbox.org/ - Installing Debian ------------------ @@ -133,7 +131,7 @@ and proceed, just press `Enter`. To select a different button, press `Tab`.  -- Choose a root password and enter it twice (and remember it for later) +- Choose a root password and enter it twice (remember it for later)  @@ -142,7 +140,7 @@ and proceed, just press `Enter`. To select a different button, press `Tab`.   -- Choose a user password and enter it twice (and remember it for later) +- Choose a user password and enter it twice (remember it for later)  @@ -227,7 +225,6 @@ In this section we will be setting up the Debian installation for Gitian buildin First we need to log in as `root` to set up dependencies and make sure that our user can use the sudo command. Type/paste the following in the terminal: - ```bash apt-get install git ruby sudo apt-cacher-ng qemu-utils debootstrap lxc python-cheetah parted kpartx bridge-utils adduser debian sudo @@ -236,7 +233,7 @@ adduser debian sudo When you get a colorful screen with a question about the 'LXC directory', just go with the default (`/var/lib/lxc`). -Then set up LXC and the rest with the following is a complex jumble of settings and workarounds: +Then set up LXC and the rest with the following, which is a complex jumble of settings and workarounds: ```bash # the version of lxc-start in Debian 7.4 needs to run as root, so make sure @@ -249,15 +246,16 @@ echo '#!/bin/sh -e' > /etc/rc.local echo 'brctl addbr br0' >> /etc/rc.local echo 'ifconfig br0 10.0.3.2/24 up' >> /etc/rc.local echo 'exit 0' >> /etc/rc.local -# make sure that USE_LXC is always set when logging in as debian +# make sure that USE_LXC is always set when logging in as debian, +# and configure LXC IP addresses echo 'export USE_LXC=1' >> /home/debian/.profile +echo 'export GITIAN_HOST_IP=10.0.3.2' >> /home/debian/.profile +echo 'export LXC_GUEST_IP=10.0.3.5' >> /home/debian/.profile reboot ``` -At the end the VM is rebooted to make sure that the changes take effect. - -**Note**: If you're following this guide on a physical system instead of a VirtualBox VM you could use `10.0.2.2` instead -of `10.0.3.2` in the above `ifconfig` line. This avoids having to patch gitian-builder in next section. +At the end the VM is rebooted to make sure that the changes take effect. The steps in this +section need only to be performed once. Installing gitian ------------------ @@ -279,27 +277,16 @@ cd .. **Note**: When sudo asks for a password, enter the password for the user *debian* not for *root*. -Clone the git repositories for bitcoin and gitian, +Clone the git repositories for bitcoin and gitian and then checkout the bitcoin version that you want to build. ```bash git clone https://github.com/devrandom/gitian-builder.git git clone https://github.com/bitcoin/bitcoin +cd bitcoin +git checkout v${VERSION} +cd .. ``` -We need to change the guest IP range for the gitian builder because otherwise it will -collide with VirtualBox its NAT IP range. Gitian does not have a way yet to configure -this, so we need to patch the IPs using `sed`. This is not nice but it will -have to do for now... (a [pull request -(#52)](https://github.com/devrandom/gitian-builder/pull/52) to make this -configurable without patching has been submitted): - -```bash -sed -i 's/10.0.2.2/10.0.3.2/g' gitian-builder/target-bin/bootstrap-fixup -sed -i 's/10.0.2.5/10.0.3.5/g' gitian-builder/etc/lxc.config.in -``` - -*note* After you update the gitian-builder repository, you may need to repeat these manual changes. - Setting up gitian images ------------------------- @@ -329,10 +316,10 @@ you will find a list of `wget` commands that can be executed to get the dependen I needed to add `--no-check-certificate` to the OpenSSL wget line to make it work. Likely this is because the ca-certificates in Debian 7.4 is fairly old. This does not create a -security issue as the gitian descriptors check integrity of the input archives and refuse to work +security issue as the gitian descriptors check the integrity of the input archives and refuse to work if any one is corrupted. -After downloading the archives, execute the `gbuild` commends to build the dependencies. +After downloading the archives, execute the `gbuild` commands to build the dependencies. This can take a long time, but only has to be done when the dependencies change, for example to upgrade the used version. @@ -349,7 +336,7 @@ tail -f var/build.log Building Bitcoin ---------------- -To build Bitcoin (for Linux and/or Windows) just follow the steps under 'perform +To build Bitcoin (for Linux, OSX and Windows) just follow the steps under 'perform gitian builds' in [doc/release-process.md](release-process.md) in the bitcoin repository. Output from `gbuild` will look something like @@ -382,7 +369,7 @@ can be inspected in `var/install.log` and `var/build.log`. Building an alternative repository ----------------------------------- -If you want to do a test build of a pull on github it can be useful to point +If you want to do a test build of a pull on GitHub it can be useful to point the gitian builder at an alternative repository, using the same descriptors and inputs. @@ -392,13 +379,14 @@ URL=https://github.com/laanwj/bitcoin.git COMMIT=2014_03_windows_unicode_path ./bin/gbuild --commit bitcoin=${COMMIT} --url bitcoin=${URL} ../bitcoin/contrib/gitian-descriptors/gitian-linux.yml ./bin/gbuild --commit bitcoin=${COMMIT} --url bitcoin=${URL} ../bitcoin/contrib/gitian-descriptors/gitian-win.yml +./bin/gbuild --commit bitcoin=${COMMIT} --url bitcoin=${URL} ../bitcoin/contrib/gitian-descriptors/gitian-osx.yml ``` Signing externally ------------------- -If you want to do the PGP signing on another device that's possible too; just define `SIGNER` as mentioned -and follow the steps in the build process as normally. +If you want to do the PGP signing on another device that's also possible; just define `SIGNER` as mentioned +and follow the steps in the build process as normal. gpg: skipped "laanwj": secret key not available @@ -406,8 +394,9 @@ When you execute `gsign` you will get an error from GPG, which can be ignored. C in `gitian.sigs` to your signing machine and do ```bash - gpg --detach-sign ${VERSION}/${SIGNER}/bitcoin-build.assert + gpg --detach-sign ${VERSION}-linux/${SIGNER}/bitcoin-build.assert gpg --detach-sign ${VERSION}-win/${SIGNER}/bitcoin-build.assert + gpg --detach-sign ${VERSION}-osx/${SIGNER}/bitcoin-build.assert ``` This will create the `.sig` files that can be committed together with the `.assert` files to assert your @@ -416,9 +405,6 @@ gitian build. Uploading signatures --------------------- -After building and signing you can push your signatures (both the `.assert` and -`.assert.sig` files) to the -[bitcoin/gitian.sigs](https://github.com/bitcoin/gitian.sigs/) repository, or -if not possible create a pull request. You can also mail the files to me -(laanwj@gmail.com) and I'll commit them. - +After building and signing you can push your signatures (both the `.assert` and `.assert.sig` files) to the +[bitcoin/gitian.sigs](https://github.com/bitcoin/gitian.sigs/) repository, or if that's not possible create a pull +request. You can also mail the files to me (laanwj@gmail.com) and I'll commit them. |