BuildSystem:

- fixed OSX + Xcode to support parallel builds
- enhanced OSX + Xcode to use proper pass-thru for all make targets
- added global target --> install
- added install: test.install
- added install: gtk.install
- updated pre-generated building guides (these will go away when wiki is updated)
- updated xml2wiki script to spit out heading


git-svn-id: svn://svn.handbrake.fr/HandBrake/trunk@2205 b64f7644-9d1e-0410-96f1-a4d463321fa5

1 files changed, 468 insertions, 0 deletions

diff --git a/00-Building.osx.txt b/00-Building.osx.txt
new file mode 100644
index 000000000..dc7c0a542
--- /dev/null
+++ b/00-Building.osx.txt
@@ -0,0 +1,468 @@
+Guide to Building HandBrake svn2204 (2009030201) 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 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 install'
+     Perform final product(s) install.  This will install build
+     products to a standard directory or one specified via `configure
+     --prefix' option.
+
+`make clean'
+     Clean all build output excluding contrib modules. Configuration is
+     retained.
+
+`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 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.
+
+