Version bump.
[builders/tor-browser-bundle.git] / gitian / README.build
1 QuickStart:
2
3  On an Ubuntu 12.04+ machine or VM, run:
4
5  $ make
6
7  This will check all of your prerequisites and tell you what you need to
8  do to get started to build the stable TBB.
9
10  If everything checks out OK, it will begin downloading dependencies, and then
11  start the build process to produce localized Linux bundles, followed by
12  Windows bundles, followed by Mac bundles.
13
14  To check your build results against the official builders, run:
15
16  $ make match
17
18  By default, the Makefile wraps input downloads in 'torsocks'. This is done
19  to allow unofficial secret verifiers to remain secret by default. To download
20  inputs without torsocks, run:
21
22  $ make TORSOCKS=
23
24  By default, 'make' will also clear out any previous partial builds. See the
25  "Partial Rebuilds" section for information on performing partial rebuilds
26  without erasing previously built components.
27
28  If you would also like to download fresh copies of your inputs before a
29  build, run 'make distclean' (note that timestamps and versions of downloaded
30  source input files are checked every time you run 'make' by default so
31  distclean should not normally be needed).
32
33  To set the number of make processes and virtual CPUs to use inside the VMs
34  to four (the default is two), use:
35
36  $ export NUM_PROCS=4
37
38  To set the amount of RAM to use inside the VMs to 4000 MiB (the default is
39  2000 MiB), use:
40
41  $ export VM_MEMORY=4000
42
43 Detailed Explanation of Scripts:
44
45  This directory is a wrapper around our modified version of Gitian, and has
46  several helper scripts to make things easier.
47
48  0. Makefile: The main Makefile. It has six main commands:
49      - prep: Check OS prerequisites and download source dependency inputs
50      - build: Build localized bundles for Linux, Windows, and Mac
51      - clean: Remove prior partial build stages (Tor and Firefox)
52      - vmclean: Remove VM base images
53      - distclean: Remove source dependency inputs, and run clean and vmclean
54      - all: The default. It calls clean, prep, and then build.
55      - sign: Signs your build output and uplodas it to people.torproject.org
56      - match: Checks your build output against public signed hashes
57     To build alpha bundles, alternate targets are provided:
58      - alpha: The equivalent to the 'all' rule for alpha packages
59      - build-alpha: The equivalent to the 'build' rule for alpha packages
60      - prep-alpha: The equivalent to the 'prep' rule for alpha packages
61      - sign-alpha: Signs your build output and uplodas it to people.torproject.org
62      - match-alpha: Checks your build output against public signed hashes
63  
64  1. check-prerequisites.sh: This script checks if your system is capable of
65     running Gitian, and if it is not, it tells you what you need to do.
66     It is called by 'make prep'.
67  
68  2. fetch-inputs.sh: This script fetches all of our source dependencies from
69     the Internet and downloads them into ../../gitian-builder/inputs.
70     After you run this script, you should be able to complete the rest of your
71     build offline.
72
73  3. versions: This scriptlet contains version definitions for the source
74     dependencies, the git tags to use, and the Tor Browser release version.
75
76  4. verify-tags.sh: This script verifies the signatures on git tags from
77     the versions file. It is only run if VERIFY_TAGS is set in the versions
78     file.
79   
80  5. descriptors: In the descriptors directory, you will find the Gitian
81     descriptors for Linux, Windows, and Mac. There are three descriptors for
82     each platform: One to build Tor and its dependencies, one to build Firefox
83     and its dependencies, and one to bundle everything together. Each
84     descriptor is run from a fresh VM.
85  
86  6. mkbundle-linux.sh: This script is a wrapper around Gitian's gbuild to call
87     the appropriate descriptors to build 32 and 64 bit Linux bundle. It also will
88     create build VM images for you if you haven't done that before.
89  
90  7. mkbundle-windows.sh: This script is a wrapper around Gitian's gbuild to
91     call the appropriate descriptors to build a Windows bundle. It also will
92     create build VM images for you if you haven't done that before.
93
94  8. mkbundle-mac.sh: This script is a wrapper around Gitian's gbuild to
95     call the appropriate descriptors to build a 32bit Mac bundle. It also
96     will create build VM images for you if you haven't done that before.
97
98
99 Partial Rebuilds:
100
101   The mkbundle shell scripts each have three Gitian stages.
102
103   First, using their platform's gitian-tor.yml Gitian descriptor, they build
104   tor and the tor dependencies (libevent, zlib, and openssl). Second, using
105   the gitian-firefox.yml descriptor, they build Firefox with the Tor Browser
106   patches and preferences applied. Third, in gitian-bundle.yml, they assemble
107   the bundles using the addons and localization packs.
108
109   The Tor and Firefox stages end up as a *gbuilt*.zip files in
110   ../../gitian-builder/inputs/, and those zip files are used as inputs into
111   the final bundling and localization stage. If those files exist in that
112   directory, the corresponding bundle will *not* be built.
113
114   No other dependency checking on build stages is performed.
115
116   This means that if any of the source inputs, or the Ubuntu buildchain tools,
117   or the build tools' dependencies upgrade, your Tor and Firefox inputs will
118   no longer match those produced by someone else's build from a fresher VM
119   that downloaded those newer toolchain packages.
120
121   This means for official builds, you should always run 'make clean' (which
122   is called by the default Makefile target).
123
124
125 Known Issues and Quirks:
126
127   1. Sometimes, fresh VM installs can fail. If your build hangs while trying
128      to connect to the target or during the SSH banner, it might be worth
129      running 'make vmclean && make build' to clean your VM images, but still
130      resume the build process as the component you left off at.  Remember,
131      'make' by itself runs a clean rule that will wipe your previous builds by
132      default.
133
134      If you have already completed a Linux build, you may run into situations
135      where 'make vmclean' causes the rebuild of two VMs in a row.. This might
136      trigger weird bugs in python-vm-builder.. To rebuild only one set of VMs,
137      use either 'rm ../../gitian-builder/*precise*' (to remove the Windows/Mac
138      VMs) or 'rm ../../gitian-builder/*lucid*' (to remove the Linux VMs).
139
140      You probably want to make sure you have no stray qemu processes before
141      rebuilding the VMs or starting a new build, too.
142
143      Once you get a working set of base VMs (in ../../gitian-builder/base-*),
144      you should probably copy them somewhere safe if you want to avoid VM
145      creation hangs in the future (or help us write a wrapper script that
146      tests VMs and re-runs the VM creation step if they don't boot).
147
148   2. One out of every 50 builds or so, 'make' locks up at some point during a
149      build, probably due to timestamp issues inside the Gitian VM. The
150      symptoms of this are a hung build where the VM or LXC container processes
151      are consuming no CPU.
152
153      Simply re-running 'make build' will resume the appropriate bundle
154      component for you.
155
156   3. If you use git branches for any repos instead of tags (for example, for
157      a development or nightly build), fresh commits will need to be
158      merged manually (or better git-fu is needed in ./fetch-inputs.sh, as
159      it is currently meant to deal with tags only).
160
161   4. Running more than one instance of Gitian at a time is not supported.
162
163   5. Related: If you perform a fresh Gitian checkout for purposes of
164      verification, be sure to kill any stray qemu VM processes before starting
165      the new build (because the new Gitian checkout will not have the PID or
166      SSH keys of the previous instances' VM, and VM startup will either hang
167      or prompt you for an SSH password).
168
169   6. The number of cpus in the VM images is currently hardcoded at 4. If you
170      need a different number, please let me know and I will write a patch to 
171      support configuring the number of CPUs easily.
172
173   7. LXC-built bundles are still not deterministic and may run into other issues.
174      See TODO file for details.
175
176 Diagnosing Problems:
177
178   During a running build, you can tail logs in real time in
179   ../../gitian-builder/var/*.log 
180
181   Upon failure, logs of any failed component builds are relocated to
182   ../../gitian-builder/*fail*.log. This is to prevent subsequent builds
183   from destroying failure information.
184