1 Build Guide for HandBrake svn3349 on Mac OS X
2 *********************************************
11 5 Building via Terminal
19 5.4.4 Contrib Touch and Untouch
20 5.4.5 Contrib Aggregates
22 5.6 Universal Binaries
23 6 Building via Xcode.app
27 6.4 User-Defined Settings
29 Appendix A Project Repository Details
35 This guide documents the recommended process to build HandBrake on
36 Mac OS X hosts from the official source-code repository. Building from
37 any other source is not supported.
42 Building on Mac OS X is well supported. It is the reference platform
43 for HandBrake. The following are the recommended specifications for
44 this platform; but is not necessarily the only configuration that is
53 * gcc 4.0.1 (Apple Inc. build 5490)
55 * yasm 0.8.0.2194 (for i386 and x86_64 architectures)
57 Note: It is recommended to use the platform distribution's bundled
58 compiler for maximum C++ compatibility. If you build with a custom
59 compiler it will likely introduce non-standard runtime
60 requirements. There are of course many valid reasons to build with
61 unbundled compilers, but be aware it is generally unsupported and
62 left as an exercise to the reader.
64 The following general tools are used on various platforms and it is
65 recommended you use these versions or similar:
69 * python - Python 2.4.6
71 * curl - curl 7.19.4 (or wget)
75 * make - GNU Make 3.81
79 * tar - GNU tar 1.15.1
81 * wget - GNU Wget 1.11.4 (or curl)
86 This chapter is for building from a terminal/shell environment in as
87 few commands as possible. Upon completion of the following commands you
88 should have a fresh build of HandBrake. Further instructions are
89 available beginning with *Note overview:: which describes procedures
90 suitable for repeating builds. This chapter should be skipped by those
91 seeking more than a minimalist build.
93 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
97 The special option `--launch' selects launch mode and performs the
100 * assert scratch directory `build/' does not exist
102 * create scratch directory `build/'
104 * change to directory `build/'
108 * capture build output to `build/log/build.txt'
114 * indicate if build ultimately succeeded or failed
119 The two general methods to build on Mac OS X are from terminal or
120 Xcode.app. The preferred method for automated and repeatable builds is
121 to use the terminal. Otherwise the choice is generally up to the
122 individual. To be extra clear, building from the terminal by default
123 actually invokes `xcodebuild' to build the very same targets contained
124 in the Xcode project. Think of it as building with Xcode but without
127 5 Building via Terminal
128 ***********************
133 Checkout HandBrake from the official source-code repository.
135 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
138 Sources are checked out from the `trunk' branch. This document was
139 generated from that very branch, and for example purposes, we will use
140 exactly the same branch.
142 If you have write-access to the repository, then you may add the
143 appropriate login/password information as needed. It is recommended to
144 use Subversion 1.5.0 or higher. Lower versions should also work.
149 Configure the build system.
153 Configure will automatically create a scratch build directory `build'
154 unless you use GNU-style build procedures and first `cd' to a directory
155 other than top-level source. Additionally you may use `--build' to
156 specify the directory. The name of the directory is arbitrary but it is
157 recommended to use something which indicates transient files which are
158 not checked into the repository.
160 The `configure' utility accepts many options. It is recommended that
161 you specify `--help' for the complete list of options. The following
162 options are also documented here:
165 List available options.
168 Specify top-level source directory for HandBrake sources.
171 Specify destination directory for final product install. The
172 default is to use either `build' if in the top-level source
173 directory, otherwise `.'
176 Specify destination directory for final product install. This
177 defaults to a reasonable platform-specific value.
180 All-in-one option which launches the build and logs output
181 automatically. Useful for novices and quick-start procedures.
184 Disable shunting the build through `xcodebuild'. If this option is
185 applied, `HandBrakeCLI' will be produced in a similar fashion as
186 it is on other platforms; sans Xcode and the Cocoa application
187 will not be produced. Mac OS X only.
190 Disable building the GTK GUI on applicable platforms such as
194 Select debug mode. Must be one of `none', `min', `std', `max'.
195 This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
198 Select optimize mode. Must be one of `none', `speed', `size'.
199 This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
202 Select build architecture. The available architectures vary by
203 platform. Most platforms support exactly one architecture except
204 Mac OS X which has support for various universal binary
205 architectures. The available choices are hard-coded per platform
206 and no sanity checks for the required tools are performed.
209 Clean-room procedures dictate that when certain factors change, old
210 builds should be scrapped and new builds configured. This is the main
211 reason for requiring a scratch directory; to promote consistent,
212 reliable and clean software builds. The following is a short list of
213 some of the reasons why someone may choose to scrap an existing build:
215 * configure with different options
217 * subversion working dir is updated and you want configure to
218 re-evaluate working dir metadata.
220 * build corruption is suspected
222 There are generally two methods for scrapping a build. The `build'
223 directory can be recursively removed which has the effect of loosing
224 your existing configuration but does guarantee no residuals are left
225 behind. The other method is to ask the build system to perform an `make
226 xclean'. This is known to work well but will leave empty directories
227 behind. However, the configuration is left intact.
232 Build main product. All necessary dependencies are also built if
237 Parallel builds may optionally be enabled. Be aware that while a
238 parallel build may save time on systems with additional cores, the
239 output is often mixed, overlapped and sometimes even corrupted with
240 binary characters. Thus if you experience a build issue, you should
241 clean and redo the build in default serial mode to produce a readable
242 log. The following command allows for up to 4 concurrent jobs via make:
249 The build system supports passing many kinds of targets some of which
250 become very useful in normal development cycles. The targets by
251 convention are lower-case words passed to `make'. Global targets are
252 one-word targets. Scoped targets are usually two-words separated by a
259 Alias for `make build'.
262 Build main product. All necessary dependencies are also built if
266 Clean all build output excluding contrib modules. Configuration is
270 Perform final product(s) install. This will install build
271 products to a standard directory or one specified via `configure
275 Perform final product(s) uninstall. This will uninstall any
276 products which may have been previously installed.
279 Clean all build output including contrib modules. Configuration is
283 Build auto-generated project documentation. Various articles are
284 produced and may be found in `build/doc/articles'.
287 Print list of available makefile vars report targets. These
288 reports detail var definitions and expanded values used by the
289 build system. For experts only.
292 Convenience target which aggregates all reports. For experts only.
294 5.4.2 General Modules
295 ---------------------
297 General modules such as `libhb', `test' and `gtk' have the following
304 Clean build output for MODULE.
306 5.4.3 Contrib Modules
307 ---------------------
309 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
310 `lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate',
311 `libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have
312 the following scoped targets:
315 Download source tarball from the Internet and save to
316 `TOP/downloads' directory. No check-summing is performed.
318 `make MODULE.extract'
319 Extract source tarball into `build' tree.
322 Apply appropriate patches (if any) to module sources.
324 `make MODULE.configure'
325 Configure module sources. This usually invokes autotool configure.
328 Build module. This usually invokes autotool build.
330 `make MODULE.install'
331 Install module products such as headers and libraries into `build'
332 tree. This usually invokes autotool install.
334 `make MODULE.uninstall'
335 Uninstall module products; generally the reverse of install. This
336 usually invokes autotool uninstall.
339 Clean module; generally the reverse of build. This usually
340 invokes autotool clean.
343 Extra clean module; first invokes uninstall then recursively
344 removes the module build directory.
346 5.4.4 Contrib Touch and Untouch
347 -------------------------------
349 Also available are some very granular targets which help force builds
350 from specific cycle points. The following targets are available to
351 touch and untouch the respective module target; this will force the
352 build system to treat the target as satisfied after a touch or
353 unsatisfied after an untouch:
355 * make MODULE.extract.touch
357 * make MODULE.extract.untouch
359 * make MODULE.patch.touch
361 * make MODULE.patch.untouch
363 * make MODULE.configure.touch
365 * make MODULE.configure.untouch
367 * make MODULE.build.touch
369 * make MODULE.build.untouch
371 * make MODULE.install.touch
373 * make MODULE.install.untouch
375 5.4.5 Contrib Aggregates
376 ------------------------
378 For convenience, the following targets aggregate the all contrib
379 modules' respective targets together:
383 * make contrib.extract
387 * make contrib.configure
391 * make contrib.install
393 * make contrib.uninstall
397 * make contrib.xclean
402 If the need arises to override settings in the build system
403 (essentially gnu-make variables) the recommended method is to create
404 optional include files which are automatically included if present and
405 follow this naming convention; Do not check these files into the
409 Custom makevar definitions outside `build'. Suitable for settings
410 which apply across all builds for a particular checkout; or which
411 survives manual removal of `build'.
414 Custom make rules outside `build'. Suitable for rules which apply
415 across all builds for a particular checkout; or which survives
416 manual removal of `build'.
418 `_BUILD_/GNUmakefile.custom.defs'
419 Custom makevar definitions specific to a `build' directory.
421 `_BUILD_/GNUmakefile.custom.rules'
422 Custom makevar rules specific to a `build' directory.
425 The purpose is to allow a place to store local build settings for
426 testing, tweaking, and experimenting with build configuration without
427 losing your settings if `configure' is invoked; ie: `configure' would
428 overwrite `GNUmakefile' and any customizations contained therein would
429 be lost. Here is a short example of what the contents of
430 `_SRC_/custom.defs' might contain:
432 ## bump to gcc-4.2 in current path
433 GCC.gcc = /usr/bin/gcc-4.2
435 ## replace optimize for 'speed' with more aggressive settings
436 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
438 See also `make report.help' which displays a set of reports used to
441 5.6 Universal Binaries
442 ======================
444 This section outlines convenience procedures for creating Universal
445 Binaries for all the architectures.
447 Note: The dummy (container) build configuration uses
448 `--disable-xcode'; but the nested architecture builds will all
449 make full use of Xcode.
451 Create a dummy (container) build configuration and use it to launch a
452 nested-build for each architecture serially; optionally you may
453 substitute `make ub.build.serial' for `make ub.build.parallel' if your
454 machine has the horsepower:
456 ./configure --disable-xcode
461 To specify a subset of architectures to be built first create/edit
462 `_SRC_/custom.defs' with the following override to build UB for `i386'
463 and `x86_64' before invoking `make':
465 ## prefer i386 (order is important)
466 UB.archs = i386 x86_64
468 6 Building via Xcode.app
469 ************************
474 Checkout HandBrake from the official source-code repository.
476 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
479 Sources are checked out from the `trunk' branch. This document was
480 generated from that very branch, and for example purposes, we will use
481 exactly the same branch.
483 If you have write-access to the repository, then you may add the
484 appropriate login/password information as needed. It is recommended to
485 use Subversion 1.5.0 or higher. Lower versions should also work.
490 Open Xcode.app from a terminal by using the `open' command which passes
491 your shell environment and its `PATH' setting to Xcode. Do not attempt
492 to launch Xcode.app from Finder or by using Finder to open
493 `HandBrake.xcodeproj' - doing so will defeat any custom path settings
494 which contain required tools.
496 open `macosx/HandBrake.xcodeproj'
498 Once the HandBrake Xcode project is open, perform the following steps
499 to build the default configuration:
501 * select active configuration standard
503 * select active target HandBrake
505 * click Build or Build and Go
507 When using Build and Go, xcode launches the application under the gdb
508 debugger. gdb will encounter a trap when starting the program. This
509 trap is harmless and you should just 'continue'. For the curious, the
510 trap occurs because we add some values to the environment with setenv,
511 then do a brain transplant with execv. Restarting the application with
512 execv triggers the trap.
514 The first build (on an empty `build' directory) will take a bit of
515 time. You may use the Build Results window to observe progress. The
516 most time-consuming part of the build is when the external build system
517 (essentially the terminal method) is triggered by Xcode and a
518 substantial amount of log transcript ensues. Much of that transcript
519 are warnings and errors that are part of the normal build process for
520 3rd-party contributed modules so in general you need not do anything.
521 However, if Xcode itself reports the build failed, then you must take
524 Unfortunately, due to limitations of Xcode we do not have hooks in
525 place to offer finer-grained control over per-module make actions for
526 the (external) build system. Thus, you will have to use terminal to
527 accomplish those tasks. Just `cd' into the build directory which is
528 associated with your active configuration and perform any necessary
529 `make' commands. Be careful not to issue commands from the terminal
530 simultaneously with Xcode tasks as that will confuse both Xcode and
531 make and likely corrupt your build directory.
533 When you click clean in Xcode it will not perform an external build
534 clean. Basically HandBrakeCLI and HandBrake.app are the only products
535 which have full Xcode iterative development flexibility.
537 Each configuration uses a different `build' directory. This makes it
538 possible to build each configuration and switch between them without
539 losing their respective build state. The description of each
540 configuration and the name convention for build directories are as
544 This configuration will build host native architecture. Build
545 directory is `build.standard' . The standard variant produces
546 optimized code without debug information.
549 This configuration will build i386 architecture. Build directory
550 is `build.standard.i386' .
553 This configuration will build x86_64 architecture. Build directory
554 is `build.standard.x86_64' .
557 This configuration will build ppc architecture. Build directory is
558 `build.standard.ppc' .
561 This configuration will build ppc64 architecture. Build directory
562 is `build.standard.ppc64' .
565 This configuration will build host native architecture. Build
566 directory is `build.debug' . The debug variant produces
567 unoptimized code with debug information.
570 This configuration will build i386 architecture. Build directory
571 is `build.debug.i386' . The debug variant produces unoptimized
572 code with debug information.
575 This configuration will build x86_64 architecture. Build directory
576 is `build.debug.x86_64' . The debug variant produces unoptimized
577 code with debug information.
580 This configuration will build ppc architecture. Build directory is
581 `build.debug.ppc' . The debug variant produces unoptimized code
582 with debug information.
585 This configuration will build ppc64 architecture. Build directory
586 is `build.debug.ppc64' . The debug variant produces unoptimized
587 code with debug information.
592 The following external targets appear in the Xcode project and perform
593 build and clean actions.
596 Target maps to `make build' and `make clean' for everything Xcode
597 products depend upon from the external build system.
600 Target maps to `make libhb.build' and `make libhb.clean'.
603 Target maps to `make contrib.build' and `make contrib.xclean'.
606 6.4 User-Defined Settings
607 =========================
609 The following user defined settings are used in Xcode project for the
610 external build system:
613 Specifies the build (scratch) directory for each configuration.
616 Specifies the concurrency factor for the external build system
617 when builds are launched from within Xcode. Modify for faster
618 external builds if your system has the horsepower and resources.
619 Specifying a value greater than the number of CPU cores (or
620 virtual cores) in your system is unlikely to produce gains and
621 will needlessly consume extra resources.
624 Do not modify; Used for internal/external build coordination and
625 must always be `xcode'.
628 Specifies the top-level source directory for HandBrake.
634 When troubleshooting build issues, the following files relative to the
635 `build/' directory may be especially useful:
638 Top-level makefile which contains build settings generated via
641 `log/config.info.txt'
642 Record of output from configure.
644 `log/config.verbose.txt'
645 Record of verbose output from configure.
648 Record of output from `configure --launch'. Similar output may be
649 recorded using `make' depending on which shell is in use, eg:
650 `make >& log/build.txt' or `make > log/build.txt 2>&1'.
652 `log/xcodemake.env.txt'
653 Environment (variables) dump as seen when Xcode forks `make'.
656 A note about gdb: We perform an extra execv when starting the
657 application. This triggers a trap in gdb. It is harmless. You should
658 just 'continue' from the trap.
660 Appendix A Project Repository Details
661 *************************************
663 url: svn://svn.handbrake.fr/HandBrake/trunk
664 root: svn://svn.handbrake.fr/HandBrake
666 uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
668 date: 2010-06-02 09:49:18 -0700