doc/BUILD-Linux

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