Guide to Building HandBrake svn2213 (2009030301) on Mac OS X ************************************************************ Table of Contents ***************** 1 Introduction 2 Prerequisites 3 QuickStart 4 Overview 5 Building via Terminal 5.1 Checkout Sources 5.2 Configure 5.3 Build 5.4 Make Targets 5.4.1 Global 5.4.2 General Modules 5.4.3 Contrib Modules 5.4.4 Contrib Aggregates 5.5 Customizing Make 6 Building via Xcode 6.1 Checkout Sources 6.2 Build 6.3 External Targets 6.4 User-Defined Settings 1 Introduction ************** This guide documents the recommended process to build HandBrake on Mac OS X hosts from the official source-code repository. Building from any other source is not supported. 2 Prerequisites *************** Building on Mac OS X is well supported. It is the reference platform for HandBrake. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible: * Mac Intel hardware * Mac OS X 10.5.6 * Xcode-3.1.2 * gcc 4.0.1 (Apple Inc. build 5490) * yasm 0.7.2.2153 (for i386 and x86_64 architectures) Note: It is recommended to use the platform distribution's bundled compiler for maximum C++ compatibility. If you build with a custom compiler it will likely introduce non-standard runtime requirements. There are of course many valid reasons to build with unbundled compilers, but be aware it is generally unsupported and left as an exercise to the reader. The following general tools are used on various platforms and it is recommended you use these versions or similar: * subversion - 1.5.5 * python - Python 2.4.6 * curl - curl 7.19.3 (or wget) * m4 - GNU M4 1.4.6 * make - GNU Make 3.81 * patch - Patch 2.5.8 * tar - GNU tar 1.15.1 * wget - GNU Wget 1.11.4 (or curl) 3 QuickStart ************ This chapter is for building from a terminal/shell environment in as few commands as possible. If more flexibility is required you should skip this chapter and jump to *Note overview::. svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk cd hb-trunk ./configure --launch The special option `--launch' selected launch mode and performs the following steps: * assert scratch directory `build/' does not exist * create scratch directory `build/' * change to directory `build/' * launch `make' * capture build output to `build/log.txt' * echo build output 4 Overview ********** The two general methods to build on Mac OS X are building from terminal or Xcode. The preferred method for automated and repeatable builds is to use the terminal. Otherwise the choice is generally up to the individual. In essence, the terminal actually invokes `xcodebuild' to build the very same targets contained in the Xcode project. 5 Building via Terminal *********************** 5.1 Checkout Sources ==================== Checkout HandBrake from the official source-code repository. svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk cd hb-trunk Sources are checked out from the `trunk' branch. This document was generated from that very branch, and for example purposes, we will use exactly the same branch. If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to use Subversion 1.5.0 or higher. Lower versions should also work. 5.2 Configure ============= Configure the build system. rm -fr build/ mkdir build/ cd build/ ../configure Create a scratch directory which will contain all files created during the build process. The directory name is arbitrary but we recommend something simple and descriptive. One directory is required for each distinctly configured build. We name our directory `build' for example purposes. The `configure' utility accepts many options. It is recommended that you specify `--help' for the complete list of options. The following options are also documented here: `--help' List available options. `--prefix=PREFIX' Specify destination directory for final product install. This defaults to a reasonable platform-specific value. `--disable-xcode' Disable driving the build through Xcode. If this option is disabled only `HandBrakeCLI' will be produced and Xcode will not be invoked. Mac OS X only. `--disable-gtk' Disable building the GTK GUI on applicable platforms such as Linux. `--debug=MODE' Select debug mode. Must be one of `none', `min', `std', `max'. This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'. `--optimize=MODE' Select optimize mode. Must be one of `none', `speed', `size'. This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'. `--arch=MODE' Select build architecture. The available architectures vary by platform. Most platforms support exactly one architecture except Mac OS X which has support for various universal binary architectures. The available choices are hard-coded per platform and no sanity checks for the required tools are performed. `--gcc=EXE' Specify the `gcc' executable to use where EXE is the executable name which is either absolute or environment `PATH' is searched accordingly. Clean-room procedures dictate that when certain factors change, old builds should be scrapped and new builds configured. This is the main reason for requiring a scratch directory; to promote consistent, reliable and clean software builds. The following is a short list of some of the reasons why someone may choose to scrap an existing build: * configure with different options * subversion working dir is updated and you want configure to re-evaluate working dir metadata. * build corruption is suspected There are generally two methods for scrapping a build. The `build' directory can be recusrively removed which has the effect of loosing your existing configuration but does guarantee no residuals are left behind. The other method is to ask the build system to perform an `make xclean'. This is known to work well but will leave empty directories behind. However, the configuration is left intact. 5.3 Build ========= Build main product. All necessary dependencies are also built if required. make Parallel builds may optionally be enabled. Be aware that while a parallel build may save time on systems with additional cores, the output is often mixed, overlapped and sometimes even corrupted with binary characters. Thus if you experience a build issue, you should clean and redo the build in default serial mode to produce a readable log. The following command allows for up to 4 concurrent jobs via make: make -j4 5.4 Make Targets ================ The build system supports passing many kinds of targets some of which become very useful in normal development cycles. The targets by convention are lower-case words passed to `make'. Global targets are one-word targets. Scoped targets are usually two-words seperated by a period. 5.4.1 Global ------------ `make' Alias for `make build'. `make build' Build main product. All necessary dependencies are also built if required. `make clean' Clean all build output excluding contrib modules. Configuration is retained. `make install' Perform final product(s) install. This will install build products to a standard directory or one specified via `configure --prefix' option. `make uninstall' Perform final product(s) uninstall. This will uninstall any products which may have been previously installed. `make xclean' Clean all build output including contrib modules. Configuration is retained. `make doc' Build auto-generated project documentation. Various articles are produced and may be found in `build/doc/articles'. 5.4.2 General Modules --------------------- General modules such as `libhb', `test' and `gtk' have the following scoped targets: `make MODULE.build' Build MODULE. `make MODULE.clean' Clean build output for MODULE. 5.4.3 Contrib Modules --------------------- Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg', `lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg', `libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264', `xvidcore' and `zlib' have the following scoped targets: `make MODULE.fetch' Download source tarball from the Internet and save to `TOP/downloads' directory. No checksumming is performed. `make MODULE.extract' Extract source tarball into `build' tree. `make MODULE.patch' Apply appropriate patches (if any) to module sources. `make MODULE.configure' Configure module sources. This usually invokes autotool configure. `make MODULE.build' Build module. This usually invokes autotool build. `make MODULE.install' Install module products such as headers and libraries into `build' tree. This usually invokes autotool install. `make MODULE.uninstall' Uninstall module products; generally the reverse of install. This usually invokes autotool uninstall. `make MODULE.clean' Clean module; generally the reverse of build. This usually invokes autotool clean. `make MODULE.xclean' Extra clean module; first invokes uninstall then recursively removes the module build directory. 5.4.4 Contrib Aggregates ------------------------ For convenience, the following targets aggregate the all contrib modules' respective targets together: * make contrib.fetch * make contrib.extract * make contrib.patch * make contrib.configure * make contrib.build * make contrib.install * make contrib.uninstall * make contrib.clean * make contrib.xclean 5.5 Customizing Make ==================== If the need arises to override settings in the build system (essentially gnu-make variables) the recommended method is to create/edit the optional include file `build/GNUmakefile.custom' which sits adjacent to the top-level makefile. Do not check this file into the respository. The sole purpose is to allow a place to store local build settings for testing, tweaking, and experimenting with build configuration without losing your settings if `configure' is invoked; ie: `configure' would overwrite `GNUmakefile' and any customizations contained therein would be lost. Here is a short example of what the contents of `build/GNUmakefile.custom' might contain: ## bump to gcc-4.2 in current path GCC.gcc = gcc-4.2 ## replace optimize for 'speed' with more agressive settings GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2 6 Building via Xcode ******************** 6.1 Checkout Sources ==================== Checkout HandBrake from the official source-code repository. svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk cd hb-trunk Sources are checked out from the `trunk' branch. This document was generated from that very branch, and for example purposes, we will use exactly the same branch. If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to use Subversion 1.5.0 or higher. Lower versions should also work. 6.2 Build ========= In Xcode perform the following steps to build the default configuration: * open `macosx/HandBrake.xcodeproj' * select active configuration standard * select active target HandBrake * click Build or Build and Go The first build (on an empty `build' directory) will take a bit of time. You may use the Build Results window to observe progress. The most time-consuming part of the build is when the external build system (essentially the terminal method) is triggered by Xcode and a substantial amount of log transcript ensues. Much of that transcript are warnings and errors that are part of the normal build process for 3rd-party contributed modules so in general you need not do anything. However, if Xcode itself reports the build failed, then you must take corrective action. Unfortunately, due to limitations of Xcode we do not have hooks in place to offer finer-grained control over per-module make actions for the (external) build system. Thus, you will have to use terminal to accomplish those tasks. Just `cd' into the build directory which is associated with your active configuration and perform any necessary `make' commands. Be careful not to issue commands from the terminal simultaneously with Xcode tasks as that will confuse both Xcode and make and likely corrupt your build directory. When you click clean in Xcode it will not perform an external build clean. Basically HandBrakeCLI and HandBrake.app are the only products which have full Xcode iterative development flexibility. Each configuration uses a different `build' directory. This makes it possible to build each configuration and switch between them without losing their respective build state. The description of each configuration and the name convention for build directories are as follows: `standard' This configuration will build to the host native architecture. Build directory is `build.standard' . The standard variant produces optimized code without debug information. `debug' This configuration will build to the host native architecture. Build directory is `build.standard' . The debug variant produces unoptimized code with debug information. `standard.i386' This configuration is used to build for the i386 architecture. Build directory is `build.standard.i386' . `standard.x86_64' This configuration is used to build for the x86_64 architecture. Build directory is `build.standard.x86_64' . `standard.ppc' This configuration is used to build for the ppc architecture. Build directory is `build.standard.ppc' . `standard.ppc64' This configuration is used to build for the ppc64 architecture. Build directory is `build.standard.ppc64' . 6.3 External Targets ==================== The following external targets appear in the Xcode project and perform build and clean actions. `external' Target maps to `make build' and `make clean' for everything Xcode products depend upon from the external build system. `libhb' Target maps to `make libhb.build' and `make libhb.clean'. `contrib' Target maps to `make contrib.build' and `make contrib.xclean'. 6.4 User-Defined Settings ========================= The following user defined settings are used in Xcode project for the external build system: `EXTERNAL_BUILD' Specifies the build location for each configuration. It is highly recommended the locations always evaluate to a unique pathname when factoring the configuration name. `EXTERNAL_JOBS' Specifies the concurrency factor for the external build system when builds are launched from within Xcode. This variable is meant to be customized by the developer for faster builds if the host supports it. `EXTERNAL_METHOD' This variable is used for internal/external build coordination and must always be `xcode'. `EXTERNAL_PROJECT' Specifies the directory which is top of HandBrake source tree.