README 7.82 KB
Newer Older
boklm's avatar
boklm committed
1
2
3
4
5
6
7
Tor Browser Build
=================

Installing build dependencies
-----------------------------

To build Tor Browser, you need a Linux distribution that has support
8
for runc (such as Debian jessie, Ubuntu 16.04, Fedora 20, etc ...).
9
10
On Debian jessie, the runc package is available in backports. On Debian
stretch, the runc package is available in the main repository.
boklm's avatar
boklm committed
11

Georg Koppen's avatar
Georg Koppen committed
12
13
14
Your user account should have sudo access, which is required to be able
to extract container file systems, start containers and copy files to and
from containers.
boklm's avatar
boklm committed
15

16
The sources of most components are downloaded using git, which needs to
17
be installed. Some components are downloaded using mercurial which also
18
needs to be installed.
boklm's avatar
boklm committed
19
20
21
22
23
24
25
26

You also need a few perl modules installed:
- YAML::XS
- File::Basename
- Getopt::Long
- Template
- IO::Handle
- IO::CaptureOutput
27
- JSON
boklm's avatar
boklm committed
28
- File::Temp
29
- Path::Tiny
boklm's avatar
boklm committed
30
- File::Path
boklm's avatar
boklm committed
31
- File::Copy::Recursive
boklm's avatar
boklm committed
32
33
34
35
36
37
38
39
40
41
- String::ShellQuote
- Sort::Versions
- Digest::SHA
- Data::UUID
- Data::Dump

If you are running Debian or Ubuntu, you can install them with:

# apt-get install libyaml-libyaml-perl libtemplate-perl \
                  libio-handle-util-perl libio-all-perl \
42
                  libio-captureoutput-perl libjson-perl libpath-tiny-perl \
boklm's avatar
boklm committed
43
44
                  libstring-shellquote-perl libsort-versions-perl \
                  libdigest-sha-perl libdata-uuid-perl libdata-dump-perl \
45
                  libfile-copy-recursive-perl git runc \
46
                  mercurial
boklm's avatar
boklm committed
47

48
49
50
51
The build system is based on rbm, which is included as a git submodule
in the rbm/ directory. You can fetch the rbm git submodule by running
'make submodule-update'.

boklm's avatar
boklm committed
52
53
54
55
56
57

Starting a build
----------------

To start a build, run one of the following commands, depending on the
channel you want to build:
58

boklm's avatar
boklm committed
59
60
61
62
63
64
  $ make release
  $ make alpha
  $ make nightly

You can find the build result in the directory release/unsigned/$version
or alpha/unsigned/$version for release or alpha builds. The result of
65
nightly can be found in the nightly/$date directory.
boklm's avatar
boklm committed
66
67
68
69
70
71
72
73

If you want to build for a specific platform only, append the platform
name to the makefile target:

  $ make nightly-linux-x86_64
  $ make nightly-linux-i686
  $ make nightly-windows-i686
  $ make nightly-osx-x86_64
74
  $ make nightly-android-armv7
75
  $ make nightly-android-aarch64
76
  $ make nightly-android-x86
77
  $ make nightly-android-x86_64
boklm's avatar
boklm committed
78

boklm's avatar
boklm committed
79
80
81
82
83
84
When you want to quickly do a build to test a change, you can use the
testbuild makefile target, and find the build in the testbuild directory.
The build will be the same as regular alpha builds, except that in order
to make the build faster, only the en-US locale will be built, and no
mar file will be created.

boklm's avatar
boklm committed
85
86
87
88
89
90

Updating git sources
--------------------

You can run "make fetch" to fetch the latest sources from git for all
components included in Tor Browser. You should run this if you want to
91
92
make a nightly build with the latest commits, and you disabled automatic
fetching of new commits for nightly builds in rbm.local.conf.
boklm's avatar
boklm committed
93
94


95
96
97
98
99
Number of make processes
------------------------

By default the builds are run with 4 processes simultaneously (with
make -j4). If you want to change the number of processes used, you can
100
set the RBM_NUM_PROCS environment variable:
101

102
  $ export RBM_NUM_PROCS=8
103

104
You can also set the buildconf/num_procs option in rbm.local.conf.
105
106


boklm's avatar
boklm committed
107
108
109
110
111
112
113
114
115
116
Automated builds
----------------

