doc/BUILD-Linux

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