TorBrowserHackingTheNextGeneration

Here are my notes on building Tor Browser yourself.

 _____ ____  _____ _____   _____ _   _ _____ 
|  ___|  _ \| ____| ____| |_   _| | | | ____|
| |_  | |_) |  _| |  _|     | | | |_| |  _|  
|  _| |  _ <| |___| |___    | | |  _  | |___ 
|_|   |_| \_\_____|_____|   |_| |_| |_|_____|
                                             
 _     ___ _____   _    ____  ____  
| |   |_ _|__  /  / \  |  _ \|  _ \ 
| |    | |  / /  / _ \ | |_) | | | |
| |___ | | / /_ / ___ \|  _ <| |_| |
|_____|___/____/_/   \_\_| \_\____/ 
                                    

(The joke is from early Netscape days: https://en.wikipedia.org/wiki/Netscape). The previous instructions, which were a useful foundation for the ones given here, are here.

Background

Running Debian 10 (buster) on a VPS (I used DigitalOcean for this one). The available memory is important: 16 GB is necessary to build. Below I sometimes do things "in a hurry" by piping curl into a shell, which is Not Good Practice. You should download those scripts, look at them (or ask someone else to look at them, or both), and when satisfied, run them.

Getting the code

• [~10 min] Get the Tor Browser code

  git clone https://git.torproject.org/tor-browser.git
  cd tor-browser

• Checkout a branch. Do

  git branch -a

  to see the branches. For example, in May 2021, you could checkout the branch associated with the most recent build (tagged as tor-browser-88.0.1-10.5-1-build1) with

  git checkout remotes/origin/tor-browser-88.0.1-10.5-1

Satisfying dependencies prior to build

• [~15 min] Install stuff we'll need in one fell swoop:

  sudo apt install --no-install-suggests  --no-install-recommends \
      unzip \
      libglib2.0-dev \
      libgconf2-dev \
      libgtk2.0-dev \
      libgtk-3-dev \
      libdbus-1-dev \
      libdbus-glib-1-dev \
      yasm \
      libasound2-dev \
      libcurl4-openssl-dev \
      libxt-dev \
      mesa-common-dev \
      autoconf \
      autoconf2.13 \
      libtool \
      libgstreamer-plugins-base1.0-dev \   
      pkg-config \
      g++ \
      libpulse-dev \
      gnupg \
      curl \
      make \
      software-properties-common \
      zip \
      apt-transport-https

Clone tor-launcher and copy it into place

  cd ..  # get to the parent of the tor-browser directory
  
  git clone https://git.torproject.org/tor-launcher

  cp -r tor-launcher tor-browser/browser/extensions/

If you want to hack on tor-launcher, you should do that separately in the cloned tor-launcher project (not in the copy in browser/extensions). Just be sure to copy over the right version each time you build.

Clone torbutton, and move it into place

  # again return to the parent of the tor-browser and tor-launcher directories. cd as needed.

  git clone https://git.torproject.org/torbutton

  cp -r torbutton tor-browser/browser/extensions/

Satisfying Mach

• set up virtualenv

  cd tor-browser  # adjust as needed to enter the project you cloned above.  
  ./mach create-mach-environment

• install cbindgen. First install rustup via the following (note: apt installing rustc and cargo fails!)

      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

then do

      cargo install cbindgen

• install clang toolchain (oi)

    bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
  * symlink clang: 
     ln -s $(which clang-10) /usr/bin/clang
  * symlink clang++: 
     ln -s $(which clang++-10) /usr/bin/clang++
  * symlink llvm: 
     ln -s $(which llvm-config-10) /usr/bin/llvm

• install nodejs 8.11 or newer

    curl -sL https://deb.nodesource.com/setup_lts.x | bash -
    apt install nodejs

• install nasm 2.14 (or better, but we go for the min):

    wget https://www.nasm.us/pub/nasm/releasebuilds/2.14/nasm-2.14.tar.xz
    tar xvf nasm-2.14.tar.xz; cd nasm-2.14

• open the Makefile in the nasm directory with a text editor, remove -Werror=attributes, save, then

    configure; make; make install

Make your modifications

• [∞] Hack away!

Generating configure, compiling and packaging

• [~30 min] generate configuration

  ./mach configure \
     --with-tor-browser-version=tbb-nightly \
     --with-distribution-id=org.torproject \
     --enable-update-channel=default \
     --enable-bundled-fonts

• Build

  ./mach build

• Package

  ./mach build stage-package

Getting an existing TBB to serve as a base

• create the base directory for the tor browser bundle (TBB) that we'll use as a base

    cd $HOME; mkdir tbb-to-copy-over; cd $_

• get the TBB; expand it

    wget https://www.torproject.org/dist/torbrowser/10.0a6/tor-browser-linux64-10.0a6_en-US.tar.xz
    tar xvf tor-browser-linux64-10.0a6_en-US.tar.xz

• set an environment variable to make next steps easier

    export INSTDIR="$HOME/tbb-to-copy-over/tor-browser_en-US"

• Copy custom stuff onto this base

    cp -a obj-*/dist/firefox/* $INSTDIR/Browser/

Make things smaller to aid transfer

• Remove symbols from the object files

    strip --strip-all $INSTDIR/Browser/*

• Remove unnecessary bits

    rm -f $INSTDIR/Browser/firefox-bin

Get the goodz on your local machine

Last, use rsync or whatever to get tbb-to-copy-over onto your local machine

    rsync -avz --progress name-of-the-tor-build-server-you-set-up:tbb-to-copy-over .