BuildSystem: docs

- added blurb about troubleshooting and log files.
- regenerated doc/ txt files.


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

8 files changed, 114 insertions, 34 deletions

diff --git a/doc/BUILD-Cygwin b/doc/BUILD-Cygwin
index 48ac13568..ca5ae2424 100644
--- a/doc/BUILD-Cygwin
+++ b/doc/BUILD-Cygwin
@@ -1,4 +1,4 @@
-Guide to Building HandBrake svn2322 (2009041301) on Cygwin
+Guide to Building HandBrake svn2413 (2009051201) on Cygwin
 **********************************************************
 
 Table of Contents
@@ -19,6 +19,7 @@ Table of Contents
     5.4.4 Contrib Touch and Untouch
     5.4.5 Contrib Aggregates
   5.5 Customizing Make
+6 Troubleshooting
 Appendix A Project Repository Details
 
 
@@ -432,6 +433,31 @@ be lost. Here is a short example of what the contents of
 See also `make report.help' which displays a set of reports used to
 dump makefile vars.
 
+6 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
 *************************************
 
@@ -439,7 +465,7 @@ Appendix A Project Repository Details
      root:   svn://svn.handbrake.fr/HandBrake
      branch: trunk
      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
-     rev:    2322
-     date:   2009-04-13 13:28:21 -0400
+     rev:    2413
+     date:   2009-05-12 14:06:22 -0400
      type:   developer
 
diff --git a/doc/BUILD-Linux b/doc/BUILD-Linux
index 3c5182cf9..54505d22a 100644
--- a/doc/BUILD-Linux
+++ b/doc/BUILD-Linux
@@ -1,4 +1,4 @@
-Guide to Building HandBrake svn2322 (2009041301) on Linux
+Guide to Building HandBrake svn2413 (2009051201) on Linux
 *********************************************************
 
 Table of Contents
@@ -19,6 +19,7 @@ Table of Contents
     5.4.4 Contrib Touch and Untouch
     5.4.5 Contrib Aggregates
   5.5 Customizing Make
+6 Troubleshooting
 Appendix A Project Repository Details
 
 
@@ -503,6 +504,31 @@ be lost. Here is a short example of what the contents of
 See also `make report.help' which displays a set of reports used to
 dump makefile vars.
 
+6 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
 *************************************
 
@@ -510,7 +536,7 @@ Appendix A Project Repository Details
      root:   svn://svn.handbrake.fr/HandBrake
      branch: trunk
      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
-     rev:    2322
-     date:   2009-04-13 13:28:21 -0400
+     rev:    2413
+     date:   2009-05-12 14:06:22 -0400
      type:   developer
 
diff --git a/doc/BUILD-Mac b/doc/BUILD-Mac
index dae650a92..35126e43a 100644
--- a/doc/BUILD-Mac
+++ b/doc/BUILD-Mac
@@ -1,4 +1,4 @@
-Build Guide for HandBrake svn2322 on Mac OS X
+Build Guide for HandBrake svn2413 on Mac OS X
 *********************************************
 
 Table of Contents
@@ -25,6 +25,7 @@ Table of Contents
   6.2 Build
   6.3 External Targets
   6.4 User-Defined Settings
+7 Troubleshooting
 Appendix A Project Repository Details
 
 
@@ -45,13 +46,13 @@ possible:
 
    * Mac Intel hardware
 
-   * Mac OS X 10.5.6
+   * Mac OS X 10.5.7
 
    * Xcode-3.1.2
 
    * gcc 4.0.1 (Apple Inc. build 5490)
 
-   * yasm 0.7.2.2153 (for i386 and x86_64 architectures)
+   * 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
@@ -620,6 +621,31 @@ external build system:
      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
 *************************************
 
@@ -627,7 +653,7 @@ Appendix A Project Repository Details
      root:   svn://svn.handbrake.fr/HandBrake
      branch: trunk
      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
