diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/BUILD-MinGW | 484 |
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 |