Add the readable copy of the MinGW doc file

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

1 files changed, 484 insertions, 0 deletions

diff --git a/doc/BUILD-MinGW b/doc/BUILD-MinGW
new file mode 100644
index 000000000..2fa752d1a
--- /dev/null
+++ b/doc/BUILD-MinGW
@@ -0,0 +1,484 @@
+Guide to Building HandBrake svn4891 (2012080501) on MinGW
+*********************************************************
+
+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
+6 Troubleshooting
+Appendix A Project Repository Details
+
+
+1 Introduction
+**************
+
+This guide documents the recommended process to build HandBrake on
+MinGW hosts from the official source-code repository. Building from any
+other source is not supported.
+
+2 Prerequisites
+***************
+
+The following are the recommended specifications for building on
+MinGW; but is not necessarily the only configuration that is possible:
+
+   * Intel 32-bit or 64-bit hardware
+
+   * MinGW on Fedora 16, Ubuntu or Debian, gcc 4.5+
+
+   * yasm 1.1.x.x (for i386 or x86_64 architectures)
+
+     Note: It is recommended to use the platform distribution's
+     standard compiler for maximum C++ compatibility. If you build with
+     a custom compiler it will likely introduce non-standard runtime
+     requirements and have new/delete, exception and RTTI
+     incompatibilities. 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.
+
+     Note: You must set the -cross flag with configure to cross compile
+     with windows.  See the Example below. Note that the cross compiler
+     name varies between distributions.
+
+     As of this writing, MinGW has available to it several versions of
+     gcc; only one of which may be found and used in the path as `gcc'
+     and `g++'. Configure will thus find what is probably the older
+     version of gcc in a typical MinGW environment. If you desire to
+     build with the newer gcc, it is found in the path as `gcc-4' and
+     `g++-4' respectively and you must indicate to configure the
+     desired versions. The following syntax should do the trick:
+
+     ../configure --cross=i686-pc-mingw32 --gcc=gcc-4
+
+The following general tools are used on various platforms and it is
+recommended you use these versions or similar:
+
+   * subversion - 1.6.16
+
+   * python - Python 2.7.1
+
+   * curl - curl 7.21.4 (or wget)
+
+   * m4 - GNU M4 1.4.6
+
+   * make - GNU Make 3.81
+
+   * patch - Patch 2.5.8
+
+   * tar - GNU tar 1.26
+
+   * wget - GNU Wget 1.13.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
+**********
+
+MinGW builds are performed from a terminal. There is no support for
+building from any IDEs.
+
+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.6.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-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.
+
+`--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.
+
+`--xcconfig=MODE'
+     Select Xcode project configuration file. The available modes are
+     the basenames of files located in `macosx/xcconfig/*.xcconfig'
+     which direct Xcode to build using various architecture and Mac OS
+     X deployment options. Mac OS X only.
+
+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 doc.post'
+     Build auto-generated project documentation and post produced
+     articles directly to source tree.
+
+`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',
+`fontconfig', `freetype', `fribidi', `lame', `libass', `libbluray',
+`libdca', `libdvdnav', `libdvdread', `libdvdread', `libiconv',
+`libmkv', `libogg', `libsamplerate', `libtheora', `libvorbis',
+`libxml2', `mp4v2', `mpeg2dec', `x264', `yasm' 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.6 in current path
+     GCC.gcc = /usr/bin/gcc-4.6
+
+     ## 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.
+
+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
+*************************************
+
+     url:    svn://svn.handbrake.fr/HandBrake/trunk
+     root:   svn://svn.handbrake.fr/HandBrake
+     branch: trunk
+     uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
+     rev:    4891
+     date:   2012-08-05 17:23:19 +0100
+     type:   developer