1. Tor Browser Build
  2. =================
  3. Installing build dependencies
  4. -----------------------------
  5. To build Tor Browser, you need a Linux distribution that has support
  6. for runc (such as Debian Buster, Ubuntu 16.04, Fedora 30, etc ...).
  7. Your user account should have sudo access, which is required to be able
  8. to extract container file systems, start containers and copy files to and
  9. from containers.
  10. The sources of most components are downloaded using git, which needs to
  11. be installed. Some components are downloaded using mercurial which also
  12. needs to be installed.
  13. You also need a few perl modules installed:
  14. - YAML::XS
  15. - File::Basename
  16. - Getopt::Long
  17. - Template
  18. - IO::Handle
  19. - IO::CaptureOutput
  20. - JSON
  21. - File::Temp
  22. - Path::Tiny
  23. - File::Path
  24. - File::Slurp
  25. - File::Copy::Recursive
  26. - String::ShellQuote
  27. - Sort::Versions
  28. - Digest::SHA
  29. - Data::UUID
  30. - Data::Dump
  31. If you are running Debian or Ubuntu, you can install them with:
  32. # apt-get install libyaml-libyaml-perl libtemplate-perl \
  33. libio-handle-util-perl libio-all-perl \
  34. libio-captureoutput-perl libjson-perl libpath-tiny-perl \
  35. libstring-shellquote-perl libsort-versions-perl \
  36. libdigest-sha-perl libdata-uuid-perl libdata-dump-perl \
  37. libfile-copy-recursive-perl libfile-slurp-perl git runc \
  38. mercurial
  39. The build system is based on rbm, which is included as a git submodule
  40. in the rbm/ directory. You can fetch the rbm git submodule by running
  41. 'make submodule-update'.
  42. Starting a build
  43. ----------------
  44. To start a build, run one of the following commands, depending on the
  45. channel you want to build:
  46. $ make release
  47. $ make alpha
  48. $ make nightly
  49. You can find the build result in the directory release/unsigned/$version
  50. or alpha/unsigned/$version for release or alpha builds. The result of
  51. nightly can be found in the nightly/$version directory.
  52. If you want to build for a specific platform only, append the platform
  53. name to the makefile target:
  54. $ make nightly-linux-x86_64
  55. $ make nightly-linux-i686
  56. $ make nightly-linux-arm
  57. $ make nightly-windows-i686
  58. $ make nightly-windows-x86_64
  59. $ make nightly-osx-x86_64
  60. $ make nightly-android-armv7
  61. $ make nightly-android-aarch64
  62. $ make nightly-android-x86
  63. $ make nightly-android-x86_64
  64. When you want to quickly do a build to test a change, you can use the
  65. testbuild makefile target, and find the build in the testbuild directory.
  66. The build will be the same as regular alpha builds, except that in order
  67. to make the build faster, only the en-US locale will be built, and no
  68. mar file will be created. If you want to base your testbuild on the latest
  69. nightly code insted, rename rbm.local.conf.example to rbm.local.conf
  70. and adapt the torbrowser-testbuild option accordingly.
  71. Updating git sources
  72. --------------------
  73. You can run `make fetch` to fetch the latest sources from git for all
  74. components included in Tor Browser. You should run this if you want to
  75. make a nightly build with the latest commits, and you disabled automatic
  76. fetching of new commits for nightly builds in rbm.local.conf.
  77. Number of make processes
  78. ------------------------
  79. By default the builds are run with 4 processes simultaneously (with
  80. make -j4). If you want to change the number of processes used, you can
  81. set the RBM_NUM_PROCS environment variable:
  82. $ export RBM_NUM_PROCS=8
  83. You can also set the buildconf/num_procs option in rbm.local.conf.
  84. Automated builds
  85. ----------------
  86. If the build fails, a shell will automatically open in the build
  87. container to help you debug the problem. You probably want to disable
  88. this if you want to do automated builds. To disable this, set
  89. the RBM_NO_DEBUG environment variable to 1:
  90. export RBM_NO_DEBUG=1
  91. Or set the debug option to 0 in the rbm.local.conf file.
  92. If you want to select the output directory, you can use rbm's --output-dir
  93. option. You can look at the Makefile to find the rbm command for what
  94. you want to build, and add the --output-dir option. For example, if you
  95. want to build Tor Browser nightly for linux-x86_64:
  96. ./rbm/rbm build release --output-dir=/var/builds/nightly/2020-05-23 \
  97. --target nightly --target torbrowser-linux-x86_64
  98. The files will be put in the directory selected by --output-dir in a
  99. subdirectory named as the version number (or current date for nightly).
  100. To remove this version subdirectory, add the noversiondir target:
  101. ./rbm/rbm build release --output-dir=/var/builds/nightly/2020-05-23 \
  102. --target nightly --target torbrowser-linux-x86_64 \
  103. --target noversiondir
  104. Automated builds using tbb-testsuite
  105. ------------------------------------
  106. The Tor Browser testsuite scripts can also be used to do nightly builds
  107. and publish the build logs. The recommended way to do that is to use
  108. the ansible roles from the tools/ansible directory. See next section
  109. for details.
  110. Using ansible to set up a nightly build machine
  111. -----------------------------------------------
  112. The directory tools/ansible contains some ansible roles to set up a
  113. nightly build machine. You can look at the playbook defined in
  114. boklm-tbb-nightly-build.yml and variables in group_vars/boklm-tbb-nightly/
  115. for an example of how it can be used.
  116. Signing builds
  117. --------------
  118. If the environment variable RBM_SIGN_BUILD is set to 1, the
  119. sha256sums-unsigned-build.txt and sha256sums-unsigned-build.incrementals.txt
  120. files will be signed with gpg. You can use the RBM_GPG_OPTS environment
  121. variable to add some options to the gpg command used to sign the file.
  122. You can also set the var/sign_build and var/sign_build_gpg_opts options
  123. in the rbm.local.conf file.
  124. Cleaning obsolete files and containers images
  125. ---------------------------------------------
  126. You can run `make clean` to clean old build files and containers that
  127. are no longer used in current builds. Before doing that, you need to
  128. configure the branches and build targets you are using in the
  129. rbm.local.conf file. The cleaning script will check out all the configured
  130. branches to create a list of used build files, and delete the files
  131. from the 'out' directory that are not used. If you want to see the list
  132. of files and containers that would be removed without doing it, you can
  133. use `make clean-dry-run`.
  134. Building without containers (Android builds only)
  135. -------------------------------------------------
  136. By default the build is done inside containers. Adding the no_containers
  137. target will disable the use of containers. The following commands can
  138. be used to build the alpha version for e.g. android-armv7:
  139. ./rbm/rbm build release --target no_containers --target testbuild \
  140. --target torbrowser-android-armv7
  141. Note: the logs will still show the use and creation of a container image
  142. called "containers_disabled". This is due to the way we disable the use
  143. of containers: the container-image project is still called, but it will
  144. just create an empty file instead of a real container image.
  145. The build without containers is currently only supported for the Android
  146. builds, and will require that you run Debian Stretch and install build
  147. dependencies for all the components that are built. This can be done
  148. with the following command:
  149. # apt-get install build-essential python automake libtool zip unzip \
  150. autoconf2.13 openjdk-8-jdk gettext-base autotools-dev \
  151. automake autoconf libtool autopoint libssl-dev \
  152. pkg-config zlib1g-dev libparallel-forkmanager-perl \
  153. libfile-slurp-perl bzip2 xz-utils apksigner yasm
  154. Common Build Errors
  155. -------------------
  156. You can look at the README.BUILD_ERRORS file for a list of common build
  157. errors and their solutions.
  158. Hacking on the Tor Browser build
  159. --------------------------------
  160. The file README.HACKING tries to list the main things to know when
  161. making changes to the Tor Browser build.
  162. Description of makefile rules
  163. -----------------------------
  164. You can find a description of the Makefile rules in the README.MAKEFILE
  165. file.