diff options
Diffstat (limited to 'doc/BUILD-Mac')
| -rw-r--r-- | doc/BUILD-Mac | 623 |
1 files changed, 623 insertions, 0 deletions
diff --git a/doc/BUILD-Mac b/doc/BUILD-Mac new file mode 100644 index 000000000..6dc74692d --- /dev/null +++ b/doc/BUILD-Mac @@ -0,0 +1,623 @@ +Build Guide for HandBrake svn2252 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 Touch and Untouch + 5.4.5 Contrib Aggregates + 5.5 Customizing Make + 5.6 Universal Binaries +6 Building via Xcode + 6.1 Checkout Sources + 6.2 Build + 6.3 External Targets + 6.4 User-Defined Settings +Appendix A Project Repository Details + + +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. Upon completion of the following commands you +should have a fresh build of HandBrake. Further instructions are +available beginning with *Note overview:: which describes procedures +suitable for repeating builds. This chapter should be skipped by those +seeking more than a minimalist build. + + svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk + cd hb-trunk + ./configure --launch + +The special option `--launch' selects 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/build.txt' + + * echo build output + + * print elapsed time + + * indicate if build ultimately succeeded or failed + +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. + + ./configure + +Configure will automatically create a scratch build directory `build' +unless you use GNU-style build procedures and first `cd' to a directory +other than top-level source. Additionally you may specify use `--build' +to specify the directory. The name of the directory is arbitrary but it +is recommended to use something which indicates transient files which +are not checked into the repository. + +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. + +`--src=DIR' + Specify top-level source directory for HandBrake sources. + +`--build=DIR' + Specify destination directory for final product install. The + default is to use either `build' if in the top-level source + directory, otherwise `.' + +`--prefix=DIR' + Specify destination directory for final product install. This + defaults to a reasonable platform-specific value. + +`--launch' + All-in-one option which launches the build and logs output + automatically. Useful for novices and quickstart procedures. + +`--disable-xcode' + Disable shunting the build through Xcode. If this option is + applied, `HandBrakeCLI' will be produced in a similare fashion as + it is on other platforms; sans Xcode. 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. + + +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'. + +`make report.help' + Print list of available makefile vars report targets. These + reports detail var definitions and expanded values used by the + build system. For experts only. + +`make report.all' + Convenience target which aggregates all reports. For experts only. + +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 Touch and Untouch +------------------------------- + +Also available are some very granular targets which help force builds +from specific cycle points. The following targets are available to +touch and untouch the respective module target; this will force the +build system to treat the target as satisfied after a touch or +unsatisfied after an untouch: + + * make MODULE.extract.touch + + * make MODULE.extract.untouch + + * make MODULE.patch.touch + + * make MODULE.patch.untouch + + * make MODULE.configure.touch + + * make MODULE.configure.untouch + + * make MODULE.build.touch + + * make MODULE.build.untouch + + * make MODULE.install.touch + + * make MODULE.install.untouch + +5.4.5 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 +optional include files which are automatically included if present and +follow this naming convention; Do not check these files into the +respository: + +`_SRC_/custom.defs' + Custom makevar definitions outside `build'. Suitable for settings + which apply across all builds for a particular checkout; or which + survives manual removal of `build'. + +`_SRC_/custom.rules' + Custom make rules outside `build'. Suitable for rules which apply + across all builds for a particular checkout; or which survives + manual removal of `build'. + +`_BUILD_/GNUmakefile.custom.defs' + Custom makevar definitions specific to a `build' directory. + +`_BUILD_/GNUmakefile.custom.rules' + Custom makevar rules specific to a `build' directory. + + +The 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 +`_SRC_/custom.defs' 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 + +See also `make report.help' which displays a set of reports used to +dump makefile vars. + +5.6 Universal Binaries +====================== + +This section outlines convenience procedures for creating Universal +Binaries for all the architectures. + + Note: The dummy (container) build configuration uses + `--disable-xcode'; but the nested architecture builds will all + make full use of Xcode. + +Create a dummy (container) build configuration and use it to launch a +nested-build for each architecture serially; optionally you may +substitute `make ub.build.serial' for `make ub.build.parallel' if your +machine has the horsepower: + + ./configure --disable-xcode + cd build/ + make ub.build.serial + make ub.combine + +To specify a subset of architectures to be built first create/edit +`_SRC_/custom.defs' with the following override to build UB for `i386' +and `x86_64' before invoking `make': + + ## prefer i386 (order is important) + UB.archs = i386 x86_64 + +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 host native architecture. Build + directory is `build.standard' . The standard variant produces + optimized code without debug information. + +`standard.i386' + This configuration will build i386 architecture. Build directory + is `build.standard.i386' . + +`standard.x86_64' + This configuration will build x86_64 architecture. Build directory + is `build.standard.x86_64' . + +`standard.ppc' + This configuration will build ppc architecture. Build directory is + `build.standard.ppc' . + +`standard.ppc64' + This configuration will build ppc64 architecture. Build directory + is `build.standard.ppc64' . + +`debug' + This configuration will build host native architecture. Build + directory is `build.debug' . The debug variant produces + unoptimized code with debug information. + +`debug.i386' + This configuration will build i386 architecture. Build directory + is `build.debug.i386' . The debug variant produces unoptimized + code with debug information. + +`debug.x86_64' + This configuration will build x86_64 architecture. Build directory + is `build.debug.x86_64' . The debug variant produces unoptimized + code with debug information. + +`debug.ppc' + This configuration will build ppc architecture. Build directory is + `build.debug.ppc' . The debug variant produces unoptimized code + with debug information. + +`debug.ppc64' + This configuration will build ppc64 architecture. Build directory + is `build.debug.ppc64' . The debug variant produces unoptimized + code with debug information. + +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 (scratch) directory for each configuration. + +`EXTERNAL_JOBS' + Specifies the concurrency factor for the external build system + when builds are launched from within Xcode. Modify for faster + external builds if your system has the horsepower and resources. + Specifying a value greater than the number of CPU cores (or + virtual cores) in your system is unlikely to produce gains and + will needlessly consume extra resources. + +`EXTERNAL_METHOD' + Do not modify; Used for internal/external build coordination and + must always be `xcode'. + +`EXTERNAL_SRC' + Specifies the top-level source directory for HandBrake. + + +Appendix A Project Repository Details +************************************* + + url: svn://svn.handbrake.fr/HandBrake/trunk + root: svn://svn.handbrake.fr/HandBrake + branch: trunk + uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5 + rev: 2252 + date: 2009-03-10 18:43:11 -0400 + type: developer + |