Add blueprint.

[tails-test.git] / wiki / src / contribute / build.mdwn

[[!meta title="Building a Tails image"]]

[[!toc levels=2]]

<a id="vagrant"></a>

Using Vagrant
=============

Tails can be built easily in a virtual machine using [Rake], [Vagrant] and
[VirtualBox]. The process requires a minimum of 1 GB of free memory and a
maximum of 10 GB of free storage.

[Rake]: http://rake.rubyforge.org/
[Vagrant]: http://vagrantup.com/
[VirtualBox]: http://www.virtualbox.org/

Set up the build environment on Debian Jessie:

1. Add Debian unstable to your APT sources.
2. Pin all packages from Debian unstable at 500 (`apt_preferences(5)`).
3. Install the needed tools:

       $ sudo apt-get install git virtualbox rake vagrant/unstable

Or, on Debian Wheezy:

1. Add Debian Jessie and unstable to your APT sources.
2. Pin all packages from Debian Jessie and unstable at 500 (`apt_preferences(5)`).
3. Install the needed tools:

       $ sudo apt-get install git virtualbox rake vagrant/unstable \
         ruby-childprocess/jessie ruby-net-scp/jessie ruby-net-ssh/jessie

Then, please run:

    $ git clone git://git.tails.boum.org/tails
    $ cd tails
    $ git checkout devel
    $ export TAILS_BUILD_OPTIONS="noproxy"
    $ rake build
    $ unset TAILS_BUILD_OPTIONS

The first time, this can take a little while to download the base virtual
machine from Tails mirror (around 300 MB). It will then boot the machine,
set it up and start the build process. When done, several `tails-*` files
should appear in the current directory.

After you are done working on Tails, do not forget to shut the virtual
machine down:

    $ rake vm:halt

One may also want to [[contribute/customize]] their image before building.

To know all available Rake tasks, please run `rake -T`.

Local HTTP proxy
----------------

If you have a local HTTP proxy, the build system will use it as long as
you properly set the `http_proxy` environment variable. The easiest way to
do so is to run:

    $ export http_proxy=http://proxy.lan:3142

This needs to be done before any other operations.

Build options
-------------

Options regarding the build process can be set using the
`TAILS_BUILD_OPTIONS` environment variable. Muliple options must be
separated by whitespaces.

The following options are available:

### Memory build settings

Tails builds way faster when everything is done in memory. If your computer
runs Linux and happens to have more than 6.5 GB of free memory before you
start the virtual machine, it will automatically switch to 'build in RAM'
mode.

To force a specific behaviour please set:

 * **ram**: start the virtual machine with 6.5GB of memory, build Tails
   inside a `tmpfs`. Build fails if the system is not in a proper state to
   do so.
 * **noram**: start the virtual machine with 1GB of memory if not already
   done, build Tails using the virtual machine hard disk.

### HTTP proxy settings

Building Tails requires downloading a little bit more than 1 GB of Debian
packages. To preserve bandwidth and developer sanity, using a HTTP proxy is
nearly a must. Tails virtual machine contains a fully configured local HTTP
proxy that will be used if no other local proxy is defined.

The following flags can be used to force a specific behaviour:

 * **extproxy**: use the proxy configured through the `http_proxy`
   environment variable. Fail if it is not set.
 * **vmproxy**: use the local proxy configured in the virtual machine even
   if a local HTTP proxy is set.
 * **noproxy**: do not use any HTTP proxy.

### Bootstrap cache settings

A Tails build starts with `debootstrap`:ing a minimal Debian system
which then is modified into a full Tails system. This is a rather time
consuming step that usually does not have to be done: the packages used
in it rarely get updated and hence the result is exactly the same most
of the time.

The following flags can be used to force a specific behaviour:

 * **cache**: re-use a cached bootstrap stage (if available), and saves
   the bootstrap stage to disk on successful build. This will also
   reduce the amount of memory required for in-memory builds by around
   150 MiB (see the **ram** option above). **Warning:** this option may
   create subtle differences between builds from the exact same Tails
   source which are hard to track to track and understand. Use this
   option only if you know what you are doing, and if you are not
   building an actual release.
 * **nocache**: do the bootstrap stage from scratch (default).

### SquashFS compression settings

