BuildSystem: general, configure and Xcode updates.

*** NOTICE:
This changeset requires a clean build directory. Please issue 'make xclean' inside
build dir(s) after 'svn up'. This will help ensure there are no unexpected results.

*** GENERAL:
- renamed makevar PROJECT/ -> SRC/ for clarity.
- renamed makevar PREFIX.install/ -> PREFIX/ for clarity.
- split custom GNUmakefile overrides into defs/rules files.
- inserted optional level of make customization at SRC/ level; see docs.
- dropped HB.repo.wcversion (svnversion is no longer used).
- corrected several 'rm' usages to use -f flag which avoids some build errors.
- refreshed generated 00-Building.*.txt docs; work still in progress on the wiki front.

*** CONFIGURE:
- made configure more robust; configure may now be run outside of build directory!
- adding log recording of configure activities.
- improved readability of default options for configure
- added:

    --force             overwrite existing build config
    --src=DIR           specify top-level source dir [.]
    --build=DIR         specify build scratch/output dir [.]
    --prefix=DIR        specify install dir for products [/Applications]

- dropped --launch-force (replaced by --force)
- dropped --launch-dir (replaced by --build)
- dropped --launch-log

*** XCODE:
- renamed pbxproj definition EXTERNAL_PROJECT -> EXTERNAL_SRC for clarity.
- fixed all configurations to default to EXTERNAL_JOBS=1 .
- enabled Xcode internal parallelization (libhb, HandBrakeCLI and HandBrake benefit).
- make now tickles Xcode build files to cause Info.plist regeneration and posting to HandBrake.app output;
  ie: svn up; click build and HandBrake.app's about panel will reflect the new repository rev.

*** DARWIN:
- added support to build universal binaries; see docs.


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

8 files changed, 73 insertions, 22 deletions

diff --git a/doc/module.defs b/doc/module.defs
index 1697c9b69..84d924ab7 100644
--- a/doc/module.defs
+++ b/doc/module.defs
@@ -1,6 +1,6 @@
 $(eval $(call import.MODULE.defs,DOC,doc))
 
-DOC.in/  = $(PROJECT/)doc/
+DOC.in/  = $(SRC/)doc/
 DOC.out/ = $(BUILD/)doc/
 
 DOC.out.api/      = $(DOC.out/)api/
diff --git a/doc/module.rules b/doc/module.rules
index f86b66c09..54fec6dc7 100644
--- a/doc/module.rules
+++ b/doc/module.rules
@@ -32,6 +32,8 @@ $(DOC.m4.out): $(DOC.M4.deps)
 $(DOC.m4.out): $(DOC.out/)%: $(DOC.in/)%.m4
 	$(call DOC.M4,$@,$<)
 
+clean: doc.clean
+
 ###############################################################################
 
 #.PHONY: wiki.post wiki.sync wiki.rm wiki.add wiki.propset wiki.clean
diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi
index a554f7a0e..a02ec6131 100644
--- a/doc/texi/Building.osx.texi
+++ b/doc/texi/Building.osx.texi
@@ -37,5 +37,33 @@ Building on @value{OS.osx} is well supported. It is the reference platform for @
 @chapter Overview
 The two general methods to build on @value{OS.osx} are building from @b{terminal} or @b{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 @command{xcodebuild} to build the very same targets contained in the Xcode project.
 
+@c %**-------------------------------------------------------------------------
 @include building/chapter.via.terminal.texi
+
+@c %**-------------------------------------------------------------------------
+@anchor{terminal.ub}
+@section Universal Binaries
+This section outlines convenience procedures for creating Universal Binaries for all the architectures.
+
+@quotation Note
+The dummy (container) build configuration uses @command{--disable-xcode}; but the nested architecture builds will all make full use of Xcode.
+@end quotation
+
+Create a dummy (container) build configuration and use it to launch a nested-build for each architecture @i{serially}; optionally you may substitute @command{make ub.build.serial} for @command{make ub.build.parallel} if your machine has the horsepower:
+
+@example
+./configure --disable-xcode
+cd build/
+make ub.build.serial
+make ub.combine
+@end example
+
+To specify a subset of architectures to be built first create/edit @file{_SRC_/custom.defs} with the following override to build UB for @samp{i386} and @samp{x86_64} before invoking @command{make}:
+
+@example
+## prefer i386 (order is important)
+UB.archs = i386 x86_64
+@end example
+
+@c %**-------------------------------------------------------------------------
 @include building/chapter.via.xcode.texi
diff --git a/doc/texi/base/handbrake.texi.m4 b/doc/texi/base/handbrake.texi.m4
index efcfa8d82..0466df77c 100644
--- a/doc/texi/base/handbrake.texi.m4
+++ b/doc/texi/base/handbrake.texi.m4
@@ -25,6 +25,5 @@ dnl
 @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/building/chapter.quickstart.texi b/doc/texi/building/chapter.quickstart.texi
index 9e18db756..6aee76b91 100644
--- a/doc/texi/building/chapter.quickstart.texi
+++ b/doc/texi/building/chapter.quickstart.texi
@@ -5,7 +5,6 @@ This chapter is for building from a terminal/shell environment in as few command
 @example
 @COMMAND.checkout{}
 ./configure --launch
-cd build/
 @end example
 
 The special option @command{--launch} selects launch mode and performs the following steps:
@@ -15,6 +14,8 @@ The special option @command{--launch} selects launch mode and performs the follo
 @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 capture build output to @file{build/log/build.txt}
 @item echo build output
+@item print elapsed time
+@item indicate if build ultimately succeeded or failed
 @end itemize
diff --git a/doc/texi/building/chapter.via.terminal.texi b/doc/texi/building/chapter.via.terminal.texi
index 29014819e..56afb8168 100644
--- a/doc/texi/building/chapter.via.terminal.texi
+++ b/doc/texi/building/chapter.via.terminal.texi
@@ -12,13 +12,10 @@
 Configure the build system.
 
 @example
-rm -fr build/
-mkdir build/
-cd build/
-../configure
+./configure
 @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.
+Configure will automatically create a scratch build directory @file{build} unless you use GNU-style build procedures and first @command{cd} to a directory other than top-level source. Additionally you may specify use @command{--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 @b{not} checked into the repository.
 
 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 also documented here:
 
@@ -26,12 +23,22 @@ The @command{configure} utility accepts many options. It is recommended that you
 @item --help
 List available options.
 
-@item --prefix=PREFIX
+@item --src=DIR
+Specify top-level source directory for @value{HB.name} sources.
+
+@item --build=DIR
+Specify destination directory for final product install. The default is to use either @file{build} if in the top-level source directory, otherwise @file{.} 
+
+@item --prefix=DIR
 Specify destination directory for final product install.
 This defaults to a reasonable platform-specific value.
 
+@item --launch
+All-in-one option which launches the build and logs output automatically.
+Useful for novices and quickstart procedures.
+
 @item --disable-xcode
-Disable driving the build through Xcode. If this option is disabled only @command{HandBrakeCLI} will be produced and Xcode will not be invoked. @value{OS.osx} only.
+Disable shunting the build through Xcode. If this option is applied, @command{HandBrakeCLI} will be produced in a similare fashion as it is on other platforms; sans Xcode. @value{OS.osx} only.
 
 @item --disable-gtk
 Disable building the GTK GUI on applicable platforms such as @value{OS.linux}.
@@ -47,8 +54,6 @@ 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:
@@ -207,7 +212,24 @@ For convenience, the following targets aggregate the all contrib modules' respec
 @c %**-------------------------------------------------------------------------
 @anchor{terminal.customizing}
 @section 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 @file{build/GNUmakefile.custom} which sits adjacent to the top-level makefile. @b{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 @command{configure} is invoked; ie: @command{configure} would overwrite @file{GNUmakefile} and any customizations contained therein would be lost. Here is a short example of what the contents of @file{build/GNUmakefile.custom} might contain:
+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; @b{Do not check these files into the respository}:
+
+@table @file
+@item _SRC_/custom.defs
+Custom makevar definitions @i{outside} @file{build}. Suitable for settings which apply across all builds for a particular checkout; or which survives manual removal of @file{build}.
+
+@item _SRC_/custom.rules
+Custom make rules @i{outside} @file{build}. Suitable for settings which apply across all builds for a particular checkout; or which survives manual removal of @file{build}.
+
+@item _BUILD_/GNUmakefile.custom.defs
+Custom makevar definitions specific to a @file{build} directory.
+
+@item _BUILD_/GNUmakefile.custom.rules
+Custom makevar rules specific to a @file{build} directory.
+
+@end table
+
+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 @command{configure} is invoked; ie: @command{configure} would overwrite @file{GNUmakefile} and any customizations contained therein would be lost. Here is a short example of what the contents of @file{_SRC_/custom.defs} might contain:
 
 @example
 ## bump to gcc-4.2 in current path
diff --git a/doc/texi/building/chapter.via.xcode.texi b/doc/texi/building/chapter.via.xcode.texi
index df42faca0..a78e0808d 100644
--- a/doc/texi/building/chapter.via.xcode.texi
+++ b/doc/texi/building/chapter.via.xcode.texi
@@ -72,17 +72,16 @@ The following user defined settings are used in Xcode project for the external b
 
 @table @samp
 @item 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.
+Specifies the build (scratch) directory for each configuration.
 
 @item 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.
+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.
 
 @item EXTERNAL_METHOD
-This variable is used for internal/external build coordination and must always be @samp{xcode}.
+Do not modify; Used for internal/external build coordination and must always be @samp{xcode}.
 
-@item EXTERNAL_PROJECT
-Specifies the directory which is top of @value{HB.name} source tree.
+@item EXTERNAL_SRC
+Specifies the top-level source directory for @value{HB.name}.
 
 @end table
diff --git a/doc/texi/building/command.texi b/doc/texi/building/command.texi
index 4c21e9892..3acddc3a0 100644
--- a/doc/texi/building/command.texi
+++ b/doc/texi/building/command.texi
@@ -1,4 +1,4 @@
 @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}
+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