1 Guide to Building HandBrake svn2688 (2009071301) on Linux
2 *********************************************************
11 5 Building via Terminal
19 5.4.4 Contrib Touch and Untouch
20 5.4.5 Contrib Aggregates
23 Appendix A Project Repository Details
29 This guide documents the recommended process to build HandBrake on
30 Linux hosts from the official source-code repository. Building from any
31 other source is not supported.
36 The following are the recommended specifications for building on
37 Linux; but is not necessarily the only configuration that is possible:
39 * Intel 32-bit or 64-bit kernel
41 * Ubuntu 8.0.4, gcc 4.3.0, yasm 0.7.1.2093
43 * Ubuntu 8.10, gcc 4.3.2, yasm 0.7.1.2093
45 * Fedora 9, gcc 4.3.0, yasm 0.7.1.2093
47 * Fedora 10, gcc 4.3.2, yasm 0.7.1.2093
49 * gcc 4.0.0 or higher is reported to work
51 Note: It is recommended to use the platform distribution's bundled
52 compiler for maximum C++ compatibility. If you build with a custom
53 compiler it will likely introduce non-standard runtime
54 requirements. There are of course many valid reasons to build with
55 unbundled compilers, but be aware it is generally unsupported and
56 left as an exercise to the reader.
58 The following general tools are used on various platforms and it is
59 recommended you use these versions or similar:
63 * python - Python 2.4.6
65 * curl - curl 7.19.4 (or wget)
69 * make - GNU Make 3.81
73 * tar - GNU tar 1.15.1
75 * wget - GNU Wget 1.11.4 (or curl)
77 The GTK UI introduces some significant extra build requirements. If you
78 intend to disable building the GUI with `configure --disable-gtk' you
79 will not need many of these packages installed:
82 * subversion (cli/gui)
86 * build-essential (cli/gui)
92 * zlib1g-dev (cli/gui)
94 * libbz2-dev (cli/gui)
98 * libglib2.0-dev (gui)
100 * libdbus-glib-1-dev (gui)
102 * libgtk2.0-dev (gui)
106 * libhal-storage-dev (gui)
108 * libwebkit-dev (gui)
110 * libnotify-dev (gui)
112 * libgstreamer0.10-dev (gui)
114 * libgstreamer-plugins-base0.10-dev (gui)
116 To install these packages:
117 sudo apt-get install subversion yasm build-essential \
118 autoconf libtool zlib1g-dev libbz2-dev intltool libglib2.0-dev \
119 libdbus-glib-1-dev libgtk2.0-dev libhal-dev libhal-storage-dev \
120 libwebkit-dev libnotify-dev libgstreamer0.10-dev \
121 libgstreamer-plugins-base0.10-dev
123 Fedora 10 package groups:
126 * Development Libraries
128 * X Software Development (gui)
130 * GNOME Software Development (gui)
132 To install these package groups:
133 sudo yum groupinstall "Development Tools" "Development Libraries" \
134 "X Software Development" "GNOME Software Development"
136 Additional Fedora 10 packages:
139 * zlib-devel (cli/gui)
141 * bzip2-devel (cli/gui)
143 * dbus-glib-devel (gui)
147 * webkitgtk-devel (gui)
149 * libnotify-devel (gui)
151 * gstreamer-devel (gui)
153 * gstreamer-plugins-base-devel (gui)
155 To install these packages:
156 sudo yum install yasm zlib-devel bzip2-devel \
157 dbus-glib-devel hal-devel webkitgtk-devel libnotify-devel\
158 gstreamer-devel gstreamer-plugins-base-devel
163 This chapter is for building from a terminal/shell environment in as
164 few commands as possible. Upon completion of the following commands you
165 should have a fresh build of HandBrake. Further instructions are
166 available beginning with *note overview:: which describes procedures
167 suitable for repeating builds. This chapter should be skipped by those
168 seeking more than a minimalist build.
170 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
174 The special option `--launch' selects launch mode and performs the
177 * assert scratch directory `build/' does not exist
179 * create scratch directory `build/'
181 * change to directory `build/'
185 * capture build output to `build/log/build.txt'
191 * indicate if build ultimately succeeded or failed
196 Linux builds are performed from a terminal. There is no support for
197 building from any IDEs.
199 5 Building via Terminal
200 ***********************
205 Checkout HandBrake from the official source-code repository.
207 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
210 Sources are checked out from the `trunk' branch. This document was
211 generated from that very branch, and for example purposes, we will use
212 exactly the same branch.
214 If you have write-access to the repository, then you may add the
215 appropriate login/password information as needed. It is recommended to
216 use Subversion 1.5.0 or higher. Lower versions should also work.
221 Configure the build system.
225 Configure will automatically create a scratch build directory `build'
226 unless you use GNU-style build procedures and first `cd' to a directory
227 other than top-level source. Additionally you may use `--build' to
228 specify the directory. The name of the directory is arbitrary but it is
229 recommended to use something which indicates transient files which are
230 not checked into the repository.
232 The `configure' utility accepts many options. It is recommended that
233 you specify `--help' for the complete list of options. The following
234 options are also documented here:
237 List available options.
240 Specify top-level source directory for HandBrake sources.
243 Specify destination directory for final product install. The
244 default is to use either `build' if in the top-level source
245 directory, otherwise `.'
248 Specify destination directory for final product install. This
249 defaults to a reasonable platform-specific value.
252 All-in-one option which launches the build and logs output
253 automatically. Useful for novices and quick-start procedures.
256 Disable shunting the build through `xcodebuild'. If this option is
257 applied, `HandBrakeCLI' will be produced in a similar fashion as
258 it is on other platforms; sans Xcode and the Cocoa application
259 will not be produced. Mac OS X only.
262 Disable building the GTK GUI on applicable platforms such as
266 Select debug mode. Must be one of `none', `min', `std', `max'.
267 This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
270 Select optimize mode. Must be one of `none', `speed', `size'.
271 This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
274 Select build architecture. The available architectures vary by
275 platform. Most platforms support exactly one architecture except
276 Mac OS X which has support for various universal binary
277 architectures. The available choices are hard-coded per platform
278 and no sanity checks for the required tools are performed.
281 Clean-room procedures dictate that when certain factors change, old
282 builds should be scrapped and new builds configured. This is the main
283 reason for requiring a scratch directory; to promote consistent,
284 reliable and clean software builds. The following is a short list of
285 some of the reasons why someone may choose to scrap an existing build:
287 * configure with different options
289 * subversion working dir is updated and you want configure to
290 re-evaluate working dir metadata.
292 * build corruption is suspected
294 There are generally two methods for scrapping a build. The `build'
295 directory can be recursively removed which has the effect of loosing
296 your existing configuration but does guarantee no residuals are left
297 behind. The other method is to ask the build system to perform an `make
298 xclean'. This is known to work well but will leave empty directories
299 behind. However, the configuration is left intact.
304 Build main product. All necessary dependencies are also built if
309 Parallel builds may optionally be enabled. Be aware that while a
310 parallel build may save time on systems with additional cores, the
311 output is often mixed, overlapped and sometimes even corrupted with
312 binary characters. Thus if you experience a build issue, you should
313 clean and redo the build in default serial mode to produce a readable
314 log. The following command allows for up to 4 concurrent jobs via make:
321 The build system supports passing many kinds of targets some of which
322 become very useful in normal development cycles. The targets by
323 convention are lower-case words passed to `make'. Global targets are
324 one-word targets. Scoped targets are usually two-words separated by a
331 Alias for `make build'.
334 Build main product. All necessary dependencies are also built if
338 Clean all build output excluding contrib modules. Configuration is
342 Perform final product(s) install. This will install build
343 products to a standard directory or one specified via `configure
347 Perform final product(s) uninstall. This will uninstall any
348 products which may have been previously installed.
351 Clean all build output including contrib modules. Configuration is
355 Build auto-generated project documentation. Various articles are
356 produced and may be found in `build/doc/articles'.
359 Print list of available makefile vars report targets. These
360 reports detail var definitions and expanded values used by the
361 build system. For experts only.
364 Convenience target which aggregates all reports. For experts only.
366 5.4.2 General Modules
367 ---------------------
369 General modules such as `libhb', `test' and `gtk' have the following
376 Clean build output for MODULE.
378 5.4.3 Contrib Modules
379 ---------------------
381 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
382 `lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate',
383 `libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have
384 the following scoped targets:
387 Download source tarball from the Internet and save to
388 `TOP/downloads' directory. No check-summing is performed.
390 `make MODULE.extract'
391 Extract source tarball into `build' tree.
394 Apply appropriate patches (if any) to module sources.
396 `make MODULE.configure'
397 Configure module sources. This usually invokes autotool configure.
400 Build module. This usually invokes autotool build.
402 `make MODULE.install'
403 Install module products such as headers and libraries into `build'
404 tree. This usually invokes autotool install.
406 `make MODULE.uninstall'
407 Uninstall module products; generally the reverse of install. This
408 usually invokes autotool uninstall.
411 Clean module; generally the reverse of build. This usually
412 invokes autotool clean.
415 Extra clean module; first invokes uninstall then recursively
416 removes the module build directory.
418 5.4.4 Contrib Touch and Untouch
419 -------------------------------
421 Also available are some very granular targets which help force builds
422 from specific cycle points. The following targets are available to
423 touch and untouch the respective module target; this will force the
424 build system to treat the target as satisfied after a touch or
425 unsatisfied after an untouch:
427 * make MODULE.extract.touch
429 * make MODULE.extract.untouch
431 * make MODULE.patch.touch
433 * make MODULE.patch.untouch
435 * make MODULE.configure.touch
437 * make MODULE.configure.untouch
439 * make MODULE.build.touch
441 * make MODULE.build.untouch
443 * make MODULE.install.touch
445 * make MODULE.install.untouch
447 5.4.5 Contrib Aggregates
448 ------------------------
450 For convenience, the following targets aggregate the all contrib
451 modules' respective targets together:
455 * make contrib.extract
459 * make contrib.configure
463 * make contrib.install
465 * make contrib.uninstall
469 * make contrib.xclean
474 If the need arises to override settings in the build system
475 (essentially gnu-make variables) the recommended method is to create
476 optional include files which are automatically included if present and
477 follow this naming convention; Do not check these files into the
481 Custom makevar definitions outside `build'. Suitable for settings
482 which apply across all builds for a particular checkout; or which
483 survives manual removal of `build'.
486 Custom make rules outside `build'. Suitable for rules which apply
487 across all builds for a particular checkout; or which survives
488 manual removal of `build'.
490 `_BUILD_/GNUmakefile.custom.defs'
491 Custom makevar definitions specific to a `build' directory.
493 `_BUILD_/GNUmakefile.custom.rules'
494 Custom makevar rules specific to a `build' directory.
497 The purpose is to allow a place to store local build settings for
498 testing, tweaking, and experimenting with build configuration without
499 losing your settings if `configure' is invoked; ie: `configure' would
500 overwrite `GNUmakefile' and any customizations contained therein would
501 be lost. Here is a short example of what the contents of
502 `_SRC_/custom.defs' might contain:
504 ## bump to gcc-4.2 in current path
505 GCC.gcc = /usr/bin/gcc-4.2
507 ## replace optimize for 'speed' with more aggressive settings
508 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
510 See also `make report.help' which displays a set of reports used to
516 When troubleshooting build issues, the following files relative to the
517 `build/' directory may be especially useful:
520 Top-level makefile which contains build settings generated via
523 `log/config.info.txt'
524 Record of output from configure.
526 `log/config.verbose.txt'
527 Record of verbose output from configure.
530 Record of output from `configure --launch'. Similar output may be
531 recorded using `make' depending on which shell is in use, eg:
532 `make >& log/build.txt' or `make > log/build.txt 2>&1'.
534 `log/xcodemake.env.txt'
535 Environment (variables) dump as seen when Xcode forks `make'.
538 Appendix A Project Repository Details
539 *************************************
541 url: svn://svn.handbrake.fr/HandBrake/trunk
542 root: svn://svn.handbrake.fr/HandBrake
544 uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
546 date: 2009-07-12 22:47:33 -0700