--- /dev/null
+Build Guide for HandBrake svn2591 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.app
+ 6.1 Checkout Sources
+ 6.2 Build
+ 6.3 External Targets
+ 6.4 User-Defined Settings
+7 Troubleshooting
+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.7
+
+ * Xcode-3.1.2
+
+ * gcc 4.0.1 (Apple Inc. build 5490)
+
+ * yasm 0.8.0.2194 (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.6.2
+
+ * python - Python 2.4.6
+
+ * curl - curl 7.19.4 (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 from terminal or
+Xcode.app. The preferred method for automated and repeatable builds is
+to use the terminal. Otherwise the choice is generally up to the
+individual. To be extra clear, building from the terminal by default
+actually invokes `xcodebuild' to build the very same targets contained
+in the Xcode project. Think of it as building with Xcode but without
+the GUI.
+
+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 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 quick-start procedures.
+
+`--disable-xcode'
+ Disable shunting the build through `xcodebuild'. If this option is
+ applied, `HandBrakeCLI' will be produced in a similar fashion as
+ it is on other platforms; sans Xcode and the Cocoa application
+ will not be produced. 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 recursively 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 separated 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', `libogg', `libsamplerate',
+`libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have
+the following scoped targets:
+
+`make MODULE.fetch'
+ Download source tarball from the Internet and save to
+ `TOP/downloads' directory. No check-summing 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
+repository:
+
+`_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 = /usr/bin/gcc-4.2
+
+ ## replace optimize for 'speed' with more aggressive 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.app
+************************
+
+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
+=========
+
+Open Xcode.app from a terminal by using the `open' command which passes
+your shell environment and its `PATH' setting to Xcode. Do not attempt
+to launch Xcode.app from Finder or by using Finder to open
+`HandBrake.xcodeproj' - doing so will defeat any custom path settings
+which contain required tools.
+
+ open `macosx/HandBrake.xcodeproj'
+
+Once the HandBrake Xcode project is open, perform the following steps
+to build the default configuration:
+
+ * 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.
+
+
+7 Troubleshooting
+*****************
+
+When troubleshooting build issues, the following files relative to the
+`build/' directory may be especially useful:
+
+`GNUmakefile'
+ Top-level makefile which contains build settings generated via
+ configure.
+
+`log/config.info.txt'
+ Record of output from configure.
+
+`log/config.verbose.txt'
+ Record of verbose output from configure.
+
+`log/build.txt'
+ Record of output from `configure --launch'. Similar output may be
+ recorded using `make' depending on which shell is in use, eg:
+ `make >& log/build.txt' or `make > log/build.txt 2>&1'.
+
+`log/xcodemake.env.txt'
+ Environment (variables) dump as seen when Xcode forks `make'.
+ Mac OS X only.
+
+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: 2591
+ date: 2009-06-21 13:15:04 -0400
+ type: developer
+
OSDN Git Service
