00-Building.linux.txt

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