doc/BUILD-Cygwin

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