diff options
Diffstat (limited to '00-Building.linux.txt')
| -rw-r--r-- | 00-Building.linux.txt | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/00-Building.linux.txt b/00-Building.linux.txt new file mode 100644 index 000000000..a2e2d0ba1 --- /dev/null +++ b/00-Building.linux.txt @@ -0,0 +1,421 @@ +Guide to Building HandBrake svn2204 (2009030201) 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 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. If more flexibility is required you should +skip this chapter and jump to *Note overview::. + + svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk + cd hb-trunk + ./configure --launch + +The special option `--launch' selected 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.txt' + + * echo build output + +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. + + rm -fr build/ + mkdir build/ + cd build/ + ../configure + +Create a scratch directory which will contain all files created during +the build process. The directory name is arbitrary but we recommend +something simple and descriptive. One directory is required for each +distinctly configured build. We name our directory `build' for example +purposes. + +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. + +`--prefix=PREFIX' + Specify destination directory for final product install. This + defaults to a reasonable platform-specific value. + +`--disable-xcode' + Disable driving the build through Xcode. If this option is + disabled only `HandBrakeCLI' will be produced and Xcode will not + be invoked. 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. + +`--gcc=EXE' + Specify the `gcc' executable to use where EXE is the executable + name which is either absolute or environment `PATH' is searched + accordingly. + +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 install' + Perform final product(s) install. This will install build + products to a standard directory or one specified via `configure + --prefix' option. + +`make clean' + Clean all build output excluding contrib modules. Configuration is + retained. + +`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'. + +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 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/edit the optional include file `build/GNUmakefile.custom' which +sits adjacent to the top-level makefile. Do not check this file into +the respository. The sole 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 `build/GNUmakefile.custom' 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 + |