BuildSystem: conversion from jam-based to make-based system.

KNOWN ISSUES:
    1. OSX + Xcode builds do not support parallel builds; attempting to
       use them may cause unbounded number of jobs. However, disabling
       via configure --disable-xcode avoids the issue.
    2. OSX ppc binary produces binary which has audio-scan problems.
    3. OSX ppc64 binary has not been runtime tested.

ADDED:
    00-BuildUserGuide.txt
    contrib/*/module.*
    doc/
    make/

    libhb/module.*
    test/module.*
    macos/module.*
    gtk/module.*

DROPPED:
    BUILD
    BuildContribDarwin.sh
    DownloadMacOsXContribBinaries.sh
    Jamfile
    Jamrules
    MacOsXContribBinariesVersion.txt
    Makefile
    Makefile.config
    jam
    libhb/Jamefile
    libhb/Makefile
    test/BUILDSHARED
    test/Makefile
    contrib/Jamfile
    contrib/Makefile
    contrib/patch-ffmpeg.patch
    contrib/patch-x264-idr.patch
    contrib/patch-x264-linux.patch

RENAMED:
    contrib/*.patch -> contrib/MODULE/[AP]??-*.patch
    macosx/HandBrake.plist -> macosx/Info.plist

MODIFIED: libhb/decavcodec.c
    Patched to use cleaner include "libavcodec/audioconvert".
    Second part to support this cleanup is ffmpeg A02-audioconvert.patch .

MODIFIED: libhb/hb.c
MODIFIED: libhb/hb.h
MODIFIED: libhb/muxmkv.c
MODIFIED: libhb/muxmp4.c
MODIFIED: libhb/update.c
    Patched to use "project.h" for project metadata.
    Renamed HB_BUILD -> HB_PROJECT_BUILD.
    Renamed HB_VERSION -> HB_PROJECT_VERSION.

MODIFIED: test/test.c:
    Patched HandBrakeCLI to support I/O on Mac OS X ZFS filesystems.
    Reference r1803 as similar patch for HandBrake.app .
    Unpatched behavior is crash/buserror when using ZFS.

MODIFIED: macosx/Growl.framework/
    Upgraded 0.7.6 (i386,ppc) -> 1.1.2 (i386,x86_64,ppc,ppc64).
    New architectures facilitate x86_64 and ppc64 builds.

MODIFIED: macosx/HandBrake.xcodeproj/
    Bumped compatibilty mode from 2.4 -> 3.1 .
    Dumped old configurations Deployment, Developer.
    Added configurations standard, sebug as replacements.
    Added standard.i386, standard.x86_64, standard.ppc, standard.ppc64 .
    for explicit architecture build.
    All configurations settings cleaned up and normalized.
    Build output directories adjusted to support new build system.


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

6 files changed, 353 insertions, 0 deletions

diff --git a/doc/texi/BuildUserGuide.texi b/doc/texi/BuildUserGuide.texi
new file mode 100644
index 000000000..7fb3a4d66
--- /dev/null
+++ b/doc/texi/BuildUserGuide.texi
@@ -0,0 +1,280 @@
+@input texinfo @c -*- Texinfo -*-
+@c %**start of header
+@setfilename BuildUserGuide.info
+@include base/article.texi
+@include build/command.texi
+@paragraphindent none
+@c %**end of header
+
+@majorheading @value{HB.title} Build User Guide
+@contents
+
+@c %**-------------------------------------------------------------------------
+@chapter Introduction
+This guide documents the recommended process to build @value{HB.name} from the official source-code repository. @b{Building from any other source is not unsupported}.
+
+@chapter Quickstart
+This chapter is for the impatient or those just looking for a quick summary of the commands used to launch a typical build with the fewest commands possible. For more control over the build process please skip this section and jump to @ref{Build Process} for full details.
+
+@example
[email protected]{}
[email protected]{}
+@end example
+
+The above is an special streamlined invocation of @command{configure} which performs the following steps automatically:
+
+@itemize
+@item assert scratch directory @file{build/} does not exist
+@item create scratch directory @file{build/}
+@item change to directory @file{build/}
+@item launch @command{make}
+@item capture build output to @file{build/log.txt}
+@item echo build output
+@end itemize
+
+@c %**-------------------------------------------------------------------------
+@anchor{Build Process}
+@chapter Build Process
+
+@anchor{Checkout}
+@section Checkout Sources
+Checkout @value{HB.name} from the official source-code repository.
+
+@example
[email protected]{}
+@end example
+
+Sources are checked out from the @samp{@value{HB.repo.branch}} 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.
+
+@anchor{Configure}
+@section Configure
+Configure the build system.
+
+@example
[email protected]{}
+@end example
+
+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 @file{build} for example purposes.
+
+The @command{configure} utility accepts many options. It is recommended that you specify @command{--help} for the complete list of options. The following options are detailed:
+
+@table @samp
+@item --help
+List available options.
+
+@item --debug=MODE
+Select debug mode. Must be one of @samp{none}, @samp{min}, @samp{std}, @samp{max}.
+This generally maps to gcc options @samp{-g0}, @samp{-g1}, @samp{-g2}, @samp{-g3}.
+
+@item --optimize=MODE
+Select optimize mode. Must be one of @samp{none}, @samp{speed}, @samp{size}.
+This generally maps to gcc options @samp{-g0}, @samp{-O0}, @samp{-O3}, @samp{-Os}.
+
+@item --arch=MODE
+Select build architecture. The available architectures vary by platform. Most platforms support exactly one architecture except @value{OS.osx} 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.
+
+@item --gcc=EXE
+Specify the @command{gcc} executable to use where @b{EXE} is the executable name which is either absolute or environment @samp{PATH} is searched accordingly.
+@end table
+
+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:
+
+@itemize
+@item configure with different options
+@item subversion working dir is updated and you want configure to re-evaluate working dir metadata.
+@item build corruption is suspected
+@end itemize
+
+There are generally two methods for scrapping a build. The @file{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 use ask the build system to perform an @command{xclean}. This is known to work well but will leave empty directories behind. However, the configuration is left intact. See @ref{Extra Clean} for further details.
+
+@anchor{Build}
+@section Build
+Build main product. All necessary dependencies are also built if required.
+
+@example
[email protected]{}
+@end example
+
+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:
+
+@example
+make -j4
+@end example
+
+@anchor{Clean}
+@section Clean
+Clean all build output excluding contrib modules. Configuration is retained.
+
+@example
[email protected]{}
+@end example
+
+@anchor{Extra Clean}
+@section Extra Clean
+Clean all build output including contrib modules. Configuration is retained.
+
+@example
[email protected]{}
+@end example
+
+@c %**-------------------------------------------------------------------------
+@anchor{Make Targets}
+@chapter 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 @command{make}. Global targets are one-word targets. Scoped targets are usually two-words seperated by a period.
+
+@anchor{Global Targets}
+@section Global
+
+@table @samp
+@item make
+Alias for @samp{make build}.
+
+@item make build
+Build main product. All necessary dependencies are also built if required.
+
+@item make clean
+Clean all build output excluding contrib modules. Configuration is retained.
+
+@item make xclean
+Clean all build output including contrib modules. Configuration is retained.
+@end table
+
+@anchor{General Module Targets}
+@section General Modules
+
+General modules such as @samp{libhb} and @samp{test} have the following scoped targets:
+
+@table @samp
+@item make @i{MODULE}.build
+Build @i{MODULE}.
+
+@item make @i{MODULE}.clean
+Clean build output for @i{MODULE}.
+@end table
+
+@anchor{Contrib Module Targets}
+@section Contrib Modules
+
+Contrib modules such as @samp{a52dec}, @samp{bzip2}, @samp{faac}, @samp{faad2}, @samp{ffmpeg}, @samp{lame}, @samp{libdca}, @samp{libdvdread}, @samp{libmkv}, @samp{libmp4v2}, @samp{libogg}, @samp{libsamplerate}, @samp{libtheora}, @samp{libvorbis}, @samp{mpeg2dec}, @samp{x264}, @samp{xvidcore} and @samp{zlib} have the following scoped targets:
+
+@table @samp
+@item make @i{MODULE}.fetch
+Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed.
+
+@item make @i{MODULE}.extract
+Extract source tarball into @file{build} tree.
+
+@item make @i{MODULE}.patch
+Apply appropriate patches (if any) to module sources.
+
+@item make @i{MODULE}.configure
+Configure module sources.
+This usually invokes autotool configure.
+
+@item make @i{MODULE}.build
+Build module.
+This usually invokes autotool build.
+
+@item make @i{MODULE}.install
+Install module products such as headers and libraries into @file{build} tree.
+This usually invokes autotool install.
+
+@item make @i{MODULE}.uninstall
+Uninstall module products; generally the reverse of install.
+This usually invokes autotool uninstall.
+
+@item make @i{MODULE}.clean
+Clean module; generally the reverse of build.
+This usually invokes autotool clean.
+
+@item make @i{MODULE}.xclean
+Extra clean module; first invokes uninstall then recursively removes the module build directory.
+@end table
+
+@anchor{Contrib Aggregate Targets}
+@section Contrib Aggregate
+
+For convenience, the following targets aggregate the all contrib modules' respective targets together:
+
+@itemize
+@item make contrib.fetch
+@item make contrib.extract
+@item make contrib.patch
+@item make contrib.configure
+@item make contrib.build
+@item make contrib.install
+@item make contrib.uninstall
+@item make contrib.clean
+@item make contrib.xclean
+@end itemize
+
+@c %**-------------------------------------------------------------------------
+@anchor{Platform}
+@chapter Platform Requirements and Notes
+
+The build system supports various platforms of interest to the project. However this does not mean it supports all plaforms. If the platform is not listed in this chapter, then it is not supported.
+
+The following tools are used on various platforms and it is recommended you use these versions or newer:
+
+@itemize @bullet
+@item python - Python 2.4.6
+@item curl - curl 7.19.3 (or wget)
+@item m4 - GNU M4 1.4.6
+@item make - GNU Make 3.81
+@item patch - Patch 2.5.8
+@item tar - GNU tar 1.15.1
+@item wget - GNU Wget 1.11.4 (or curl)
+@end itemize
+
+@anchor{@value{OS.osx}}
+@section @value{OS.osx}
+
+Building on @value{OS.osx} is well supported. It is the reference platform for @value{HB.name}. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible:
+
+@itemize @bullet
+@item Mac Intel hardware
+@item @value{OS.osx} 10.5.6
+@item Xcode-3.1.2
+@item gcc 4.0.1 (Apple Inc. build 5490)
+@item yasm 0.7.2.2153 (for i386 or x86_64 architectures)
+@end itemize
+
+@include build/platform.common.bundled.texi
+
+@anchor{@value{OS.cygwin}}
+@section @value{OS.cygwin}
+
+Building on @value{OS.cygwin} is supported. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible:
+
+@itemize @bullet
+@item Intel 32-bit or 64-bit hardware
+@item @value{OS.cygwin}, gcc 4.3.2
+@item yasm 0.7.1.2093 (for i386 or x86_64 architectures)
+@end itemize
+
+@quotation Note
+As of this writing, @value{OS.cygwin} has available to it several versions of gcc; only one of which may be found and
+used in the path as @code{gcc} and @code{g++}. Configure will thus find what is probably the older version of gcc in a typical @value{OS.cygwin} environment. If you desire to build with the newer gcc, it is found in the path as @command{gcc-4} and @command{g++-4} respectively and you must indicate to configure the desired versions. The following syntax should do the trick:
+@end quotation
+
+@example
+../configure --gcc=gcc-4
+@end example
+
+@anchor{@value{OS.linux}}
+@section @value{OS.linux}
+
+Building on @value{OS.linux} is supported. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible:
+
+@itemize @bullet
+@item Intel 32-bit or 64-bit hardware
+@item Fedora 8, gcc 4.1.2, yasm 0.6.2.1985
+@item Fedora 9, gcc 4.3.0, yasm 0.6.2.1985
+@item Fedora 10, gcc 4.3.2, yasm 0.7.1.2093
+@item gcc 4.0.0 or higher is reported to work
+@end itemize
+
+@include build/platform.common.bundled.texi
diff --git a/doc/texi/base/article.texi b/doc/texi/base/article.texi
new file mode 100644
index 000000000..7ff6c7480
--- /dev/null
+++ b/doc/texi/base/article.texi
@@ -0,0 +1,6 @@
+@ifhtml
+@exampleindent 0
+@end ifhtml
+
+@include base/handbrake.texi
+@include base/glossary.texi
diff --git a/doc/texi/base/glossary.texi b/doc/texi/base/glossary.texi
new file mode 100644
index 000000000..1a998f4b8
--- /dev/null
+++ b/doc/texi/base/glossary.texi
@@ -0,0 +1,7 @@
+@set OS.cygwin   Cygwin
+@set OS.freebsd  FreeBSD
+@set OS.linux    Linux
+@set OS.osx      Mac OS X
+@set OS.solaris  Solaris
+@set OS.unix     unix
+@set OS.windows  Windows
diff --git a/doc/texi/base/handbrake.texi.m4 b/doc/texi/base/handbrake.texi.m4
new file mode 100644
index 000000000..efcfa8d82
--- /dev/null
+++ b/doc/texi/base/handbrake.texi.m4
@@ -0,0 +1,30 @@
+changequote(<<,>>)dnl
+include(<<handbrake.m4>>)dnl
+dnl
+dnl
+dnl
+@set HB.title           __HB_title
+@set HB.name            __HB_name
+@set HB.name.lower      __HB_name_lower
+@set HB.name.upper      __HB_name_upper
+@set HB.acro.lower      __HB_acro_lower
+@set HB.acro.upper      __HB_acro_upper
+@set HB.url.website     __HB_url_website
+@set HB.url.community   __HB_url_community
+@set HB.url.irc         __HB_url_irc
+@set HB.url.appcast     __HB_url_appcast
+@set HB.version.major   __HB_version_major
+@set HB.version.minor   __HB_version_minor
+@set HB.version.point   __HB_version_point
+@set HB.version         __HB_version
+@set HB.version.hex     __HB_version_hex
+@set HB.build           __HB_build
+@set HB.repo.url        __HB_repo_url
+@set HB.repo.root       __HB_repo_root
+@set HB.repo.branch     __HB_repo_branch
+@set HB.repo.uuid       __HB_repo_uuid
+@set HB.repo.rev        __HB_repo_rev
+@set HB.repo.date       __HB_repo_date
+@set HB.repo.wcversion  __HB_repo_wcversion
+@set HB.repo.official   __HB_repo_official
+@set HB.repo.type       __HB_repo_type
diff --git a/doc/texi/build/command.texi b/doc/texi/build/command.texi
new file mode 100644
index 000000000..db6b0b493
--- /dev/null
+++ b/doc/texi/build/command.texi
@@ -0,0 +1,27 @@
+@macro COMMAND.checkout{}
+svn checkout @value{HB.repo.url} @value{HB.acro.lower}-@value{HB.repo.branch}
+cd @value{HB.acro.lower}-@value{HB.repo.branch}
+@end macro
+
+@macro COMMAND.configure.launch{}
+./configure --launch
+@end macro
+
+@macro COMMAND.configure{}
+rm -fr build/
+mkdir build/
+cd build/
+../configure
+@end macro
+
+@macro COMMAND.build{}
+make
+@end macro
+
+@macro COMMAND.clean{}
+make clean
+@end macro
+
+@macro COMMAND.xclean{}
+make xclean
+@end macro
diff --git a/doc/texi/build/platform.common.bundled.texi b/doc/texi/build/platform.common.bundled.texi
new file mode 100644
index 000000000..f5af0fcce
--- /dev/null
+++ b/doc/texi/build/platform.common.bundled.texi
@@ -0,0 +1,3 @@
+@quotation 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.
+@end quotation