00.Building.cygwin.txt

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