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

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

boklm's avatar
boklm committed
7
8
9
10
To build Tor Browser, you need a recent Linux distribution with support
for user_namespaces(7) (such as Debian Buster, Ubuntu 16.04, Fedora 30,
etc ...). You will need to install the uidmap package, providing the
newuidmap and newgidmap commands.
boklm's avatar
boklm committed
11

12
The sources of most components are downloaded using git, which needs to
Georg Koppen's avatar
Georg Koppen committed
13
be installed.
boklm's avatar
boklm committed
14
15
16
17
18
19
20
21

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

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

37
# apt-get install libyaml-libyaml-perl libtemplate-perl libdatetime-perl \
boklm's avatar
boklm committed
38
                  libio-handle-util-perl libio-all-perl \
39
                  libio-captureoutput-perl libjson-perl libpath-tiny-perl \
boklm's avatar
boklm committed
40
41
                  libstring-shellquote-perl libsort-versions-perl \
                  libdigest-sha-perl libdata-uuid-perl libdata-dump-perl \
boklm's avatar
boklm committed
42
43
                  libfile-copy-recursive-perl libfile-slurp-perl git \
                  uidmap
boklm's avatar
boklm committed
44

45
46
47
48
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
49
50
51
52
53
54
55
The build uses user_namespaces(7), which are disabled by default on Debian.
To enable them you can use the following command as root:

  # sysctl -w kernel.unprivileged_userns_clone=1

You can enable them permanently by adding the setting to /etc/sysctl.d/

56
57
58
59
60
61
The user you use to build needs to have a range of subordinate uids and
gids in /etc/subuid and /etc/subgid. Most of the time they are added by
default when the user is created. If it was not the case, you can use
usermod(8) with the --add-subuids and --add-subgids options. See also
the subuid(5) and subgid(5) man pages.

boklm's avatar
boklm committed
62
63
64
65
66
67

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

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

boklm's avatar
boklm committed
69
70
71
72
73
74
  $ 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
75
nightly can be found in the nightly/$version directory.
boklm's avatar
boklm committed
76
77
78
79
80
81
82

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
83
  $ make nightly-windows-x86_64
boklm's avatar
boklm committed
84
  $ make nightly-osx-x86_64
85
  $ make nightly-android-armv7
86
  $ make nightly-android-aarch64
87
  $ make nightly-android-x86
88
  $ make nightly-android-x86_64
boklm's avatar
boklm committed
89

boklm's avatar
boklm committed
90
91
92
93
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
94
95
96
mar file will be created. If you want to base your testbuild on the latest
nightly code insted, rename rbm.local.conf.example to rbm.local.conf
and adapt the torbrowser-testbuild option accordingly.
boklm's avatar
boklm committed
97

boklm's avatar
boklm committed
98
99
100
101

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

102
You can run `make fetch` to fetch the latest sources from git for all
boklm's avatar
boklm committed
103
components included in Tor Browser. You should run this if you want to
104
105
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
106
107


108
109
110
111
112
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
113
set the RBM_NUM_PROCS environment variable:
114

115
  $ export RBM_NUM_PROCS=8
116

117
You can also set the buildconf/num_procs option in rbm.local.conf.
118
119


boklm's avatar
boklm committed
120
121
122
123
124
125
126
127
128
129
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

130
131
Or set the debug option to 0 in the rbm.local.conf file.

boklm's avatar
boklm committed
132
133
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
134
you want to build, and add the --output-dir option. For example, if you
boklm's avatar
boklm committed
135
136
want to build Tor Browser nightly for linux-x86_64:

137
   ./rbm/rbm build release --output-dir=/var/builds/nightly/2020-05-23 \
boklm's avatar
boklm committed
138
139
140
141
142
143
                        --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:

144
   ./rbm/rbm build release --output-dir=/var/builds/nightly/2020-05-23 \
boklm's avatar
boklm committed
145
146
147
148
149
150
151
152
                        --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
153
154
155
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
156
157


158
159
Using ansible to set up a nightly build machine
-----------------------------------------------
boklm's avatar
boklm committed
160

161
162
163
164
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
165
166


167
168
169
170
Signing builds
--------------

If the environment variable RBM_SIGN_BUILD is set to 1, the
171
172
173
174
175
sha256sums-unsigned-build.txt and sha256sums-unsigned-build.incrementals.txt
files will be signed with gpg. You can use the RBM_GPG_OPTS environment
variable to add some options 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.
176
177


boklm's avatar
boklm committed
178
179
180
Cleaning obsolete files and containers images
---------------------------------------------

181
You can run `make clean` to clean old build files and containers that
182
183
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
184
rbm.local.conf file. The cleaning script will check out all the configured
185
186
187
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
188
use `make clean-dry-run`.
boklm's avatar
boklm committed
189

190

191
192
193
194
195
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
196
be used to build the alpha version for e.g. android-armv7:
197
198
199
200
201
202
203
204
205
206

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

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
207
builds, and will require that you run Debian Buster and install build
208
209
210
dependencies for all the components that are built. This can be done
with the following command:

211
  # apt-get install build-essential python automake libtool zip unzip \
212
213
214
            autoconf2.13 openjdk-8-jdk gettext-base autotools-dev \
            automake autoconf libtool autopoint libssl-dev \
            pkg-config zlib1g-dev libparallel-forkmanager-perl \
215
            libfile-slurp-perl bzip2 xz-utils apksigner yasm
216
217


218
219
220
Common Build Errors
-------------------

221
You can look at the file doc/BUILD_ERRORS.txt for a list of common build
222
223
errors and their solutions.

boklm's avatar
boklm committed
224
225
226
227

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

228
The file doc/HACKING.txt tries to list the main things to know when
boklm's avatar
boklm committed
229
230
making changes to the Tor Browser build.

231

232
233
234
Description of makefile rules
-----------------------------

235
You can find a description of the Makefile rules in the file doc/MAKEFILE.txt.
236