One of the most expensive operations when building Tails is the creation
of the final SquashFS. It also depends on the compression algorithm used.
When working on the `stable` or `testing` branch, the image will be made
using the slow but efficient default. Any other setup will switch to the
faster *gzip*.

Forcing a specific behaviour can be done using:

 * **gzipcomp**: always use *gzip* to create the SquashFS.
 * **defaultcomp**: always use the default compression algorithm.

### Clean-up settings

Some operations are preserved accross builds. Currently they are:

* The wiki (for documentation).
* The bootstrap stage cache (see the **cache** option above).

In case you want to delete all these, the following option is available:

 * **cleanall**: force a clean up before starting the build.

### Virtual CPUs settings

The number of virtual CPUs that are allocated in the virtual machine can be set
through:

 * **cpus=_n_**: allocate _n_ CPUs to the virtual machine.

Obviously you should not allocate more virtual CPUs than the number of cores
available to the host system. When using Linux, the number of CPUs allocated
will default to be the same as the host system.

### Git settings

The build system can only work on files that have been *commited* to the Git
repository. By default, it will refuse to start a build in presence of
uncommited changes. This behaviour can be controlled by:

 * **ignorechanges**: allow to make a build that will ignore changes in the Git
   repository.

### Example

The fastest build you could pretend to get can be done by setting:

    export TAILS_BUILD_OPTIONS="ram cache extproxy gzipcomp"

This will force the build to happen in RAM and allow skipping the
boostrap stage if one is cached, and will use use an HTTP proxy
external to the virtual machine, and SquashFS compression will be done
using *gzip*.

<a id="manual"></a>

Building manually
=================

In order to build Tails manually, you need a running [Debian
Wheezy](https://www.debian.org/releases/wheezy/) system
and some [backports](http://backports.debian.org/). Anything else
will fail.

Dependencies
------------

The following Debian packages need to be installed:

* our `live-build` 2.x package, adapted for Wheezy. Its version is
  something like *3.0.5+really+is+2.0.12-0.tails1*. One can install it
  from:

      deb http://deb.tails.boum.org/ builder-wheezy main

  This APT repository's signing key can be found on the keyservers.
  It is certified by the [[!tails_website tails-signing.key
  desc="Tails signing key"]], and its fingerprint is:

      221F 9A3C 6FA3 E09E 182E  060B C798 8EA7 A358 D82E

* `syslinux`
* `eatmydata`, `time` and `whois` (for `/usr/bin/mkpasswd`)
* `ikiwiki` 3.20120725 or newer, available in wheezy-backports.
* `apt-get install libyaml-perl libyaml-libyaml-perl po4a perlmagick
  libyaml-syck-perl` so that the wiki builds smoothly.
* `dpkg-dev`
* `intltool`

Configure live-build
--------------------

Add these lines to `/etc/live/build.conf`:

        LB_PARENT_MIRROR_BINARY="http://ftp.us.debian.org/debian/"
        LB_MIRROR_BINARY="http://ftp.us.debian.org/debian/"

Build process
-------------

Every build command must be run as `root`, at the root of a clone of the
[[`tails` repository|git]].

In short, a build shall be done using:

    # lb clean --all && lb config && lb build

Running `lb config` or `lb build` in an environment that wasn't full
cleaned first is not supported.

### Customize the build process if needed

If you need to set custom build settings that are specific to your
local environment, such as a custom Debian mirror or APT proxy, you
probably want to configure live-build a bit.

The most common customizations are documented on this wiki:

* to avoid compressing the SquashFS using XZ (efficient, but very
  slow), `export MKSQUASHFS_OPTIONS='-comp gzip'` in your
  build environment;
* [[using a custom Debian mirror to build Tails
  images|build/custom_mirror]];
* [[using squid-deb-proxy to build Tails images|build/squid-deb-proxy]]
  (**Note**: most Tails contributors using the manual build method
  use [[!debpts apt-cacher-ng]] instead, nowadays.)

More documentation about this can be found in the [Debian Live
Manual](http://live.debian.net/manual-2.x/html/live-manual.en.html).

More information
================

More documentation about the build process can be found in the [Debian
Live Manual](http://live.debian.net/manual/oldstable/html/live-manual.en.html).

Related pages
=============

[[!map pages="contribute/build/*"]]