1 Build Guide for HandBrake svn2591 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 The first build (on an empty `build' directory) will take a bit of
508 time. You may use the Build Results window to observe progress. The
509 most time-consuming part of the build is when the external build system
510 (essentially the terminal method) is triggered by Xcode and a
511 substantial amount of log transcript ensues. Much of that transcript
512 are warnings and errors that are part of the normal build process for
513 3rd-party contributed modules so in general you need not do anything.
514 However, if Xcode itself reports the build failed, then you must take
517 Unfortunately, due to limitations of Xcode we do not have hooks in
518 place to offer finer-grained control over per-module make actions for
519 the (external) build system. Thus, you will have to use terminal to
520 accomplish those tasks. Just `cd' into the build directory which is
521 associated with your active configuration and perform any necessary
522 `make' commands. Be careful not to issue commands from the terminal
523 simultaneously with Xcode tasks as that will confuse both Xcode and
524 make and likely corrupt your build directory.
526 When you click clean in Xcode it will not perform an external build
527 clean. Basically HandBrakeCLI and HandBrake.app are the only products
528 which have full Xcode iterative development flexibility.
530 Each configuration uses a different `build' directory. This makes it
531 possible to build each configuration and switch between them without
532 losing their respective build state. The description of each
533 configuration and the name convention for build directories are as
537 This configuration will build host native architecture. Build
538 directory is `build.standard' . The standard variant produces
539 optimized code without debug information.
542 This configuration will build i386 architecture. Build directory
543 is `build.standard.i386' .
546 This configuration will build x86_64 architecture. Build directory
547 is `build.standard.x86_64' .
550 This configuration will build ppc architecture. Build directory is
551 `build.standard.ppc' .
554 This configuration will build ppc64 architecture. Build directory
555 is `build.standard.ppc64' .
558 This configuration will build host native architecture. Build
559 directory is `build.debug' . The debug variant produces
560 unoptimized code with debug information.
563 This configuration will build i386 architecture. Build directory
564 is `build.debug.i386' . The debug variant produces unoptimized
565 code with debug information.
568 This configuration will build x86_64 architecture. Build directory
569 is `build.debug.x86_64' . The debug variant produces unoptimized
570 code with debug information.
573 This configuration will build ppc architecture. Build directory is
574 `build.debug.ppc' . The debug variant produces unoptimized code
575 with debug information.
578 This configuration will build ppc64 architecture. Build directory
579 is `build.debug.ppc64' . The debug variant produces unoptimized
580 code with debug information.
585 The following external targets appear in the Xcode project and perform
586 build and clean actions.
589 Target maps to `make build' and `make clean' for everything Xcode
590 products depend upon from the external build system.
593 Target maps to `make libhb.build' and `make libhb.clean'.
596 Target maps to `make contrib.build' and `make contrib.xclean'.
599 6.4 User-Defined Settings
600 =========================
602 The following user defined settings are used in Xcode project for the
603 external build system:
606 Specifies the build (scratch) directory for each configuration.
609 Specifies the concurrency factor for the external build system
610 when builds are launched from within Xcode. Modify for faster
611 external builds if your system has the horsepower and resources.
612 Specifying a value greater than the number of CPU cores (or
613 virtual cores) in your system is unlikely to produce gains and
614 will needlessly consume extra resources.
617 Do not modify; Used for internal/external build coordination and
618 must always be `xcode'.
621 Specifies the top-level source directory for HandBrake.
627 When troubleshooting build issues, the following files relative to the
628 `build/' directory may be especially useful:
631 Top-level makefile which contains build settings generated via
634 `log/config.info.txt'
635 Record of output from configure.
637 `log/config.verbose.txt'
638 Record of verbose output from configure.
641 Record of output from `configure --launch'. Similar output may be
642 recorded using `make' depending on which shell is in use, eg:
643 `make >& log/build.txt' or `make > log/build.txt 2>&1'.
645 `log/xcodemake.env.txt'
646 Environment (variables) dump as seen when Xcode forks `make'.
649 Appendix A Project Repository Details
650 *************************************
652 url: svn://svn.handbrake.fr/HandBrake/trunk
653 root: svn://svn.handbrake.fr/HandBrake
655 uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
657 date: 2009-06-21 13:15:04 -0400