00-BuildUserGuide.txt

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