diff options
| -rw-r--r-- | 00-Building.cygwin.txt | 432 | ||||
| -rw-r--r-- | 00-Building.linux.txt | 498 | ||||
| -rw-r--r-- | 00-Building.osx.txt | 591 | ||||
| -rw-r--r-- | doc/module.defs | 18 | ||||
| -rw-r--r-- | doc/module.rules | 37 | ||||
| -rw-r--r-- | doc/texi/Building.cygwin.texi | 2 | ||||
| -rw-r--r-- | doc/texi/Building.linux.texi | 2 |
7 files changed, 4 insertions, 1576 deletions
diff --git a/00-Building.cygwin.txt b/00-Building.cygwin.txt deleted file mode 100644 index 70cbd53dd..000000000 --- a/00-Building.cygwin.txt +++ /dev/null @@ -1,432 +0,0 @@ -Guide to Building HandBrake svn2241 (2009030801) 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 - - -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 settings 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. - diff --git a/00-Building.linux.txt b/00-Building.linux.txt deleted file mode 100644 index 955e4cd4a..000000000 --- a/00-Building.linux.txt +++ /dev/null @@ -1,498 +0,0 @@ -Guide to Building HandBrake svn2241 (2009030801) on Linux -********************************************************* - -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 - - -1 Introduction -************** - -This guide documents the recommended process to build HandBrake on -Linux 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 -Linux; but is not necessarily the only configuration that is possible: - - * Intel 32-bit or 64-bit kernel - - * Ubuntu 8.0.4, gcc 4.3.0, yasm 0.7.1.2093 - - * Ubuntu 8.10, gcc 4.3.2, yasm 0.7.1.2093 - - * Fedora 9, gcc 4.3.0, yasm 0.7.1.2093 - - * Fedora 10, gcc 4.3.2, yasm 0.7.1.2093 - - * gcc 4.0.0 or higher is reported to work - - 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. - -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) - -The GTK UI introduces some significant extra build requirements. If you -intend to disable building the GUI with `configure --disable-gtk' you -will not need many of these packages installed: - -Ubuntu 8.10 packages: - * build-essential - - * autoconf (gui) - - * intltool (gui) - - * libtool (gui) - - * zlib1g-dev (gui) - - * libbz2-dev - - * libglib2.0-dev (gui) - - * libdbus-glib-1-dev (gui) - - * libgtk2.0-dev (gui) - - * libhal-dev (gui) - - * libhal-storage-dev (gui) - - * libgtkhtml3.14-dev (gui) - - * libgstreamer0.10-dev (gui) - - * libgstreamer-plugins-base0.10-dev (gui) - -To install these packages: - sudo apt-get install subversion yasm build-essential \ - autoconf intltool libtool zlib1g-dev libbz2-dev libglib2.0-dev \ - libdbus-glib-1-dev libgtk2.0-dev libhal-dev libhal-storage-dev \ - libgtkhtml3.14-dev libgstreamer0.10-dev libgstreamer-plugins-base0.10-dev - -Fedora 10 package groups: - * Development Tools - - * Development Libraries - - * X Software Development (gui) - - * GNOME Software Development (gui) - -To install these package groups: - sudo yum groupinstall "Development Tools" "Development Libraries" \ - "X Software Development" "GNOME Software Development" - -Additional Fedora 10 packages: - * zlib-devel (gui) - - * bzip2-devel - - * dbus-glib-devel (gui) - - * hal-devel (gui) - - * gtkhtml3-devel (gui) - - * gstreamer-devel (gui) - - * gstreamer-plugins-base-devel (gui) - -To install these packages: - sudo yum install yasm zlib-devel bzip2-devel \ - dbus-glib-devel hal-devel gtkhtml3-devel \ - gstreamer-devel gstreamer-plugins-base-devel - -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 -********** - -Linux 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 settings 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. - diff --git a/00-Building.osx.txt b/00-Building.osx.txt deleted file mode 100644 index 0d91d75a8..000000000 --- a/00-Building.osx.txt +++ /dev/null @@ -1,591 +0,0 @@ -Guide to Building HandBrake svn2241 (2009030801) on Mac OS X -************************************************************ - -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 - 5.6 Universal Binaries -6 Building via Xcode - 6.1 Checkout Sources - 6.2 Build - 6.3 External Targets - 6.4 User-Defined Settings - - -1 Introduction -************** - -This guide documents the recommended process to build HandBrake on -Mac OS X hosts from the official source-code repository. Building from -any other source is not supported. - -2 Prerequisites -*************** - -Building on Mac OS X is well supported. It is the reference platform -for HandBrake. The following are the recommended specifications for -this platform; but is not necessarily the only configuration that is -possible: - - * Mac Intel hardware - - * Mac OS X 10.5.6 - - * Xcode-3.1.2 - - * gcc 4.0.1 (Apple Inc. build 5490) - - * yasm 0.7.2.2153 (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 - 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. - -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 -********** - -The two general methods to build on Mac OS X are building from terminal -or 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 `xcodebuild' to -build the very same targets contained in the Xcode project. - -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 settings 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. - -5.6 Universal Binaries -====================== - -This section outlines convenience procedures for creating Universal -Binaries for all the architectures. - - Note: The dummy (container) build configuration uses - `--disable-xcode'; but the nested architecture builds will all - make full use of Xcode. - -Create a dummy (container) build configuration and use it to launch a -nested-build for each architecture serially; optionally you may -substitute `make ub.build.serial' for `make ub.build.parallel' if your -machine has the horsepower: - - ./configure --disable-xcode - cd build/ - make ub.build.serial - make ub.combine - -To specify a subset of architectures to be built first create/edit -`_SRC_/custom.defs' with the following override to build UB for `i386' -and `x86_64' before invoking `make': - - ## prefer i386 (order is important) - UB.archs = i386 x86_64 - -6 Building via Xcode -******************** - -6.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. - -6.2 Build -========= - -In Xcode perform the following steps to build the default configuration: - - * open `macosx/HandBrake.xcodeproj' - - * select active configuration standard - - * select active target HandBrake - - * click Build or Build and Go - -The first build (on an empty `build' directory) will take a bit of -time. You may use the Build Results window to observe progress. The -most time-consuming part of the build is when the external build system -(essentially the terminal method) is triggered by Xcode and a -substantial amount of log transcript ensues. Much of that transcript -are warnings and errors that are part of the normal build process for -3rd-party contributed modules so in general you need not do anything. -However, if Xcode itself reports the build failed, then you must take -corrective action. - -Unfortunately, due to limitations of Xcode we do not have hooks in -place to offer finer-grained control over per-module make actions for -the (external) build system. Thus, you will have to use terminal to -accomplish those tasks. Just `cd' into the build directory which is -associated with your active configuration and perform any necessary -`make' commands. Be careful not to issue commands from the terminal -simultaneously with Xcode tasks as that will confuse both Xcode and -make and likely corrupt your build directory. - -When you click clean in Xcode it will not perform an external build -clean. Basically HandBrakeCLI and HandBrake.app are the only products -which have full Xcode iterative development flexibility. - -Each configuration uses a different `build' directory. This makes it -possible to build each configuration and switch between them without -losing their respective build state. The description of each -configuration and the name convention for build directories are as -follows: - -`standard' - This configuration will build to the host native architecture. - Build directory is `build.standard' . The standard variant - produces optimized code without debug information. - -`debug' - This configuration will build to the host native architecture. - Build directory is `build.standard' . The debug variant produces - unoptimized code with debug information. - -`standard.i386' - This configuration is used to build for the i386 architecture. - Build directory is `build.standard.i386' . - -`standard.x86_64' - This configuration is used to build for the x86_64 architecture. - Build directory is `build.standard.x86_64' . - -`standard.ppc' - This configuration is used to build for the ppc architecture. - Build directory is `build.standard.ppc' . - -`standard.ppc64' - This configuration is used to build for the ppc64 architecture. - Build directory is `build.standard.ppc64' . - -6.3 External Targets -==================== - -The following external targets appear in the Xcode project and perform -build and clean actions. - -`external' - Target maps to `make build' and `make clean' for everything Xcode - products depend upon from the external build system. - -`libhb' - Target maps to `make libhb.build' and `make libhb.clean'. - -`contrib' - Target maps to `make contrib.build' and `make contrib.xclean'. - - -6.4 User-Defined Settings -========================= - -The following user defined settings are used in Xcode project for the -external build system: - -`EXTERNAL_BUILD' - Specifies the build (scratch) directory for each configuration. - -`EXTERNAL_JOBS' - Specifies the concurrency factor for the external build system - when builds are launched from within Xcode. 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. - -`EXTERNAL_METHOD' - Do not modify; Used for internal/external build coordination and - must always be `xcode'. - -`EXTERNAL_SRC' - Specifies the top-level source directory for HandBrake. - - diff --git a/doc/module.defs b/doc/module.defs index 84d924ab7..8047022bd 100644 --- a/doc/module.defs +++ b/doc/module.defs @@ -46,21 +46,3 @@ MAKEINFO = $(MAKEINFO.exe) $(MAKEINFO.flags) $(MAKEINFO.flags.$(1)) $ XML2WIKI.exe = python3.0 $(DOC.in/)xml2wiki.py XML2WIKI.flags = --toc XML2WIKI = $(XML2WIKI.exe) $(XML2WIKI.flags) $(1) > $(2) - -############################################################################### - -## This section is for generating wiki docs and posting them to: -## -## [REPOSITORY]/wiki/[VERSION] -## -## which in turn is hosted by trac export webserver: -## -## http://[TRACSERVER]/HEAD/wiki/[VERSION] -## - -WIKI.out/ = $(BUILD/)wiki/ -WIKI.out.version/ = $(WIKI.out/)$(HB.repo.branch)/ - -WIKI.repo.url = $(HB.repo.root)/wiki - -BUILD.out += $(WIKI.out.version/) diff --git a/doc/module.rules b/doc/module.rules index cc451241f..ac30a2a55 100644 --- a/doc/module.rules +++ b/doc/module.rules @@ -33,40 +33,3 @@ $(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 - -## main target -wiki.post: $(WIKI.out/) wiki.sync wiki.rm wiki.add wiki.propset - -$(WIKI.out/): - svn co --depth immediates $(WIKI.repo.url) $@ - svn update --set-depth infinity $(WIKI.out.version/) - -## cleanup after post -wiki.clean: - $(RM.exe) -fr $(WIKI.out/) - -wiki.sync: | $(WIKI.out.version/) -wiki.sync: $(DOC.xml2wiki.out) - rsync -vrptPL --delete $^ $(WIKI.out.version/) - -wiki.rm: - @files=`svn status $(WIKI.out.version/) | grep '^!' | awk '{ print $$2 }'`; \ - if [ -n "$$files" ]; then \ - svn rm $$files; \ - fi - -wiki.add: - @files=`svn status $(WIKI.out.version/) | grep '^?' | awk '{ print $$2 }'`; \ - if [ -n "$$files" ]; then \ - svn add $$files; \ - fi - -wiki.propset: - find $(WIKI.out.version/) -type f -a -name "*.wiki" -print0 \ - | xargs -0 svn propset svn:eol-style LF - find $(WIKI.out.version/) -type f -a -name "*.wiki" -print0 \ - | xargs -0 svn propset svn:mime-type "text/x-trac-wiki" diff --git a/doc/texi/Building.cygwin.texi b/doc/texi/Building.cygwin.texi index a2fda9ab3..643a591ee 100644 --- a/doc/texi/Building.cygwin.texi +++ b/doc/texi/Building.cygwin.texi @@ -42,4 +42,6 @@ As of this writing, @value{OS.cygwin} has available to it several versions of gc @chapter Overview @value{OS.cygwin} builds are performed from a @b{terminal}. There is no support for building from any IDEs. +@c %**------------------------------------------------------------------------- @include building/chapter.via.terminal.texi +@include building/appendix.repo.texi diff --git a/doc/texi/Building.linux.texi b/doc/texi/Building.linux.texi index 0e89a2277..aac1c266d 100644 --- a/doc/texi/Building.linux.texi +++ b/doc/texi/Building.linux.texi @@ -98,4 +98,6 @@ gstreamer-devel gstreamer-plugins-base-devel @chapter Overview @value{OS.linux} builds are performed from a @b{terminal}. There is no support for building from any IDEs. +@c %**------------------------------------------------------------------------- @include building/chapter.via.terminal.texi +@include building/appendix.repo.texi |