doc/BUILD-Linux

   1 Guide to Building HandBrake svn3555 (2010092801) on Linux
   2 *********************************************************
   3
   4 Table of Contents
   5 *****************
   6
   7 1 Introduction
   8 2 Prerequisites
   9 3 QuickStart
  10 4 Overview
  11 5 Building via Terminal
  12   5.1 Checkout Sources
  13   5.2 Configure
  14   5.3 Build
  15   5.4 Make Targets
  16     5.4.1 Global
  17     5.4.2 General Modules
  18     5.4.3 Contrib Modules
  19     5.4.4 Contrib Touch and Untouch
  20     5.4.5 Contrib Aggregates
  21   5.5 Customizing Make
  22 6 Troubleshooting
  23 Appendix A Project Repository Details
  24
  25
  26 1 Introduction
  27 **************
  28
  29 This guide documents the recommended process to build HandBrake on
  30 Linux hosts from the official source-code repository. Building from any
  31 other source is not supported.
  32
  33 2 Prerequisites
  34 ***************
  35
  36 The following are the recommended specifications for building on
  37 Linux; but is not necessarily the only configuration that is possible:
  38
  39    * Intel 32-bit or 64-bit kernel
  40
  41    * Ubuntu 8.04, gcc 4.3.0, yasm 0.7.1
  42
  43    * Ubuntu 8.10, gcc 4.3.2, yasm 0.7.1
  44
  45    * Ubuntu 9.04, gcc 4.3.3, yasm 0.7.1
  46
  47    * Ubuntu 9.10, gcc 4.4.1, yasm 0.8.0
  48
  49    * Fedora 9, gcc 4.3.0, yasm 0.7.1
  50
  51    * Fedora 10, gcc 4.3.2, yasm 0.7.1
  52
  53    * Fedora 11, gcc 4.4.0, yasm 0.7.2
  54
  55    * Fedora 12, gcc 4.4.2, yasm 0.7.2
  56
  57    * gcc 4.0.0 or higher is reported to work
  58
  59      Note: It is recommended to use the platform distribution's bundled
  60      compiler for maximum C++ compatibility. If you build with a custom
  61      compiler it will likely introduce non-standard runtime
  62      requirements. There are of course many valid reasons to build with
  63      unbundled compilers, but be aware it is generally unsupported and
  64      left as an exercise to the reader.
  65
  66 The following general tools are used on various platforms and it is
  67 recommended you use these versions or similar:
  68
  69    * subversion - 1.6.2
  70
  71    * python - Python 2.4.6
  72
  73    * curl - curl 7.19.4 (or wget)
  74
  75    * m4 - GNU M4 1.4.6
  76
  77    * make - GNU Make 3.81
  78
  79    * patch - Patch 2.5.8
  80
  81    * tar - GNU tar 1.15.1
  82
  83    * wget - GNU Wget 1.11.4 (or curl)
  84
  85 The GTK UI introduces some significant extra build requirements. If you
  86 intend to disable building the GUI with `configure --disable-gtk' you
  87 will not need many of these packages installed:
  88
  89 Ubuntu 9.10 - 10.04 packages:
  90    * subversion (cli/gui)
  91
  92    * yasm (cli/gui)
  93
  94    * build-essential (cli/gui)
  95
  96    * autoconf (cli/gui)
  97
  98    * libtool (cli/gui)
  99
 100    * zlib1g-dev (cli/gui)
 101
 102    * libbz2-dev (cli/gui)
 103
 104    * intltool (gui)
 105
 106    * libglib2.0-dev (gui)
 107
 108    * libdbus-glib-1-dev (gui)
 109
 110    * libgtk2.0-dev (gui)
 111
 112    * libgudev-1.0-dev (gui)
 113
 114    * libwebkit-dev (gui)
 115
 116    * libnotify-dev (gui)
 117
 118    * libgstreamer0.10-dev (gui)
 119
 120    * libgstreamer-plugins-base0.10-dev (gui)
 121
 122 To install these packages:
 123      sudo apt-get install subversion yasm build-essential \
 124      autoconf libtool zlib1g-dev libbz2-dev intltool libglib2.0-dev \
 125      libdbus-glib-1-dev libgtk2.0-dev libgudev-1.0-dev \
 126      libwebkit-dev libnotify-dev libgstreamer0.10-dev \
 127      libgstreamer-plugins-base0.10-dev
 128
 129 Fedora 12 - 13 package groups:
 130    * Development Tools
 131
 132    * Development Libraries
 133
 134    * X Software Development (gui)
 135
 136    * GNOME Software Development (gui)
 137
 138 To install these package groups:
 139      sudo yum groupinstall "Development Tools" "Development Libraries" \
 140      "X Software Development" "GNOME Software Development"
 141
 142 Additional Fedora packages:
 143    * yasm (cli/gui)
 144
 145    * zlib-devel (cli/gui)
 146
 147    * bzip2-devel (cli/gui)
 148
 149    * dbus-glib-devel (gui)
 150
 151    * libgudev1-devel (gui)
 152
 153    * webkitgtk-devel (gui)
 154
 155    * libnotify-devel (gui)
 156
 157    * gstreamer-devel (gui)
 158
 159    * gstreamer-plugins-base-devel (gui)
 160
 161 To install these packages:
 162      sudo yum install yasm zlib-devel bzip2-devel \
 163      dbus-glib-devel libgudev1-devel webkitgtk-devel libnotify-devel \
 164      gstreamer-devel gstreamer-plugins-base-devel
 165
 166 3 QuickStart
 167 ************
 168
 169 This chapter is for building from a terminal/shell environment in as
 170 few commands as possible. Upon completion of the following commands you
 171 should have a fresh build of HandBrake. Further instructions are
 172 available beginning with *note overview:: which describes procedures
 173 suitable for repeating builds. This chapter should be skipped by those
 174 seeking more than a minimalist build.
 175
 176      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 177      cd hb-trunk
 178      ./configure --launch
 179
 180 The special option `--launch' selects launch mode and performs the
 181 following steps:
 182
 183    * assert scratch directory `build/' does not exist
 184
 185    * create scratch directory `build/'
 186
 187    * change to directory `build/'
 188
 189    * launch `make'
 190
 191    * capture build output to `build/log/build.txt'
 192
 193    * echo build output
 194
 195    * print elapsed time
 196
 197    * indicate if build ultimately succeeded or failed
 198
 199 4 Overview
 200 **********
 201
 202 Linux builds are performed from a terminal. There is no support for
 203 building from any IDEs.
 204
 205 5 Building via Terminal
 206 ***********************
 207
 208 5.1 Checkout Sources
 209 ====================
 210
 211 Checkout HandBrake from the official source-code repository.
 212
 213      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 214      cd hb-trunk
 215
 216 Sources are checked out from the `trunk' branch. This document was
 217 generated from that very branch, and for example purposes, we will use
 218 exactly the same branch.
 219
 220 If you have write-access to the repository, then you may add the
 221 appropriate login/password information as needed. It is recommended to
 222 use Subversion 1.5.0 or higher. Lower versions should also work.
 223
 224 5.2 Configure
 225 =============
 226
 227 Configure the build system.
 228
 229      ./configure
 230
 231 Configure will automatically create a scratch build directory `build'
 232 unless you use GNU-style build procedures and first `cd' to a directory
 233 other than top-level source. Additionally you may use `--build' to
 234 specify the directory. The name of the directory is arbitrary but it is
 235 recommended to use something which indicates transient files which are
 236 not checked into the repository.
 237
 238 The `configure' utility accepts many options. It is recommended that
 239 you specify `--help' for the complete list of options. The following
 240 options are also documented here:
 241
 242 `--help'
 243      List available options.
 244
 245 `--src=DIR'
 246      Specify top-level source directory for HandBrake sources.
 247
 248 `--build=DIR'
 249      Specify destination directory for final product install. The
 250      default is to use either `build' if in the top-level source
 251      directory, otherwise `.'
 252
 253 `--prefix=DIR'
 254      Specify destination directory for final product install.  This
 255      defaults to a reasonable platform-specific value.
 256
 257 `--launch'
 258      All-in-one option which launches the build and logs output
 259      automatically.  Useful for novices and quick-start procedures.
 260
 261 `--disable-xcode'
 262      Disable shunting the build through `xcodebuild'. If this option is
 263      applied, `HandBrakeCLI' will be produced in a similar fashion as
 264      it is on other platforms; sans Xcode and the Cocoa application
 265      will not be produced. Mac OS X only.
 266
 267 `--disable-gtk'
 268      Disable building the GTK GUI on applicable platforms such as
 269      Linux.
 270
 271 `--debug=MODE'
 272      Select debug mode. Must be one of `none', `min', `std', `max'.
 273      This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
 274
 275 `--optimize=MODE'
 276      Select optimize mode. Must be one of `none', `speed', `size'.
 277      This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
 278
 279 `--arch=MODE'
 280      Select build architecture. The available architectures vary by
 281      platform. Most platforms support exactly one architecture except
 282      Mac OS X which has support for various universal binary
 283      architectures. The available choices are hard-coded per platform
 284      and no sanity checks for the required tools are performed.
 285
 286
 287 Clean-room procedures dictate that when certain factors change, old
 288 builds should be scrapped and new builds configured. This is the main
 289 reason for requiring a scratch directory; to promote consistent,
 290 reliable and clean software builds. The following is a short list of
 291 some of the reasons why someone may choose to scrap an existing build:
 292
 293    * configure with different options
 294
 295    * subversion working dir is updated and you want configure to
 296      re-evaluate working dir metadata.
 297
 298    * build corruption is suspected
 299
 300 There are generally two methods for scrapping a build. The `build'
 301 directory can be recursively removed which has the effect of loosing
 302 your existing configuration but does guarantee no residuals are left
 303 behind. The other method is to ask the build system to perform an `make
 304 xclean'. This is known to work well but will leave empty directories
 305 behind. However, the configuration is left intact.
 306
 307 5.3 Build
 308 =========
 309
 310 Build main product. All necessary dependencies are also built if
 311 required.
 312
 313      make
 314
 315 Parallel builds may optionally be enabled. Be aware that while a
 316 parallel build may save time on systems with additional cores, the
 317 output is often mixed, overlapped and sometimes even corrupted with
 318 binary characters. Thus if you experience a build issue, you should
 319 clean and redo the build in default serial mode to produce a readable
 320 log. The following command allows for up to 4 concurrent jobs via make:
 321
 322      make -j4
 323
 324 5.4 Make Targets
 325 ================
 326
 327 The build system supports passing many kinds of targets some of which
 328 become very useful in normal development cycles. The targets by
 329 convention are lower-case words passed to `make'. Global targets are
 330 one-word targets. Scoped targets are usually two-words separated by a
 331 period.
 332
 333 5.4.1 Global
 334 ------------
 335
 336 `make'
 337      Alias for `make build'.
 338
 339 `make build'
 340      Build main product. All necessary dependencies are also built if
 341      required.
 342
 343 `make clean'
 344      Clean all build output excluding contrib modules. Configuration is
 345      retained.
 346
 347 `make install'
 348      Perform final product(s) install.  This will install build
 349      products to a standard directory or one specified via `configure
 350      --prefix' option.
 351
 352 `make uninstall'
 353      Perform final product(s) uninstall.  This will uninstall any
 354      products which may have been previously installed.
 355
 356 `make xclean'
 357      Clean all build output including contrib modules. Configuration is
 358      retained.
 359
 360 `make doc'
 361      Build auto-generated project documentation. Various articles are
 362      produced and may be found in `build/doc/articles'.
 363
 364 `make report.help'
 365      Print list of available makefile vars report targets.  These
 366      reports detail var definitions and expanded values used by the
 367      build system.  For experts only.
 368
 369 `make report.all'
 370      Convenience target which aggregates all reports.  For experts only.
 371
 372 5.4.2 General Modules
 373 ---------------------
 374
 375 General modules such as `libhb', `test' and `gtk' have the following
 376 scoped targets:
 377
 378 `make MODULE.build'
 379      Build MODULE.
 380
 381 `make MODULE.clean'
 382      Clean build output for MODULE.
 383
 384 5.4.3 Contrib Modules
 385 ---------------------
 386
 387 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 388 `lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate',
 389 `libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have
 390 the following scoped targets:
 391
 392 `make MODULE.fetch'
 393      Download source tarball from the Internet and save to
 394      `TOP/downloads' directory. No check-summing is performed.
 395
 396 `make MODULE.extract'
 397      Extract source tarball into `build' tree.
 398
 399 `make MODULE.patch'
 400      Apply appropriate patches (if any) to module sources.
 401
 402 `make MODULE.configure'
 403      Configure module sources.  This usually invokes autotool configure.
 404
 405 `make MODULE.build'
 406      Build module.  This usually invokes autotool build.
 407
 408 `make MODULE.install'
 409      Install module products such as headers and libraries into `build'
 410      tree.  This usually invokes autotool install.
 411
 412 `make MODULE.uninstall'
 413      Uninstall module products; generally the reverse of install.  This
 414      usually invokes autotool uninstall.
 415
 416 `make MODULE.clean'
 417      Clean module; generally the reverse of build.  This usually
 418      invokes autotool clean.
 419
 420 `make MODULE.xclean'
 421      Extra clean module; first invokes uninstall then recursively
 422      removes the module build directory.
 423
 424 5.4.4 Contrib Touch and Untouch
 425 -------------------------------
 426
 427 Also available are some very granular targets which help force builds
 428 from specific cycle points. The following targets are available to
 429 touch and untouch the respective module target; this will force the
 430 build system to treat the target as satisfied after a touch or
 431 unsatisfied after an untouch:
 432
 433    * make MODULE.extract.touch
 434
 435    * make MODULE.extract.untouch
 436
 437    * make MODULE.patch.touch
 438
 439    * make MODULE.patch.untouch
 440
 441    * make MODULE.configure.touch
 442
 443    * make MODULE.configure.untouch
 444
 445    * make MODULE.build.touch
 446
 447    * make MODULE.build.untouch
 448
 449    * make MODULE.install.touch
 450
 451    * make MODULE.install.untouch
 452
 453 5.4.5 Contrib Aggregates
 454 ------------------------
 455
 456 For convenience, the following targets aggregate the all contrib
 457 modules' respective targets together:
 458
 459    * make contrib.fetch
 460
 461    * make contrib.extract
 462
 463    * make contrib.patch
 464
 465    * make contrib.configure
 466
 467    * make contrib.build
 468
 469    * make contrib.install
 470
 471    * make contrib.uninstall
 472
 473    * make contrib.clean
 474
 475    * make contrib.xclean
 476
 477 5.5 Customizing Make
 478 ====================
 479
 480 If the need arises to override settings in the build system
 481 (essentially gnu-make variables) the recommended method is to create
 482 optional include files which are automatically included if present and
 483 follow this naming convention; Do not check these files into the
 484 repository:
 485
 486 `_SRC_/custom.defs'
 487      Custom makevar definitions outside `build'. Suitable for settings
 488      which apply across all builds for a particular checkout; or which
 489      survives manual removal of `build'.
 490
 491 `_SRC_/custom.rules'
 492      Custom make rules outside `build'. Suitable for rules which apply
 493      across all builds for a particular checkout; or which survives
 494      manual removal of `build'.
 495
 496 `_BUILD_/GNUmakefile.custom.defs'
 497      Custom makevar definitions specific to a `build' directory.
 498
 499 `_BUILD_/GNUmakefile.custom.rules'
 500      Custom makevar rules specific to a `build' directory.
 501
 502
 503 The purpose is to allow a place to store local build settings for
 504 testing, tweaking, and experimenting with build configuration without
 505 losing your settings if `configure' is invoked; ie: `configure' would
 506 overwrite `GNUmakefile' and any customizations contained therein would
 507 be lost. Here is a short example of what the contents of
 508 `_SRC_/custom.defs' might contain:
 509
 510      ## bump to gcc-4.2 in current path
 511      GCC.gcc = /usr/bin/gcc-4.2
 512
 513      ## replace optimize for 'speed' with more aggressive settings
 514      GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 515
 516 See also `make report.help' which displays a set of reports used to
 517 dump makefile vars.
 518
 519 6 Troubleshooting
 520 *****************
 521
 522 When troubleshooting build issues, the following files relative to the
 523 `build/' directory may be especially useful:
 524
 525 `GNUmakefile'
 526      Top-level makefile which contains build settings generated via
 527      configure.
 528
 529 `log/config.info.txt'
 530      Record of output from configure.
 531
 532 `log/config.verbose.txt'
 533      Record of verbose output from configure.
 534
 535 `log/build.txt'
 536      Record of output from `configure --launch'. Similar output may be
 537      recorded using `make' depending on which shell is in use, eg:
 538      `make >& log/build.txt' or `make > log/build.txt 2>&1'.
 539
 540 `log/xcodemake.env.txt'
 541      Environment (variables) dump as seen when Xcode forks `make'.
 542      Mac OS X only.
 543
 544 Appendix A Project Repository Details
 545 *************************************
 546
 547      url:    svn://svn.handbrake.fr/HandBrake/trunk
 548      root:   svn://svn.handbrake.fr/HandBrake
 549      branch: trunk
 550      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
 551      rev:    3555
 552      date:   2010-09-26 09:13:48 -0700
 553      type:   developer
 554