00.Building.linux.txt

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