diff options
Diffstat (limited to 'doc/BUILD-Cygwin')
| -rw-r--r-- | doc/BUILD-Cygwin | 444 |
1 files changed, 444 insertions, 0 deletions
diff --git a/doc/BUILD-Cygwin b/doc/BUILD-Cygwin new file mode 100644 index 000000000..5bda0ae13 --- /dev/null +++ b/doc/BUILD-Cygwin @@ -0,0 +1,444 @@ +Guide to Building HandBrake svn2252 (2009031001) on Cygwin +********************************************************** + +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 +Appendix A Project Repository Details + + +1 Introduction +************** + +This guide documents the recommended process to build HandBrake on +Cygwin 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 +Cygwin; but is not necessarily the only configuration that is possible: + + * Intel 32-bit or 64-bit hardware (only 32-bit product binaries are + supported) + + * Cygwin, gcc 4.2.4 + + * yasm 0.7.2.2153 (for i386 or 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 + 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. + + Note: As of this writing, Cygwin 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 Cygwin 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 --gcc=gcc-4 + +The following general tools are used on various platforms and it is +recommended you use these versions or similar: + + * subversion - 1.5.5 + + * python - Python 2.4.6 + + * curl - curl 7.19.3 (or wget) + + * m4 - GNU M4 1.4.6 + + * make - GNU Make 3.81 + + * patch - Patch 2.5.8 + + * tar - GNU tar 1.15.1 + + * wget - GNU Wget 1.11.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 +********** + +Cygwin 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.5.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 specify 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 quickstart procedures. + +`--disable-xcode' + Disable shunting the build through Xcode. If this option is + applied, `HandBrakeCLI' will be produced in a similare fashion as + it is on other platforms; sans Xcode. Mac OS X only. + +`--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. + + +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 recusrively 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 seperated 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 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', +`lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg', +`libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264', +`xvidcore' and `zlib' have the following scoped targets: + +`make MODULE.fetch' + Download source tarball from the Internet and save to + `TOP/downloads' directory. No checksumming 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 +respository: + +`_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.2 in current path + GCC.gcc = gcc-4.2 + + ## replace optimize for 'speed' with more agressive 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. + +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: 2252 + date: 2009-03-10 18:43:11 -0400 + type: developer + |