1 Guide to Building HandBrake svn3555 (2010092801) 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 9.10 - 10.04 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)
112 * libgudev-1.0-dev (gui)
114 * libwebkit-dev (gui)
116 * libnotify-dev (gui)
118 * libgstreamer0.10-dev (gui)
120 * libgstreamer-plugins-base0.10-dev (gui)
122 To install these packages:
123 sudo apt-get install subversion yasm build-essential \
124 autoconf libtool zlib1g-dev libbz2-dev intltool libglib2.0-dev \
125 libdbus-glib-1-dev libgtk2.0-dev libgudev-1.0-dev \
126 libwebkit-dev libnotify-dev libgstreamer0.10-dev \
127 libgstreamer-plugins-base0.10-dev
129 Fedora 12 - 13 package groups:
132 * Development Libraries
134 * X Software Development (gui)
136 * GNOME Software Development (gui)
138 To install these package groups:
139 sudo yum groupinstall "Development Tools" "Development Libraries" \
140 "X Software Development" "GNOME Software Development"
142 Additional Fedora packages:
145 * zlib-devel (cli/gui)
147 * bzip2-devel (cli/gui)
149 * dbus-glib-devel (gui)
151 * libgudev1-devel (gui)
153 * webkitgtk-devel (gui)
155 * libnotify-devel (gui)
157 * gstreamer-devel (gui)
159 * gstreamer-plugins-base-devel (gui)
161 To install these packages:
162 sudo yum install yasm zlib-devel bzip2-devel \
163 dbus-glib-devel libgudev1-devel webkitgtk-devel libnotify-devel \
164 gstreamer-devel gstreamer-plugins-base-devel
169 This chapter is for building from a terminal/shell environment in as
170 few commands as possible. Upon completion of the following commands you
171 should have a fresh build of HandBrake. Further instructions are
172 available beginning with *note overview:: which describes procedures
173 suitable for repeating builds. This chapter should be skipped by those
174 seeking more than a minimalist build.
176 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
180 The special option `--launch' selects launch mode and performs the
183 * assert scratch directory `build/' does not exist
185 * create scratch directory `build/'
187 * change to directory `build/'
191 * capture build output to `build/log/build.txt'
197 * indicate if build ultimately succeeded or failed
202 Linux builds are performed from a terminal. There is no support for
203 building from any IDEs.
205 5 Building via Terminal
206 ***********************
211 Checkout HandBrake from the official source-code repository.
213 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
216 Sources are checked out from the `trunk' branch. This document was
217 generated from that very branch, and for example purposes, we will use
218 exactly the same branch.
220 If you have write-access to the repository, then you may add the
221 appropriate login/password information as needed. It is recommended to
222 use Subversion 1.5.0 or higher. Lower versions should also work.
227 Configure the build system.
231 Configure will automatically create a scratch build directory `build'
232 unless you use GNU-style build procedures and first `cd' to a directory
233 other than top-level source. Additionally you may use `--build' to
234 specify the directory. The name of the directory is arbitrary but it is
235 recommended to use something which indicates transient files which are
236 not checked into the repository.
238 The `configure' utility accepts many options. It is recommended that
239 you specify `--help' for the complete list of options. The following
240 options are also documented here:
243 List available options.
246 Specify top-level source directory for HandBrake sources.
249 Specify destination directory for final product install. The
250 default is to use either `build' if in the top-level source
251 directory, otherwise `.'
254 Specify destination directory for final product install. This
255 defaults to a reasonable platform-specific value.
258 All-in-one option which launches the build and logs output
259 automatically. Useful for novices and quick-start procedures.
262 Disable shunting the build through `xcodebuild'. If this option is
263 applied, `HandBrakeCLI' will be produced in a similar fashion as
264 it is on other platforms; sans Xcode and the Cocoa application
265 will not be produced. Mac OS X only.
268 Disable building the GTK GUI on applicable platforms such as
272 Select debug mode. Must be one of `none', `min', `std', `max'.
273 This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
276 Select optimize mode. Must be one of `none', `speed', `size'.
277 This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
280 Select build architecture. The available architectures vary by
281 platform. Most platforms support exactly one architecture except
282 Mac OS X which has support for various universal binary
283 architectures. The available choices are hard-coded per platform
284 and no sanity checks for the required tools are performed.
287 Clean-room procedures dictate that when certain factors change, old
288 builds should be scrapped and new builds configured. This is the main
289 reason for requiring a scratch directory; to promote consistent,
290 reliable and clean software builds. The following is a short list of
291 some of the reasons why someone may choose to scrap an existing build:
293 * configure with different options
295 * subversion working dir is updated and you want configure to
296 re-evaluate working dir metadata.
298 * build corruption is suspected
300 There are generally two methods for scrapping a build. The `build'
301 directory can be recursively removed which has the effect of loosing
302 your existing configuration but does guarantee no residuals are left
303 behind. The other method is to ask the build system to perform an `make
304 xclean'. This is known to work well but will leave empty directories
305 behind. However, the configuration is left intact.
310 Build main product. All necessary dependencies are also built if
315 Parallel builds may optionally be enabled. Be aware that while a
316 parallel build may save time on systems with additional cores, the
317 output is often mixed, overlapped and sometimes even corrupted with
318 binary characters. Thus if you experience a build issue, you should
319 clean and redo the build in default serial mode to produce a readable
320 log. The following command allows for up to 4 concurrent jobs via make:
327 The build system supports passing many kinds of targets some of which
328 become very useful in normal development cycles. The targets by
329 convention are lower-case words passed to `make'. Global targets are
330 one-word targets. Scoped targets are usually two-words separated by a
337 Alias for `make build'.
340 Build main product. All necessary dependencies are also built if
344 Clean all build output excluding contrib modules. Configuration is
348 Perform final product(s) install. This will install build
349 products to a standard directory or one specified via `configure
353 Perform final product(s) uninstall. This will uninstall any
354 products which may have been previously installed.
357 Clean all build output including contrib modules. Configuration is
361 Build auto-generated project documentation. Various articles are
362 produced and may be found in `build/doc/articles'.
365 Print list of available makefile vars report targets. These
366 reports detail var definitions and expanded values used by the
367 build system. For experts only.
370 Convenience target which aggregates all reports. For experts only.
372 5.4.2 General Modules
373 ---------------------
375 General modules such as `libhb', `test' and `gtk' have the following
382 Clean build output for MODULE.
384 5.4.3 Contrib Modules
385 ---------------------
387 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
388 `lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate',
389 `libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have
390 the following scoped targets:
393 Download source tarball from the Internet and save to
394 `TOP/downloads' directory. No check-summing is performed.
396 `make MODULE.extract'
397 Extract source tarball into `build' tree.
400 Apply appropriate patches (if any) to module sources.
402 `make MODULE.configure'
403 Configure module sources. This usually invokes autotool configure.
406 Build module. This usually invokes autotool build.
408 `make MODULE.install'
409 Install module products such as headers and libraries into `build'
410 tree. This usually invokes autotool install.
412 `make MODULE.uninstall'
413 Uninstall module products; generally the reverse of install. This
414 usually invokes autotool uninstall.
417 Clean module; generally the reverse of build. This usually
418 invokes autotool clean.
421 Extra clean module; first invokes uninstall then recursively
422 removes the module build directory.
424 5.4.4 Contrib Touch and Untouch
425 -------------------------------
427 Also available are some very granular targets which help force builds
428 from specific cycle points. The following targets are available to
429 touch and untouch the respective module target; this will force the
430 build system to treat the target as satisfied after a touch or
431 unsatisfied after an untouch:
433 * make MODULE.extract.touch
435 * make MODULE.extract.untouch
437 * make MODULE.patch.touch
439 * make MODULE.patch.untouch
441 * make MODULE.configure.touch
443 * make MODULE.configure.untouch
445 * make MODULE.build.touch
447 * make MODULE.build.untouch
449 * make MODULE.install.touch
451 * make MODULE.install.untouch
453 5.4.5 Contrib Aggregates
454 ------------------------
456 For convenience, the following targets aggregate the all contrib
457 modules' respective targets together:
461 * make contrib.extract
465 * make contrib.configure
469 * make contrib.install
471 * make contrib.uninstall
475 * make contrib.xclean
480 If the need arises to override settings in the build system
481 (essentially gnu-make variables) the recommended method is to create
482 optional include files which are automatically included if present and
483 follow this naming convention; Do not check these files into the
487 Custom makevar definitions outside `build'. Suitable for settings
488 which apply across all builds for a particular checkout; or which
489 survives manual removal of `build'.
492 Custom make rules outside `build'. Suitable for rules which apply
493 across all builds for a particular checkout; or which survives
494 manual removal of `build'.
496 `_BUILD_/GNUmakefile.custom.defs'
497 Custom makevar definitions specific to a `build' directory.
499 `_BUILD_/GNUmakefile.custom.rules'
500 Custom makevar rules specific to a `build' directory.
503 The purpose is to allow a place to store local build settings for
504 testing, tweaking, and experimenting with build configuration without
505 losing your settings if `configure' is invoked; ie: `configure' would
506 overwrite `GNUmakefile' and any customizations contained therein would
507 be lost. Here is a short example of what the contents of
508 `_SRC_/custom.defs' might contain:
510 ## bump to gcc-4.2 in current path
511 GCC.gcc = /usr/bin/gcc-4.2
513 ## replace optimize for 'speed' with more aggressive settings
514 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
516 See also `make report.help' which displays a set of reports used to
522 When troubleshooting build issues, the following files relative to the
523 `build/' directory may be especially useful:
526 Top-level makefile which contains build settings generated via
529 `log/config.info.txt'
530 Record of output from configure.
532 `log/config.verbose.txt'
533 Record of verbose output from configure.
536 Record of output from `configure --launch'. Similar output may be
537 recorded using `make' depending on which shell is in use, eg:
538 `make >& log/build.txt' or `make > log/build.txt 2>&1'.
540 `log/xcodemake.env.txt'
541 Environment (variables) dump as seen when Xcode forks `make'.
544 Appendix A Project Repository Details
545 *************************************
547 url: svn://svn.handbrake.fr/HandBrake/trunk
548 root: svn://svn.handbrake.fr/HandBrake
550 uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
552 date: 2010-09-26 09:13:48 -0700