00-Building.cygwin.txt

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