Fork of upstream Tor's repo. You should probably be using upstream.

JeremyRand bcd0e21237 (WIP) ncdns / linux-cross: Fix libcap dependency 4 years ago
keyring bd21fef218 Bug 32992: TBB Project for LZMA 4 years ago
projects bcd0e21237 (WIP) ncdns / linux-cross: Fix libcap dependency 4 years ago
rbm @ 5f8c0ac72a ea9ec4f818 Pick up rbm changes for #33993 4 years ago
tools 895efbcd31 Move mcs and brade to alumns build machine-wise 4 years ago
.gitignore 07ffaa9144 Bug 25099: Remove the alpha_nightly target 4 years ago
.gitmodules 0ff4bb1275 Update rbm submodule url 7 years ago
ChangeLog.txt 905f80c552 Add ChangeLog.txt symlink 7 years ago
LICENSE 49319fa1af Bug 32038: Add a LICENSE file 4 years ago
Makefile 91613c8785 Makefile: Add linux-arm target 4 years ago
README 91613c8785 Makefile: Add linux-arm target 4 years ago
README.BUILD_ERRORS 2b2e744357 Bug 26773: Add another build error FAQ 6 years ago
README.HACKING f89da2a9b0 Bug 31192 - Add Android x86_64 build support 4 years ago
README.MAKEFILE d4460a9265 Bug 25101: Add support for generating nightly incremental mars 4 years ago
rbm.conf 9a27221524 rbm.conf: Add linux-arm target 4 years ago
rbm.local.conf.example adf23abdce Bug 32751: Sign incrementals sha256sums too if var/sign_build is set 4 years ago


Tor Browser Build

Installing build dependencies

To build Tor Browser, you need a Linux distribution that has support
for runc (such as Debian Buster, Ubuntu 16.04, Fedora 30, etc ...).

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.

The sources of most components are downloaded using git, which needs to
be installed. Some components are downloaded using mercurial which also
needs to be installed.

You also need a few perl modules installed:
- File::Basename
- Getopt::Long
- Template
- IO::Handle
- IO::CaptureOutput
- File::Temp
- Path::Tiny
- File::Path
- File::Slurp
- File::Copy::Recursive
- 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 libjson-perl libpath-tiny-perl \
libstring-shellquote-perl libsort-versions-perl \
libdigest-sha-perl libdata-uuid-perl libdata-dump-perl \
libfile-copy-recursive-perl libfile-slurp-perl git runc \

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'.

Starting a build

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

$ 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
nightly can be found in the nightly/$version 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-linux-arm
$ make nightly-windows-i686
$ make nightly-windows-x86_64
$ make nightly-osx-x86_64
$ make nightly-android-armv7
$ make nightly-android-aarch64
$ make nightly-android-x86
$ make nightly-android-x86_64

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. 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.

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, and you disabled automatic
fetching of new commits for nightly builds in rbm.local.conf.

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
set the RBM_NUM_PROCS environment variable:

$ export RBM_NUM_PROCS=8

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

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

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

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/2020-05-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/2020-05-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. The recommended way to do that is to use
the ansible roles from the tools/ansible directory. See next section
for details.

Using ansible to set up a nightly build machine

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.

Signing builds

If the environment variable RBM_SIGN_BUILD is set to 1, the
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.

Cleaning obsolete files and containers images

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
rbm.local.conf file. The cleaning script will check out all the configured
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`.

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 e.g. android-armv7:

./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
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 \
libfile-slurp-perl bzip2 xz-utils apksigner yasm

Common Build Errors

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

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.

Description of makefile rules

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