Add a README.HACKING file

Add a file to list the main things to know when making changes to the
Tor Browser build.

README

@@ -205,3 +205,10 @@ 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.
+

README.HACKING

+Hacking on Tor Browser Build
+============================
+
+This file tries to list the main things to know when making changes to
+the Tor Browser build.
+
+
+rbm documentation
+-----------------
+
+If you go to directory rbm/doc, you can find the rbm documentation. You
+can build it with 'make html' or 'make man'.
+
+
+Using and defining options
+--------------------------
+
+Options can be used in templates with the following syntax:
+
+  [% c("option_name") %]
+
+More details about the templates syntax can be found in
+rbm/doc/rbm_templates.7 and [http://template-toolkit.org/docs/manual/index.html].
+
+Some options have a specific meaning to rbm. You can see their descriptions
+in rbm/doc/rbm_config.7 and rbm/doc/rbm_input_files.7.
+
+When the option does not have a specific meaning to rbm, it is a good
+idea to define it under var/ to avoid potential conflicts in option names
+with a future version of rbm.
+
+The options can be defined in different places:
+
+- rbm.conf for options available to all components
+- project/$project/config for options available to one component
+- rbm.local.conf for user defined options
+
+In each of those places, an option can be defined:
+
+- at the root of the document
+- under targets/$target/, in which case the definition only applies when
+  a specific target is defined
+
+The targets are usually used to select:
+
+- the platform: torbrowser-linux-x86_64, torbrowser-linux-i686,
+  torbrowser-windows-i686, torbrowser-osx-x86_64
+- the channel: release, nightly, alpha
+
+The targets torbrowser-linux-x86_64, torbrowser-linux-i686,
+torbrowser-windows-i686, torbrowser-osx-x86_64 are special cases. They
+do not contain options directly, instead they contain a list of other
+targets. For instance, the torbrowser-linux-x86_64 target is pointing
+to the linux-x86_64 and linux targets. You should define an option under
+the linux target if it applies to Linux on both architectures, or under
+the linux-x86_64 if it only applies to the x86_64 architecture.
+
+An option that is defined at the root of rbm.conf can be overrided by
+an other definition under a target, or inside projects/$project/config.
+You can find the complete priority order in rbm/doc/rbm_config.7.
+
+
+Defining a project's filename
+-----------------------------
+
+The filename option defines the output file or directory from the build
+of a component. If the file or directory exists in the out/$component
+directory, the component will not be rebuilt when it is used as a
+dependency from an other component.
+
+The filename is usually something like this:
+
+  filename: '[% project %]-[% c("version") %]-[% c("var/osname") %]-[% c("var/build_id") %].tar.gz'
+
+The var/build_id value is a hash that is based on the build inputs of
+the component:
+ - the build script (after template evaluation)
+ - the container definition
+ - the input files (the filename when it is a dependency on an other
+   project, the filename and hash of its content otherwise)
+This means that each time the build script, the container or one of the
+dependencies is modified, the output filename will change and a rebuild
+of the component will be required.
+
+The version and var/osname values could be removed from the filename,
+but they are useful to get an idea of what a file contains.
+
+
+Adding some Linux/Windows/OSX specific changes to a build script
+----------------------------------------------------------------
+
+You can use the following template syntax in the build scripts:
+
+  [% IF c("var/linux") -%]
+    # do something for linux
+  [% ELSIF c("var/windows") -%]
+    # do something for windows
+  [% ELSIF c("var/osx") -%]
+    # do something for osx
+  [% END -%]
+
+You can also use var/linux-x86_64 and var/linux-i686 for things that
+only apply to x86_64 and i686 linux builds. You can use the var/release,
+var/alpha and var/nightly options to do things depending on the channel.
+
+As an alternative you can define an option with a different value
+depending on the target:
+
+  targets:
+    linux:
+      var:
+        do_something: 'do something for linux'
+    windows-i686:
+      var:
+        do_something: 'do something for windows'
+    osx-x86_64:
+      var:
+        do_something: 'do something for osx'
+
+And in the build script, use:
+
+  [% c("var/do_something") %]
+
+
+Evaluating a component's build script
+-------------------------------------
+
+If you want to look at the build script used to build a component for a
+specific platform/channel, you can use the following command:
+
+   $ ./rbm/rbm showconf $component build --target $channel --target $platform
+
+$component should be replaced by the name of the component.
+
+$channel should be one of the following:
+
+ - release
+
+ - alpha
+
+ - nightly
+
+$platform should be one of the following:
+
+ - torbrowser-linux-x86_64
+
+ - torbrowser-linux-i686
+
+ - torbrowser-windows-i686
+
+ - torbrowser-osx-x86_64
+
+For example, to see the tor's build script for linux x86_64 on the alpha
+channel, you can use:
+
+  $ ./rbm/rbm showconf tor build --target alpha --target \
+    torbrowser-linux-x86_64
+
+If the component you are looking at has many dependencies, the display
+can take some time as various build_id values need to be computed. If
+you don't care about the accuracy of input and output file names, you
+can add '--target no_build_id' to the command line. For instance if you
+want to look at the build script for the tor-browser component (which
+has a lot of dependencies), you can use:
+
+  $ ./rbm/rbm showconf tor build --target alpha --target \
+     torbrowser-linux-x86_64 --target no_build_id
+
+The same type of commands can be used to look at any option values,
+replacing build with the name of the option you want to look at. For
+instance if you want to know the output filename of tor on linux-x86_64
+on the alpha channel, you can use:
+
+  $ ./rbm/rbm showconf tor filename --target alpha --target \
+    torbrowser-linux-x86_64
+
+
+Building a single component
+---------------------------
+
+When you are working on some changes to a component, before creating a
+full bundle with those changes, you might want to try a build of the
+component you modified only.
+
+This can be done with the following command:
+
+   $ ./rbm/rbm build $component --target $channel --target $platform
+
+See the previous section "Evaluating a component's build script" for a
+list of possible values for $channel and $platform.
+
+For instance if you want to build tor for linux-x86_64 on the alpha
+channel, you can run:
+
+   $ ./rbm/rbm build tor --target alpha --target torbrowser-linux-x86_64
+
+To find the resulting file from the build, you can use 'ls -ltr out/tor/'
+to find the file with the last modification time.
+
+
+Debugging a build error
+-----------------------
+
+If the build fails, a debugging shell will automatically be opened in
+the container used for the build (unless you set debug to 0 in
+rbm.local.conf).
+
+Before using the debugging shell, you can first look at the build logs
+in an other terminal (the filename of the log file is indicated in the
+rbm output).
+
+In the debug shell, you can type 'bash' to get a shell with completion.
+You can then look at the 'build' file, and copy paste some of its commands
+to debug the problem. If you need to edit files, vim is not installed
+in the build containers, but vi can be used instead.
+
+When you press ctrl+d (twice if you opened a bash shell) the debug shell
+is closed and the container containing the failed build is removed.
+
+If you want to make a backup of the container's rootfs with the failed
+build to look at it later, you should be able to find it in
+/tmp/$UID/rbm-containers.
+