README 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203
  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 jessie, Ubuntu 16.04, Fedora 20, etc ...).
  7. On Debian jessie, the runc package is available in backports. On Debian
  8. stretch, the runc package is available in the main repository.
  9. Your user account should have sudo access, which is required to be able
  10. to extract container file systems, start containers and copy files to and
  11. from containers.
  12. The sources of most components are downloaded using git, which needs to
  13. be installed. Some components are downloaded using mercurial which also
  14. needs to be installed. The sources of webrtc are downloaded using
  15. gclient, which requires GTK+ 2.0 development files and curl to be
  16. installed.
  17. You also need a few perl modules installed:
  18. - YAML::XS
  19. - File::Basename
  20. - Getopt::Long
  21. - Template
  22. - IO::Handle
  23. - IO::CaptureOutput
  24. - JSON
  25. - File::Temp
  26. - Path::Tiny
  27. - File::Path
  28. - File::Copy::Recursive
  29. - String::ShellQuote
  30. - Sort::Versions
  31. - Digest::SHA
  32. - Data::UUID
  33. - Data::Dump
  34. If you are running Debian or Ubuntu, you can install them with:
  35. # apt-get install libyaml-libyaml-perl libtemplate-perl \
  36. libio-handle-util-perl libio-all-perl \
  37. libio-captureoutput-perl libjson-perl libpath-tiny-perl \
  38. libstring-shellquote-perl libsort-versions-perl \
  39. libdigest-sha-perl libdata-uuid-perl libdata-dump-perl \
  40. libfile-copy-recursive-perl git libgtk2.0-dev curl runc \
  41. mercurial
  42. The build system is based on rbm, which is included as a git submodule
  43. in the rbm/ directory. You can fetch the rbm git submodule by running
  44. 'make submodule-update'.
  45. Starting a build
  46. ----------------
  47. To start a build, run one of the following commands, depending on the
  48. channel you want to build:
  49. $ make release
  50. $ make alpha
  51. $ make nightly
  52. $ make alpha_nightly
  53. You can find the build result in the directory release/unsigned/$version
  54. or alpha/unsigned/$version for release or alpha builds. The result of
  55. nightly or alpha_nightly can be found in the nightly/$date or
  56. alpha_nightly/$date directory.
  57. The alpha and alpha_nightly make target will build the same thing. The
  58. only difference is the output directory. The alpha_nightly target can be
  59. useful if you want to do a test build without polluting your alpha
  60. directory.
  61. If you want to build for a specific platform only, append the platform
  62. name to the makefile target:
  63. $ make nightly-linux-x86_64
  64. $ make nightly-linux-i686
  65. $ make nightly-windows-i686
  66. $ make nightly-osx-x86_64
  67. $ make nightly-android-armv7
  68. When you want to quickly do a build to test a change, you can use the
  69. testbuild makefile target, and find the build in the testbuild directory.
  70. The build will be the same as regular alpha builds, except that in order
  71. to make the build faster, only the en-US locale will be built, and no
  72. mar file will be created.
  73. Updating git sources
  74. --------------------
  75. You can run "make fetch" to fetch the latest sources from git for all
  76. components included in Tor Browser. You should run this if you want to
  77. make a nightly build with the latest commits, and you disabled automatic
  78. fetching of new commits for nightly builds in rbm.local.conf.
  79. Number of make processes
  80. ------------------------
  81. By default the builds are run with 4 processes simultaneously (with
  82. make -j4). If you want to change the number of processes used, you can
  83. set the RBM_NUM_PROCS environment variable:
  84. $ export RBM_NUM_PROCS=8
  85. You can also set the buildconf/num_procs option in rbm.local.conf.
  86. Automated builds
  87. ----------------
  88. If the build fails, a shell will automatically open in the build
  89. container to help you debug the problem. You probably want to disable
  90. this if you want to do automated builds. To disable this, set
  91. the RBM_NO_DEBUG environment variable to 1:
  92. export RBM_NO_DEBUG=1
  93. Or set the debug option to 0 in the rbm.local.conf file.
  94. If you want to select the output directory, you can use rbm's --output-dir
  95. option. You can look at the Makefile to find the rbm command for what
  96. you want to build, and add the --output-dir option. For example, if you
  97. want to build Tor Browser nightly for linux-x86_64:
  98. ./rbm/rbm build release --output-dir=/var/builds/nightly/2017-01-23 \
  99. --target nightly --target torbrowser-linux-x86_64
  100. The files will be put in the directory selected by --output-dir in a
  101. subdirectory named as the version number (or current date for nightly).
  102. To remove this version subdirectory, add the noversiondir target:
  103. ./rbm/rbm build release --output-dir=/var/builds/nightly/2017-01-23 \
  104. --target nightly --target torbrowser-linux-x86_64 \
  105. --target noversiondir
  106. Automated builds using tbb-testsuite
  107. ------------------------------------
  108. The Tor Browser testsuite scripts can also be used to do nightly builds
  109. and publish the build logs. The recommended way to do that is to use
  110. the ansible roles from the tools/ansible directory. See next section
  111. for details.
  112. Using ansible to set up a nightly build machine
  113. -----------------------------------------------
  114. The directory tools/ansible contains some ansible roles to set up a
  115. nightly build machine. You can look at the playbook defined in
  116. boklm-tbb-nightly-build.yml and variables in group_vars/boklm-tbb-nightly/
  117. for an example of how it can be used.
  118. Signing builds
  119. --------------
  120. If the environment variable RBM_SIGN_BUILD is set to 1, the
  121. sha256sums-unsigned-build.txt file will be signed with gpg.
  122. You can use the RBM_GPG_OPTS environment variable to add some options
  123. to the gpg command used to sign the file. You can also set the
  124. var/sign_build and var/sign_build_gpg_opts options in the rbm.local.conf
  125. file.
  126. Cleaning obsolete files and containers images
  127. ---------------------------------------------
  128. You can run 'make clean' to clean old build files and containers that
  129. are no longer used in current builds. Before doing that, you need to
  130. configure the branches and build targets you are using in the
  131. rbm.local.conf file. The cleaning script will check out all the configured
  132. branches to create a list of used build files, and delete the files
  133. from the 'out' directory that are not used. If you want to see the list
  134. of files and containers that would be removed without doing it, you can
  135. use 'make clean-dry-run'.
  136. Common Build Errors
  137. -------------------
  138. You can look at the README.BUILD_ERRORS file for a list of common build
  139. errors and their solutions.
  140. Hacking on the Tor Browser build
  141. --------------------------------
  142. The file README.HACKING tries to list the main things to know when
  143. making changes to the Tor Browser build.
  144. Description of makefile rules
  145. -----------------------------
  146. You can find a description of the makefile rules in the README.MAKEFILE
  147. file.