doc/BUILD-Cygwin

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