path: root/doc/BUILD-Mac

Build Guide for HandBrake svn3349 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

When using Build and Go, xcode launches the application under the gdb
debugger.  gdb will encounter a trap when starting the program.  This
trap is harmless and you should just 'continue'.  For the curious, the
trap occurs because we add some values to the environment with setenv,
then do a brain transplant with execv. Restarting the application with
execv triggers the trap.

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.

A note about gdb: We perform an extra execv when starting the
application.  This triggers a trap in gdb.  It is harmless.  You should
just 'continue' from the trap.

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:    3349
     date:   2010-06-02 09:49:18 -0700
     type:   developer