Building via Terminal
*********************

Checkout Sources
================

     [file method.checkout.texi not included]

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. only.

--disable-gtk
     Disable building the GTK GUI on applicable platforms such as.

--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 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.

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

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.

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.

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.

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.

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

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