Guide to Building HandBrake 20160902092339-aef9c01-master (2016090201) on Linux ******************************************************************************* 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 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 14.04, gcc 4.8, yasm 1.3.x * Ubuntu 16.04, gcc 5.3, yasm 1.3.x * Fedora 20, gcc 4.8, yasm 1.3.x * gcc 4.7 or higher is reported to work 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. The following general tools are used on various platforms and it is recommended you use these versions or similar: * git - 2.4.3 * python - Python 2.7.1 * m4 - GNU M4 1.4.6 * make - GNU Make 3.81 * patch - Patch 2.5.8 * tar - GNU tar 1.26 The GTK UI introduces some significant extra build requirements. GTK version 3.10+ is required to build the GTK UI. If you intend to disable building the GUI with 'configure --disable-gtk' you will not need many of these packages installed: Ubuntu 14.04, 16.04 packages: * git (cli/gui) * cmake (cli/gui) * yasm (cli/gui) * build-essential (cli/gui) * autoconf (cli/gui) * libtool (cli/gui) * zlib1g-dev (cli/gui) * libbz2-dev (cli/gui) * libxml2-dev (cli/gui) * libogg-dev (cli/gui) * libtheora-dev (cli/gui) * libvorbis-dev (cli/gui) * libopus-dev (cli/gui) * libsamplerate-dev (cli/gui) * libfribidi-dev (cli/gui) * libfreetype6-dev (cli/gui) * libfontconfig1-dev (cli/gui) * libass-dev (cli/gui) * libmp3lame-dev (cli/gui) * libx264-dev (cli/gui) * libjansson-dev (cli/gui) * intltool (gui) * libglib2.0-dev (gui) * libdbus-glib-1-dev (gui) * libgtk-3-dev (gui) * libgudev-1.0-dev (gui) * libwebkitgtk-3.0-dev (gui) * libnotify-dev (gui) * libgstreamer1.0-dev (gui) * libgstreamer-plugins-base1.0-dev (gui) * libappindicator-dev (gui) To install these packages: sudo apt-get install git cmake yasm build-essential autoconf libtool \ zlib1g-dev libbz2-dev libogg-dev libtheora-dev libvorbis-dev libopus-dev \ libsamplerate-dev libxml2-dev libfribidi-dev libfreetype6-dev \ libfontconfig1-dev libass-dev libmp3lame-dev libx264-dev libjansson-dev \ intltool libglib2.0-dev libdbus-glib-1-dev libgtk-3-dev libgudev-1.0-dev \ libwebkitgtk-3.0-dev libnotify-dev libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev libappindicator-dev Additional Ubuntu 16.04 packages: * libtool-bin (cli/gui) To install these packages: sudo apt-get install libtool-bin Fedora 20 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 packages: * patch (cli/gui) * intltool (cli/gui) * libtool (cli/gui) * cmake (cli/gui) * gcc-c++ (cli/gui) * yasm (cli/gui) * zlib-devel (cli/gui) * bzip2-devel (cli/gui) * libogg-devel (cli/gui) * libtheora-devel (cli/gui) * libvorbis-devel (cli/gui) * opus-devel (cli/gui) * libsamplerate-devel (cli/gui) * libxml2-devel (cli/gui) * fribidi-devel (cli/gui) * freetype-devel (cli/gui) * fontconfig-devel (cli/gui) * libass-devel (cli/gui) * lame-devel (cli/gui) * x264-devel (cli/gui) * jansson-devel (cli/gui) * dbus-glib-devel (gui) * libgudev1-devel (gui) * webkitgtk3-devel (gui) * libnotify-devel (gui) * gstreamer1-devel (gui) * gstreamer1-plugins-base-devel (gui) To install these packages: sudo yum install patch intltool libtool cmake gcc-c++ yasm zlib-devel \ bzip2-devel libogg-devel libtheora-devel libvorbis-devel opus-devel \ libsamplerate-devel libxml2-devel fribidi-devel freetype-devel \ fontconfig-devel libass-devel lame-devel x264-devel jansson-devel \ dbus-glib-devel libgudev1-devel webkitgtk3-devel libnotify-devel \ gstreamer1-devel gstreamer1-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. git clone https://github.com/HandBrake/HandBrake.git hb-master cd hb-master ./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. git clone https://github.com/HandBrake/HandBrake.git hb-master cd hb-master Sources are checked out from the 'master' 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. 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 * git 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 'bzip2', 'ffmpeg', 'fontconfig', 'freetype', 'fribidi', 'lame', 'libass', 'libbluray', 'libdvdnav', 'libdvdread', 'libiconv', 'libogg', 'libsamplerate', 'libtheora', 'libvorbis', 'libxml2', '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: https://github.com/HandBrake/HandBrake.git branch: master tag: rev: 7475 hash: aef9c01792bae5c656a6e026b31187cd4b9062d0 date: 2016-09-02 09:23:39 type: developer