-     rev:    2322
-     date:   2009-04-13 13:28:21 -0400
+     rev:    2413
+     date:   2009-05-12 14:06:22 -0400
      type:   developer
 
diff --git a/doc/texi/Building.cygwin.texi b/doc/texi/Building.cygwin.texi
index 643a591ee..583755b9d 100644
--- a/doc/texi/Building.cygwin.texi
+++ b/doc/texi/Building.cygwin.texi
@@ -44,4 +44,5 @@ As of this writing, @value{OS.cygwin} has available to it several versions of gc
 
 @c %**-------------------------------------------------------------------------
 @include building/chapter.via.terminal.texi
+@include building/chapter.troubleshooting.texi
 @include building/appendix.repo.texi
diff --git a/doc/texi/Building.linux.texi b/doc/texi/Building.linux.texi
index 8a3f8da4a..f3b562896 100644
--- a/doc/texi/Building.linux.texi
+++ b/doc/texi/Building.linux.texi
@@ -103,4 +103,5 @@ gstreamer-devel gstreamer-plugins-base-devel
 
 @c %**-------------------------------------------------------------------------
 @include building/chapter.via.terminal.texi
+@include building/chapter.troubleshooting.texi
 @include building/appendix.repo.texi
diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi
index 5ab1ff1ce..ee3f82619 100644
--- a/doc/texi/Building.osx.texi
+++ b/doc/texi/Building.osx.texi
@@ -20,10 +20,10 @@ Building on @value{OS.osx} is well supported. It is the reference platform for @
 
 @itemize @bullet
 @item Mac Intel hardware
-@item @value{OS.osx} 10.5.6
+@item @value{OS.osx} 10.5.7
 @item Xcode-3.1.2
 @item gcc 4.0.1 (Apple Inc. build 5490)
-@item yasm 0.7.2.2153 (for i386 and x86_64 architectures)
+@item yasm 0.8.0.2194 (for i386 and x86_64 architectures)
 @end itemize
 
 @include building/prerequisites.bundled.texi
@@ -67,4 +67,5 @@ UB.archs = i386 x86_64
 
 @c %**-------------------------------------------------------------------------
 @include building/chapter.via.xcode.texi
+@include building/chapter.troubleshooting.texi
 @include building/appendix.repo.texi
diff --git a/doc/texi/building/chapter.overview.texi b/doc/texi/building/chapter.overview.texi
deleted file mode 100644
index 29dec0394..000000000
--- a/doc/texi/building/chapter.overview.texi
+++ /dev/null
@@ -1,21 +0,0 @@
-@anchor{overview}
-@chapter Build Overview
-The build system has several
-
-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 @ref{process}.
-
-@example
[email protected]{}
-./configure --launch
-@end example
-
-The special option @command{--launch} selected launch mode and performs the following steps:
-
-@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
diff --git a/doc/texi/building/chapter.troubleshooting.texi b/doc/texi/building/chapter.troubleshooting.texi
new file mode 100644
index 000000000..4d42e76a3
--- /dev/null
+++ b/doc/texi/building/chapter.troubleshooting.texi
@@ -0,0 +1,20 @@
+@anchor{troubleshooting}
+@chapter Troubleshooting
+When troubleshooting build issues, the following files relative to the @file{build/} directory may be especially useful:
+
+@table @file
+@item GNUmakefile
+Top-level makefile which contains build settings generated via @b{configure}.
+
+@item log/config.info.txt
+Record of output from @b{configure}.
+
+@item log/config.verbose.txt
+Record of verbose output from @b{configure}.
+
+@item log/build.txt
+Record of output from @command{configure --launch}. Similar output may be recorded using @command{make} depending on which shell is in use, eg: @command{make >& log/build.txt} or @command{make > log/build.txt 2>&1}.
+
+@item log/xcodemake.env.txt
+Environment (variables) dump as seen when Xcode forks @command{make}. @value{OS.osx} only.
+@end table