mirror of https://github.com/HandBrake/HandBrake
597 lines
17 KiB
Plaintext
597 lines
17 KiB
Plaintext
Guide to Building HandBrake svn5208 (2013012701) on Linux
|
|
*********************************************************
|
|
|
|
Table of Contents
|
|
*****************
|
|
|
|
1 Introduction
|
|
2 Prerequisites
|
|
3 QuickStart
|
|
4 Overview
|
|
5 Building via Terminal
|
|
5.1 Checkout Sources
|
|
5.2 Configure
|
|
5.3 Build
|
|
5.4 Make Targets
|
|
5.4.1 Global
|
|
5.4.2 General Modules
|
|
5.4.3 Contrib Modules
|
|
5.4.4 Contrib Touch and Untouch
|
|
5.4.5 Contrib Aggregates
|
|
5.5 Customizing Make
|
|
6 Troubleshooting
|
|
Appendix A Project Repository Details
|
|
|
|
|
|
1 Introduction
|
|
**************
|
|
|
|
This guide documents the recommended process to build HandBrake on
|
|
Linux hosts from the official source-code repository. Building from any
|
|
other source is not supported.
|
|
|
|
2 Prerequisites
|
|
***************
|
|
|
|
The following are the recommended specifications for building on
|
|
Linux; but is not necessarily the only configuration that is possible:
|
|
|
|
* Intel 32-bit or 64-bit kernel
|
|
|
|
* Ubuntu 12.04, gcc 4.5, yasm 1.2.x
|
|
|
|
* Fedora 17 and 18, gcc 4.5, yasm 1.2.x
|
|
|
|
* gcc 4.5 or higher is reported to work
|
|
|
|
Note: It is recommended to use the platform distribution's
|
|
standard compiler for maximum C++ compatibility. If you build with
|
|
a custom compiler it will likely introduce non-standard runtime
|
|
requirements and have new/delete, exception and RTTI
|
|
incompatibilities. There are of course many valid reasons to build
|
|
with unbundled compilers, but be aware it is generally unsupported
|
|
and left as an exercise to the reader.
|
|
|
|
The following general tools are used on various platforms and it is
|
|
recommended you use these versions or similar:
|
|
|
|
* subversion - 1.6.16
|
|
|
|
* python - Python 2.7.1
|
|
|
|
* curl - curl 7.21.4 (or wget)
|
|
|
|
* m4 - GNU M4 1.4.6
|
|
|
|
* make - GNU Make 3.81
|
|
|
|
* patch - Patch 2.5.8
|
|
|
|
* tar - GNU tar 1.26
|
|
|
|
* wget - GNU Wget 1.13.4 (or curl)
|
|
|
|
The GTK UI introduces some significant extra build requirements. If you
|
|
intend to disable building the GUI with `configure --disable-gtk' you
|
|
will not need many of these packages installed:
|
|
|
|
Ubuntu 12+ packages:
|
|
* subversion (cli/gui)
|
|
|
|
* yasm (cli/gui)
|
|
|
|
* build-essential (cli/gui)
|
|
|
|
* autoconf (cli/gui)
|
|
|
|
* libtool (cli/gui)
|
|
|
|
* zlib1g-dev (cli/gui)
|
|
|
|
* libbz2-dev (cli/gui)
|
|
|
|
* libxml2-dev (cli/gui)
|
|
|
|
* libogg-dev (cli/gui)
|
|
|
|
* libtheora-dev (cli/gui)
|
|
|
|
* libvorbis-dev (cli/gui)
|
|
|
|
* libsamplerate-dev (cli/gui)
|
|
|
|
* libfribidi-dev (cli/gui)
|
|
|
|
* libfreetype6-dev (cli/gui)
|
|
|
|
* libfontconfig1-dev (cli/gui)
|
|
|
|
* libass-dev (cli/gui)
|
|
|
|
* intltool (gui)
|
|
|
|
* libglib2.0-dev (gui)
|
|
|
|
* libdbus-glib-1-dev (gui)
|
|
|
|
* libgtk2.0-dev (gui)
|
|
|
|
* libgudev-1.0-dev (gui)
|
|
|
|
* libwebkit-dev (gui)
|
|
|
|
* libnotify-dev (gui)
|
|
|
|
* libgstreamer0.10-dev (gui)
|
|
|
|
* libgstreamer-plugins-base0.10-dev (gui)
|
|
|
|
Ubuntu 12+ packages:
|
|
* libappindicator-dev (gui)
|
|
|
|
To install these packages:
|
|
sudo apt-get install subversion yasm build-essential autoconf libtool \
|
|
zlib1g-dev libbz2-dev libogg-dev libtheora-dev libvorbis-dev \
|
|
libsamplerate-dev libxml2-dev libfribidi-dev libfreetype6-dev \
|
|
libfontconfig1-dev libass-dev intltool libglib2.0-dev libdbus-glib-1-dev \
|
|
libgtk2.0-dev libgudev-1.0-dev libwebkit-dev libnotify-dev \
|
|
libgstreamer0.10-dev libgstreamer-plugins-base0.10-dev libappindicator-dev
|
|
|
|
Fedora 17+ package groups:
|
|
* Development Tools
|
|
|
|
* Development Libraries
|
|
|
|
* X Software Development (gui)
|
|
|
|
* GNOME Software Development (gui)
|
|
|
|
To install these package groups:
|
|
sudo yum groupinstall "Development Tools" "Development Libraries" \
|
|
"X Software Development" "GNOME Software Development"
|
|
|
|
Additional Fedora packages:
|
|
* yasm (cli/gui)
|
|
|
|
* zlib-devel (cli/gui)
|
|
|
|
* bzip2-devel (cli/gui)
|
|
|
|
* libogg-devel (cli/gui)
|
|
|
|
* libtheora-devel (cli/gui)
|
|
|
|
* libvorbis-devel (cli/gui)
|
|
|
|
* libsamplerate-devel (cli/gui)
|
|
|
|
* libxml2-devel (cli/gui)
|
|
|
|
* fribidi-devel (cli/gui)
|
|
|
|
* freetype-devel (cli/gui)
|
|
|
|
* fontconfig-devel (cli/gui)
|
|
|
|
* libass-devel (cli/gui)
|
|
|
|
* dbus-glib-devel (gui)
|
|
|
|
* libgudev1-devel (gui)
|
|
|
|
* webkitgtk-devel (gui)
|
|
|
|
* libnotify-devel (gui)
|
|
|
|
* gstreamer-devel (gui)
|
|
|
|
* gstreamer-plugins-base-devel (gui)
|
|
|
|
To install these packages:
|
|
sudo yum install yasm zlib-devel bzip2-devel libogg-devel libtheora-devel \
|
|
libvorbis-devel libsamplerate-devel libxml2-devel fribidi-devel \
|
|
freetype-devel fontconfig-devel libass-devel dbus-glib-devel \
|
|
libgudev1-devel webkitgtk-devel libnotify-devel \
|
|
gstreamer-devel gstreamer-plugins-base-devel
|
|
|
|
3 QuickStart
|
|
************
|
|
|
|
This chapter is for building from a terminal/shell environment in as
|
|
few commands as possible. Upon completion of the following commands you
|
|
should have a fresh build of HandBrake. Further instructions are
|
|
available beginning with *Note overview:: which describes procedures
|
|
suitable for repeating builds. This chapter should be skipped by those
|
|
seeking more than a minimalist build.
|
|
|
|
svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
|
|
cd hb-trunk
|
|
./configure --launch
|
|
|
|
The special option `--launch' selects launch mode and performs the
|
|
following steps:
|
|
|
|
* assert scratch directory `build/' does not exist
|
|
|
|
* create scratch directory `build/'
|
|
|
|
* change to directory `build/'
|
|
|
|
* launch `make'
|
|
|
|
* capture build output to `build/log/build.txt'
|
|
|
|
* echo build output
|
|
|
|
* print elapsed time
|
|
|
|
* indicate if build ultimately succeeded or failed
|
|
|
|
4 Overview
|
|
**********
|
|
|
|
Linux builds are performed from a terminal. There is no support for
|
|
building from any IDEs.
|
|
|
|
5 Building via Terminal
|
|
***********************
|
|
|
|
5.1 Checkout Sources
|
|
====================
|
|
|
|
Checkout HandBrake from the official source-code repository.
|
|
|
|
svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
|
|
cd hb-trunk
|
|
|
|
Sources are checked out from the `trunk' branch. This document was
|
|
generated from that very branch, and for example purposes, we will use
|
|
exactly the same branch.
|
|
|
|
If you have write-access to the repository, then you may add the
|
|
appropriate login/password information as needed. It is recommended to
|
|
use Subversion 1.6.0 or higher. Lower versions should also work.
|
|
|
|
5.2 Configure
|
|
=============
|
|
|
|
Configure the build system.
|
|
|
|
./configure
|
|
|
|
Configure will automatically create a scratch build directory `build'
|
|
unless you use GNU-style build procedures and first `cd' to a directory
|
|
other than top-level source. Additionally you may use `--build' to
|
|
specify the directory. The name of the directory is arbitrary but it is
|
|
recommended to use something which indicates transient files which are
|
|
not checked into the repository.
|
|
|
|
The `configure' utility accepts many options. It is recommended that
|
|
you specify `--help' for the complete list of options. The following
|
|
options are also documented here:
|
|
|
|
`--help'
|
|
List available options.
|
|
|
|
`--src=DIR'
|
|
Specify top-level source directory for HandBrake sources.
|
|
|
|
`--build=DIR'
|
|
Specify destination directory for final product install. The
|
|
default is to use either `build' if in the top-level source
|
|
directory, otherwise `.'
|
|
|
|
`--prefix=DIR'
|
|
Specify destination directory for final product install. This
|
|
defaults to a reasonable platform-specific value.
|
|
|
|
`--launch'
|
|
All-in-one option which launches the build and logs output
|
|
automatically. Useful for novices and quick-start procedures.
|
|
|
|
`--disable-gtk'
|
|
Disable building the GTK GUI on applicable platforms such as
|
|
Linux.
|
|
|
|
`--debug=MODE'
|
|
Select debug mode. Must be one of `none', `min', `std', `max'.
|
|
This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
|
|
|
|
`--optimize=MODE'
|
|
Select optimize mode. Must be one of `none', `speed', `size'.
|
|
This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
|
|
|
|
`--arch=MODE'
|
|
Select build architecture. The available architectures vary by
|
|
platform. Most platforms support exactly one architecture except
|
|
Mac OS X which has support for various universal binary
|
|
architectures. The available choices are hard-coded per platform
|
|
and no sanity checks for the required tools are performed.
|
|
|
|
`--disable-xcode'
|
|
Disable shunting the build through `xcodebuild'. If this option is
|
|
applied, `HandBrakeCLI' will be produced in a similar fashion as
|
|
it is on other platforms; sans Xcode and the Cocoa application
|
|
will not be produced. Mac OS X only.
|
|
|
|
`--xcconfig=MODE'
|
|
Select Xcode project configuration file. The available modes are
|
|
the basenames of files located in `macosx/xcconfig/*.xcconfig'
|
|
which direct Xcode to build using various architecture and Mac OS
|
|
X deployment options. Mac OS X only.
|
|
|
|
Clean-room procedures dictate that when certain factors change, old
|
|
builds should be scrapped and new builds configured. This is the main
|
|
reason for requiring a scratch directory; to promote consistent,
|
|
reliable and clean software builds. The following is a short list of
|
|
some of the reasons why someone may choose to scrap an existing build:
|
|
|
|
* configure with different options
|
|
|
|
* subversion working dir is updated and you want configure to
|
|
re-evaluate working dir metadata.
|
|
|
|
* build corruption is suspected
|
|
|
|
There are generally two methods for scrapping a build. The `build'
|
|
directory can be recursively removed which has the effect of loosing
|
|
your existing configuration but does guarantee no residuals are left
|
|
behind. The other method is to ask the build system to perform an `make
|
|
xclean'. This is known to work well but will leave empty directories
|
|
behind. However, the configuration is left intact.
|
|
|
|
5.3 Build
|
|
=========
|
|
|
|
Build main product. All necessary dependencies are also built if
|
|
required.
|
|
|
|
make
|
|
|
|
Parallel builds may optionally be enabled. Be aware that while a
|
|
parallel build may save time on systems with additional cores, the
|
|
output is often mixed, overlapped and sometimes even corrupted with
|
|
binary characters. Thus if you experience a build issue, you should
|
|
clean and redo the build in default serial mode to produce a readable
|
|
log. The following command allows for up to 4 concurrent jobs via make:
|
|
|
|
make -j4
|
|
|
|
5.4 Make Targets
|
|
================
|
|
|
|
The build system supports passing many kinds of targets some of which
|
|
become very useful in normal development cycles. The targets by
|
|
convention are lower-case words passed to `make'. Global targets are
|
|
one-word targets. Scoped targets are usually two-words separated by a
|
|
period.
|
|
|
|
5.4.1 Global
|
|
------------
|
|
|
|
`make'
|
|
Alias for `make build'.
|
|
|
|
`make build'
|
|
Build main product. All necessary dependencies are also built if
|
|
required.
|
|
|
|
`make clean'
|
|
Clean all build output excluding contrib modules. Configuration is
|
|
retained.
|
|
|
|
`make install'
|
|
Perform final product(s) install. This will install build
|
|
products to a standard directory or one specified via `configure
|
|
--prefix' option.
|
|
|
|
`make uninstall'
|
|
Perform final product(s) uninstall. This will uninstall any
|
|
products which may have been previously installed.
|
|
|
|
`make xclean'
|
|
Clean all build output including contrib modules. Configuration is
|
|
retained.
|
|
|
|
`make doc'
|
|
Build auto-generated project documentation. Various articles are
|
|
produced and may be found in `build/doc/articles'.
|
|
|
|
`make doc.post'
|
|
Build auto-generated project documentation and post produced
|
|
articles directly to source tree.
|
|
|
|
`make report.help'
|
|
Print list of available makefile vars report targets. These
|
|
reports detail var definitions and expanded values used by the
|
|
build system. For experts only.
|
|
|
|
`make report.all'
|
|
Convenience target which aggregates all reports. For experts only.
|
|
|
|
5.4.2 General Modules
|
|
---------------------
|
|
|
|
General modules such as `libhb', `test' and `gtk' have the following
|
|
scoped targets:
|
|
|
|
`make MODULE.build'
|
|
Build MODULE.
|
|
|
|
`make MODULE.clean'
|
|
Clean build output for MODULE.
|
|
|
|
5.4.3 Contrib Modules
|
|
---------------------
|
|
|
|
Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
|
|
`fontconfig', `freetype', `fribidi', `lame', `libass', `libbluray',
|
|
`libdca', `libdvdnav', `libdvdread', `libdvdread', `libiconv',
|
|
`libmkv', `libogg', `libsamplerate', `libtheora', `libvorbis',
|
|
`libxml2', `mp4v2', `mpeg2dec', `x264', `yasm' and `zlib' have the
|
|
following scoped targets:
|
|
|
|
`make MODULE.fetch'
|
|
Download source tarball from the Internet and save to
|
|
`TOP/downloads' directory. No check-summing is performed.
|
|
|
|
`make MODULE.extract'
|
|
Extract source tarball into `build' tree.
|
|
|
|
`make MODULE.patch'
|
|
Apply appropriate patches (if any) to module sources.
|
|
|
|
`make MODULE.configure'
|
|
Configure module sources. This usually invokes autotool configure.
|
|
|
|
`make MODULE.build'
|
|
Build module. This usually invokes autotool build.
|
|
|
|
`make MODULE.install'
|
|
Install module products such as headers and libraries into `build'
|
|
tree. This usually invokes autotool install.
|
|
|
|
`make MODULE.uninstall'
|
|
Uninstall module products; generally the reverse of install. This
|
|
usually invokes autotool uninstall.
|
|
|
|
`make MODULE.clean'
|
|
Clean module; generally the reverse of build. This usually
|
|
invokes autotool clean.
|
|
|
|
`make MODULE.xclean'
|
|
Extra clean module; first invokes uninstall then recursively
|
|
removes the module build directory.
|
|
|
|
5.4.4 Contrib Touch and Untouch
|
|
-------------------------------
|
|
|
|
Also available are some very granular targets which help force builds
|
|
from specific cycle points. The following targets are available to
|
|
touch and untouch the respective module target; this will force the
|
|
build system to treat the target as satisfied after a touch or
|
|
unsatisfied after an untouch:
|
|
|
|
* make MODULE.extract.touch
|
|
|
|
* make MODULE.extract.untouch
|
|
|
|
* make MODULE.patch.touch
|
|
|
|
* make MODULE.patch.untouch
|
|
|
|
* make MODULE.configure.touch
|
|
|
|
* make MODULE.configure.untouch
|
|
|
|
* make MODULE.build.touch
|
|
|
|
* make MODULE.build.untouch
|
|
|
|
* make MODULE.install.touch
|
|
|
|
* make MODULE.install.untouch
|
|
|
|
5.4.5 Contrib Aggregates
|
|
------------------------
|
|
|
|
For convenience, the following targets aggregate the all contrib
|
|
modules' respective targets together:
|
|
|
|
* make contrib.fetch
|
|
|
|
* make contrib.extract
|
|
|
|
* make contrib.patch
|
|
|
|
* make contrib.configure
|
|
|
|
* make contrib.build
|
|
|
|
* make contrib.install
|
|
|
|
* make contrib.uninstall
|
|
|
|
* make contrib.clean
|
|
|
|
* make contrib.xclean
|
|
|
|
5.5 Customizing Make
|
|
====================
|
|
|
|
If the need arises to override settings in the build system
|
|
(essentially gnu-make variables) the recommended method is to create
|
|
optional include files which are automatically included if present and
|
|
follow this naming convention; Do not check these files into the
|
|
repository:
|
|
|
|
`_SRC_/custom.defs'
|
|
Custom makevar definitions outside `build'. Suitable for settings
|
|
which apply across all builds for a particular checkout; or which
|
|
survives manual removal of `build'.
|
|
|
|
`_SRC_/custom.rules'
|
|
Custom make rules outside `build'. Suitable for rules which apply
|
|
across all builds for a particular checkout; or which survives
|
|
manual removal of `build'.
|
|
|
|
`_BUILD_/GNUmakefile.custom.defs'
|
|
Custom makevar definitions specific to a `build' directory.
|
|
|
|
`_BUILD_/GNUmakefile.custom.rules'
|
|
Custom makevar rules specific to a `build' directory.
|
|
|
|
|
|
The purpose is to allow a place to store local build settings for
|
|
testing, tweaking, and experimenting with build configuration without
|
|
losing your settings if `configure' is invoked; ie: `configure' would
|
|
overwrite `GNUmakefile' and any customizations contained therein would
|
|
be lost. Here is a short example of what the contents of
|
|
`_SRC_/custom.defs' might contain:
|
|
|
|
## bump to gcc-4.6 in current path
|
|
GCC.gcc = /usr/bin/gcc-4.6
|
|
|
|
## replace optimize for 'speed' with more aggressive settings
|
|
GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
|
|
|
|
See also `make report.help' which displays a set of reports used to
|
|
dump makefile vars.
|
|
|
|
6 Troubleshooting
|
|
*****************
|
|
|
|
When troubleshooting build issues, the following files relative to the
|
|
`build/' directory may be especially useful:
|
|
|
|
`GNUmakefile'
|
|
Top-level makefile which contains build settings generated via
|
|
configure.
|
|
|
|
`log/config.info.txt'
|
|
Record of output from configure.
|
|
|
|
`log/config.verbose.txt'
|
|
Record of verbose output from configure.
|
|
|
|
`log/build.txt'
|
|
Record of output from `configure --launch'. Similar output may be
|
|
recorded using `make' depending on which shell is in use, eg:
|
|
`make >& log/build.txt' or `make > log/build.txt 2>&1'.
|
|
|
|
`log/xcodemake.env.txt'
|
|
Environment (variables) dump as seen when Xcode forks `make'.
|
|
Mac OS X only.
|
|
|
|
Appendix A Project Repository Details
|
|
*************************************
|
|
|
|
url: svn://svn.handbrake.fr/HandBrake/trunk
|
|
root: svn://svn.handbrake.fr/HandBrake
|
|
branch: trunk
|
|
uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
|
|
rev: 5208
|
|
date: 2013-01-26 18:47:13 +0000
|
|
type: developer
|
|
|