README 6.57 KB
Newer Older
boklm's avatar
boklm committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
Tor Browser Build
=================

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

To build Tor Browser, you need a Linux distribution that has support
for Docker (such as Debian jessie, Ubuntu 14.04, Fedora 20, etc ...).
The Docker package is usually named docker.io or docker-io.
On Debian jessie, the docker.io package is available in backports.

Your user account should have access to the docker command without using
sudo, so it should be in the docker group. The docker daemon should
also be running.

The sources are downloaded using git which needs to be installed.

You also need a few perl modules installed:
- YAML::XS
- File::Basename
- Getopt::Long
- Template
- IO::Handle
- IO::CaptureOutput
- File::Temp
- File::Slurp
- File::Path
- 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 \
                  libio-captureoutput-perl libfile-slurp-perl \
                  libstring-shellquote-perl libsort-versions-perl \
                  libdigest-sha-perl libdata-uuid-perl libdata-dump-perl \
                  git


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

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

boklm's avatar
boklm committed
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
  $ make release
  $ make alpha
  $ make nightly
  $ make alpha_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
nightly or alpha_nightly can be found in the nightly/$date or
alpha_nightly/$date directory.

The alpha and alpha_nightly make target will build the same thing. The
only difference is the output directory. The alpha_nightly target can be
useful if you want to do a test build without polluting your alpha
directory.

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

boklm's avatar
boklm committed
73
74
75
76
77
78
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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

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
make a nightly build with the latest commits.


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

98
99
Or set the debug option to 0 in the rbm.local.conf file.

boklm's avatar
boklm committed
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
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
you want to build, and add the --output-dir option. For example if you
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
and publish the build logs.

If you want to do that, start by cloning the git repository:

   $ git clone https://git.torproject.org/boklm/tor-browser-bundle-testsuite.git

Install some dependencies:

   # apt-get install -y libdata-dump-perl libfile-slurp-perl \
               libio-captureoutput-perl perlmagick libjson-perl \
               libwww-perl liblwp-protocol-https-perl libtemplate-perl \
               libyaml-syck-perl libdatetime-perl \
               libemail-sender-perl libemail-simple-perl libfile-type-perl \
               libipc-run-perl libxml-libxml-perl

Copy the config/tor-browser_build-boklm file and edit it:

   $ cd tor-browser-bundle-testsuite
   $ cp config/tor-browser_build-boklm config/tor-browser_build-$user
   $ vim config/tor-browser_build-$user

Change the publish_dir and publish_url options. The publish_dir option is
the local directory where the builds will be stored. The publish_url
option is the public URL where the builds will be available.

Copy the tools/tor-browser-builds-boklm file and edit it to change the
--config= option:

   $ cp tools/tor-browser-builds-boklm tools/tor-browser-builds-$user
   $ vim tools/tor-browser-builds-$user

You can now run ./tools/tor-browser-builds-$user to start the build, and
add it to you crontab.

The html build reports will be available in the reports/ directory, and
the build files in the tor-browser-builds/ directory (unless you changed
the publish_dir option).


160
161
162
163
164
165
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
166
167
168
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.
169
170


boklm's avatar
boklm committed
171
172
173
174
175
176
Cleaning obsolete files and containers images
---------------------------------------------

There will be a script to clean old build files and containers that are
no longer used, but it has not been added yet.

177

178
179
180
181
182
183
184
185
186
187
188
189
Multiple build directories on the same host
-------------------------------------------

You can do multiple builds of Tor Browser in different directories on
the same host. However the docker images namespace is global, so you
may have some conflicts with the same image names used by the
different builds. By default, the docker images are prefixed with
tor-browser_$USER. You can change this prefix by defining the
docker_image_prefix option in rbm.local.conf, using a different prefix
for each of your build directories.


190
191
192
193
194
195
Common Build Errors
-------------------

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