doc/BUILD-Linux

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