doc/BUILD-Linux

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