If the build fails, a shell will automatically open in the build
container to help you debug the problem. You probably want to disable
this if you want to do automated builds. To disable this, set
the RBM_NO_DEBUG environment variable to 1:

   export RBM_NO_DEBUG=1

117
118
Or set the debug option to 0 in the rbm.local.conf file.

boklm's avatar
boklm committed
119
120
If you want to select the output directory, you can use rbm's --output-dir
option. You can look at the Makefile to find the rbm command for what
Georg Koppen's avatar
Georg Koppen committed
121
you want to build, and add the --output-dir option. For example, if you
boklm's avatar
boklm committed
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
want to build Tor Browser nightly for linux-x86_64:

   ./rbm/rbm build release --output-dir=/var/builds/nightly/2017-01-23 \
                        --target nightly --target torbrowser-linux-x86_64

The files will be put in the directory selected by --output-dir in a
subdirectory named as the version number (or current date for nightly).
To remove this version subdirectory, add the noversiondir target:

   ./rbm/rbm build release --output-dir=/var/builds/nightly/2017-01-23 \
                        --target nightly --target torbrowser-linux-x86_64 \
                        --target noversiondir


Automated builds using tbb-testsuite
------------------------------------

The Tor Browser testsuite scripts can also be used to do nightly builds
140
141
142
and publish the build logs. The recommended way to do that is to use
the ansible roles from the tools/ansible directory. See next section
for details.
boklm's avatar
boklm committed
143
144


145
146
Using ansible to set up a nightly build machine
-----------------------------------------------
boklm's avatar
boklm committed
147

148
149
150
151
The directory tools/ansible contains some ansible roles to set up a
nightly build machine. You can look at the playbook defined in
boklm-tbb-nightly-build.yml and variables in group_vars/boklm-tbb-nightly/
for an example of how it can be used.
boklm's avatar
boklm committed
152
153


154
155
156
157
158
159
Signing builds
--------------

If the environment variable RBM_SIGN_BUILD is set to 1, the
sha256sums-unsigned-build.txt file will be signed with gpg.
You can use the RBM_GPG_OPTS environment variable to add some options
160
161
162
to the gpg command used to sign the file. You can also set the
var/sign_build and var/sign_build_gpg_opts options in the rbm.local.conf
file.
163
164


boklm's avatar
boklm committed
165
166
167
Cleaning obsolete files and containers images
---------------------------------------------

168
169
170
You can run 'make clean' to clean old build files and containers that
are no longer used in current builds. Before doing that, you need to
configure the branches and build targets you are using in the
Georg Koppen's avatar
Georg Koppen committed
171
rbm.local.conf file. The cleaning script will check out all the configured
172
173
174
175
branches to create a list of used build files, and delete the files
from the 'out' directory that are not used. If you want to see the list
of files and containers that would be removed without doing it, you can
use 'make clean-dry-run'.
boklm's avatar
boklm committed
176

177

178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
Building without containers (Android builds only)
-------------------------------------------------

By default the build is done inside containers. Adding the no_containers
target will disable the use of containers. The following commands can
be used to build the alpha version for android-armv7 and android-x86:

  ./rbm/rbm build release --target no_containers --target testbuild \
                          --target torbrowser-android-armv7
  ./rbm/rbm build release --target no_containers --target testbuild \
                          --target torbrowser-android-x86

Note: the logs will still show the use and creation of a container image
called "containers_disabled". This is due to the way we disable the use
of containers: the container-image project is still called, but it will
just create an empty file instead of a real container image.

The build without containers is currently only supported for the Android
builds, and will require that you run Debian Stretch and install build
dependencies for all the components that are built. This can be done
with the following command:

  # apt-get install build-essential python automake libtool zip unzip
            autoconf2.13 openjdk-8-jdk gettext-base autotools-dev \
            automake autoconf libtool autopoint libssl-dev \
            pkg-config zlib1g-dev libparallel-forkmanager-perl \
204
            libfile-slurp-perl bzip2 xz-utils apksigner yasm
205
206


207
208
209
210
211
212
Common Build Errors
-------------------

You can look at the README.BUILD_ERRORS file for a list of common build
errors and their solutions.

boklm's avatar
boklm committed
213
214
215
216
217
218
219

Hacking on the Tor Browser build
--------------------------------

The file README.HACKING tries to list the main things to know when
making changes to the Tor Browser build.

220
221
222
223
224
225
Description of makefile rules
-----------------------------

You can find a description of the makefile rules in the README.MAKEFILE
file.