doc/BUILD-Linux

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