1 Guide to Building HandBrake svn3023 (2009121001) 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.04, gcc 4.3.0, yasm 0.7.1
43 * Ubuntu 8.10, gcc 4.3.2, yasm 0.7.1
45 * Ubuntu 9.04, gcc 4.3.3, yasm 0.7.1
47 * Ubuntu 9.10, gcc 4.4.1, yasm 0.8.0
49 * Fedora 9, gcc 4.3.0, yasm 0.7.1
51 * Fedora 10, gcc 4.3.2, yasm 0.7.1
53 * Fedora 11, gcc 4.4.0, yasm 0.7.2
55 * Fedora 12, gcc 4.4.2, yasm 0.7.2
57 * gcc 4.0.0 or higher is reported to work
59 Note: It is recommended to use the platform distribution's bundled
60 compiler for maximum C++ compatibility. If you build with a custom
61 compiler it will likely introduce non-standard runtime
62 requirements. There are of course many valid reasons to build with
63 unbundled compilers, but be aware it is generally unsupported and
64 left as an exercise to the reader.
66 The following general tools are used on various platforms and it is
67 recommended you use these versions or similar:
71 * python - Python 2.4.6
73 * curl - curl 7.19.4 (or wget)
77 * make - GNU Make 3.81
81 * tar - GNU tar 1.15.1
83 * wget - GNU Wget 1.11.4 (or curl)
85 The GTK UI introduces some significant extra build requirements. If you
86 intend to disable building the GUI with `configure --disable-gtk' you
87 will not need many of these packages installed:
89 Ubuntu 8.04 - 9.10 packages:
90 * subversion (cli/gui)
94 * build-essential (cli/gui)
100 * zlib1g-dev (cli/gui)
102 * libbz2-dev (cli/gui)
106 * libglib2.0-dev (gui)
108 * libdbus-glib-1-dev (gui)
110 * libgtk2.0-dev (gui)
114 * libhal-storage-dev (gui)
116 * libwebkit-dev (gui)
118 * libnotify-dev (gui)
120 * libgstreamer0.10-dev (gui)
122 * libgstreamer-plugins-base0.10-dev (gui)
124 Ubuntu 8.04, substitute libwebkitgtk-dev for libwebkit-dev
126 To install these packages:
127 sudo apt-get install subversion yasm build-essential \
128 autoconf libtool zlib1g-dev libbz2-dev intltool libglib2.0-dev \
129 libdbus-glib-1-dev libgtk2.0-dev libhal-dev libhal-storage-dev \
130 libwebkit-dev libnotify-dev libgstreamer0.10-dev \
131 libgstreamer-plugins-base0.10-dev
133 Fedora 9 - 12 package groups:
136 * Development Libraries
138 * X Software Development (gui)
140 * GNOME Software Development (gui)
142 To install these package groups:
143 sudo yum groupinstall "Development Tools" "Development Libraries" \
144 "X Software Development" "GNOME Software Development"
146 Additional Fedora packages:
149 * zlib-devel (cli/gui)
151 * bzip2-devel (cli/gui)
153 * dbus-glib-devel (gui)
157 * webkitgtk-devel (gui)
159 * libnotify-devel (gui)
161 * gstreamer-devel (gui)
163 * gstreamer-plugins-base-devel (gui)
165 Fedora 9 & 10, substitute WebKit-gtk-devel for webkitgtk-devel
167 To install these packages:
168 sudo yum install yasm zlib-devel bzip2-devel \
169 dbus-glib-devel hal-devel webkitgtk-devel libnotify-devel\
170 gstreamer-devel gstreamer-plugins-base-devel
175 This chapter is for building from a terminal/shell environment in as
176 few commands as possible. Upon completion of the following commands you
177 should have a fresh build of HandBrake. Further instructions are
178 available beginning with *note overview:: which describes procedures
179 suitable for repeating builds. This chapter should be skipped by those
180 seeking more than a minimalist build.
182 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
186 The special option `--launch' selects launch mode and performs the
189 * assert scratch directory `build/' does not exist
191 * create scratch directory `build/'
193 * change to directory `build/'
197 * capture build output to `build/log/build.txt'
203 * indicate if build ultimately succeeded or failed
208 Linux builds are performed from a terminal. There is no support for
209 building from any IDEs.
211 5 Building via Terminal
212 ***********************
217 Checkout HandBrake from the official source-code repository.
219 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
222 Sources are checked out from the `trunk' branch. This document was
223 generated from that very branch, and for example purposes, we will use
224 exactly the same branch.
226 If you have write-access to the repository, then you may add the
227 appropriate login/password information as needed. It is recommended to
228 use Subversion 1.5.0 or higher. Lower versions should also work.
233 Configure the build system.
237 Configure will automatically create a scratch build directory `build'
238 unless you use GNU-style build procedures and first `cd' to a directory
239 other than top-level source. Additionally you may use `--build' to
240 specify the directory. The name of the directory is arbitrary but it is
241 recommended to use something which indicates transient files which are
242 not checked into the repository.
244 The `configure' utility accepts many options. It is recommended that
245 you specify `--help' for the complete list of options. The following
246 options are also documented here:
249 List available options.
252 Specify top-level source directory for HandBrake sources.
255 Specify destination directory for final product install. The
256 default is to use either `build' if in the top-level source
257 directory, otherwise `.'
260 Specify destination directory for final product install. This
261 defaults to a reasonable platform-specific value.
264 All-in-one option which launches the build and logs output
265 automatically. Useful for novices and quick-start procedures.
268 Disable shunting the build through `xcodebuild'. If this option is
269 applied, `HandBrakeCLI' will be produced in a similar fashion as
270 it is on other platforms; sans Xcode and the Cocoa application
271 will not be produced. Mac OS X only.
274 Disable building the GTK GUI on applicable platforms such as
278 Select debug mode. Must be one of `none', `min', `std', `max'.
279 This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
282 Select optimize mode. Must be one of `none', `speed', `size'.
283 This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
286 Select build architecture. The available architectures vary by
287 platform. Most platforms support exactly one architecture except
288 Mac OS X which has support for various universal binary
289 architectures. The available choices are hard-coded per platform
290 and no sanity checks for the required tools are performed.
293 Clean-room procedures dictate that when certain factors change, old
294 builds should be scrapped and new builds configured. This is the main
295 reason for requiring a scratch directory; to promote consistent,
296 reliable and clean software builds. The following is a short list of
297 some of the reasons why someone may choose to scrap an existing build:
299 * configure with different options
301 * subversion working dir is updated and you want configure to
302 re-evaluate working dir metadata.
304 * build corruption is suspected
306 There are generally two methods for scrapping a build. The `build'
307 directory can be recursively removed which has the effect of loosing
308 your existing configuration but does guarantee no residuals are left
309 behind. The other method is to ask the build system to perform an `make
310 xclean'. This is known to work well but will leave empty directories
311 behind. However, the configuration is left intact.
316 Build main product. All necessary dependencies are also built if
321 Parallel builds may optionally be enabled. Be aware that while a
322 parallel build may save time on systems with additional cores, the
323 output is often mixed, overlapped and sometimes even corrupted with
324 binary characters. Thus if you experience a build issue, you should
325 clean and redo the build in default serial mode to produce a readable
326 log. The following command allows for up to 4 concurrent jobs via make:
333 The build system supports passing many kinds of targets some of which
334 become very useful in normal development cycles. The targets by
335 convention are lower-case words passed to `make'. Global targets are
336 one-word targets. Scoped targets are usually two-words separated by a
343 Alias for `make build'.
346 Build main product. All necessary dependencies are also built if
350 Clean all build output excluding contrib modules. Configuration is
354 Perform final product(s) install. This will install build
355 products to a standard directory or one specified via `configure
359 Perform final product(s) uninstall. This will uninstall any
360 products which may have been previously installed.
363 Clean all build output including contrib modules. Configuration is
367 Build auto-generated project documentation. Various articles are
368 produced and may be found in `build/doc/articles'.
371 Print list of available makefile vars report targets. These
372 reports detail var definitions and expanded values used by the
373 build system. For experts only.
376 Convenience target which aggregates all reports. For experts only.
378 5.4.2 General Modules
379 ---------------------
381 General modules such as `libhb', `test' and `gtk' have the following
388 Clean build output for MODULE.
390 5.4.3 Contrib Modules
391 ---------------------
393 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
394 `lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate',
395 `libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have
396 the following scoped targets:
399 Download source tarball from the Internet and save to
400 `TOP/downloads' directory. No check-summing is performed.
402 `make MODULE.extract'
403 Extract source tarball into `build' tree.
406 Apply appropriate patches (if any) to module sources.
408 `make MODULE.configure'
409 Configure module sources. This usually invokes autotool configure.
412 Build module. This usually invokes autotool build.
414 `make MODULE.install'
415 Install module products such as headers and libraries into `build'
416 tree. This usually invokes autotool install.
418 `make MODULE.uninstall'
419 Uninstall module products; generally the reverse of install. This
420 usually invokes autotool uninstall.
423 Clean module; generally the reverse of build. This usually
424 invokes autotool clean.
427 Extra clean module; first invokes uninstall then recursively
428 removes the module build directory.
430 5.4.4 Contrib Touch and Untouch
431 -------------------------------
433 Also available are some very granular targets which help force builds
434 from specific cycle points. The following targets are available to
435 touch and untouch the respective module target; this will force the
436 build system to treat the target as satisfied after a touch or
437 unsatisfied after an untouch:
439 * make MODULE.extract.touch
441 * make MODULE.extract.untouch
443 * make MODULE.patch.touch
445 * make MODULE.patch.untouch
447 * make MODULE.configure.touch
449 * make MODULE.configure.untouch
451 * make MODULE.build.touch
453 * make MODULE.build.untouch
455 * make MODULE.install.touch
457 * make MODULE.install.untouch
459 5.4.5 Contrib Aggregates
460 ------------------------
462 For convenience, the following targets aggregate the all contrib
463 modules' respective targets together:
467 * make contrib.extract
471 * make contrib.configure
475 * make contrib.install
477 * make contrib.uninstall
481 * make contrib.xclean
486 If the need arises to override settings in the build system
487 (essentially gnu-make variables) the recommended method is to create
488 optional include files which are automatically included if present and
489 follow this naming convention; Do not check these files into the
493 Custom makevar definitions outside `build'. Suitable for settings
494 which apply across all builds for a particular checkout; or which
495 survives manual removal of `build'.
498 Custom make rules outside `build'. Suitable for rules which apply
499 across all builds for a particular checkout; or which survives
500 manual removal of `build'.
502 `_BUILD_/GNUmakefile.custom.defs'
503 Custom makevar definitions specific to a `build' directory.
505 `_BUILD_/GNUmakefile.custom.rules'
506 Custom makevar rules specific to a `build' directory.
509 The purpose is to allow a place to store local build settings for
510 testing, tweaking, and experimenting with build configuration without
511 losing your settings if `configure' is invoked; ie: `configure' would
512 overwrite `GNUmakefile' and any customizations contained therein would
513 be lost. Here is a short example of what the contents of
514 `_SRC_/custom.defs' might contain:
516 ## bump to gcc-4.2 in current path
517 GCC.gcc = /usr/bin/gcc-4.2
519 ## replace optimize for 'speed' with more aggressive settings
520 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
522 See also `make report.help' which displays a set of reports used to
528 When troubleshooting build issues, the following files relative to the
529 `build/' directory may be especially useful:
532 Top-level makefile which contains build settings generated via
535 `log/config.info.txt'
536 Record of output from configure.
538 `log/config.verbose.txt'
539 Record of verbose output from configure.
542 Record of output from `configure --launch'. Similar output may be
543 recorded using `make' depending on which shell is in use, eg:
544 `make >& log/build.txt' or `make > log/build.txt 2>&1'.
546 `log/xcodemake.env.txt'
547 Environment (variables) dump as seen when Xcode forks `make'.
550 Appendix A Project Repository Details
551 *************************************
553 url: svn://svn.handbrake.fr/HandBrake/trunk
554 root: svn://svn.handbrake.fr/HandBrake
556 uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
558 date: 2009-12-10 09:44:05 -0800