00.Building.osx.txt

   1 Guide to Building HandBrake svn2194 (2009030201) on Mac OS X
   2 ************************************************************
   3
   4      Warning: Parallel builds on Mac OS X are currently broken when
   5      building in a terminal with Xcode. You must not use the `make -jN'
   6      jobs option. A workaround is available if you do not need to build
   7      HandBrake.app (MacGUI): use `configure --disable-xcode' to disable
   8      Xcode.
   9
  10 Table of Contents
  11 *****************
  12
  13 1 Introduction
  14 2 Prerequisites
  15 3 QuickStart
  16 4 Overview
  17 5 Building via Terminal
  18   5.1 Checkout Sources
  19   5.2 Configure
  20   5.3 Build
  21   5.4 Make Targets
  22     5.4.1 Global
  23     5.4.2 General Modules
  24     5.4.3 Contrib Modules
  25     5.4.4 Contrib Aggregates
  26 6 Building via Xcode
  27   6.1 Checkout Sources
  28   6.2 Build
  29
  30
  31 1 Introduction
  32 **************
  33
  34 This guide documents the recommended process to build HandBrake on
  35 Mac OS X hosts from the official source-code repository. Building from
  36 any other source is not supported.
  37
  38 2 Prerequisites
  39 ***************
  40
  41 Building on Mac OS X is well supported. It is the reference platform
  42 for HandBrake. The following are the recommended specifications for
  43 this platform; but is not necessarily the only configuration that is
  44 possible:
  45
  46    * Mac Intel hardware
  47
  48    * Mac OS X 10.5.6
  49
  50    * Xcode-3.1.2
  51
  52    * gcc 4.0.1 (Apple Inc. build 5490)
  53
  54    * yasm 0.7.2.2153 (for i386 and x86_64 architectures)
  55
  56      Note: It is recommended to use the platform distribution's bundled
  57      compiler for maximum C++ compatibility. If you build with a custom
  58      compiler it will likely introduce non-standard runtime
  59      requirements. There are of course many valid reasons to build with
  60      unbundled compilers, but be aware it is generally unsupported and
  61      left as an exercise to the reader.
  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. If more flexibility is required you should
  87 skip this chapter and jump to *Note overview::.
  88
  89      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
  90      cd hb-trunk
  91      ./configure --launch
  92
  93 The special option `--launch' selected launch mode and performs the
  94 following steps:
  95
  96    * assert scratch directory `build/' does not exist
  97
  98    * create scratch directory `build/'
  99
 100    * change to directory `build/'
 101
 102    * launch `make'
 103
 104    * capture build output to `build/log.txt'
 105
 106    * echo build output
 107
 108 4 Overview
 109 **********
 110
 111 The two general methods to build on Mac OS X are building from terminal
 112 or Xcode. The preferred method for automated and repeatable builds is
 113 to use the terminal. Otherwise the choice is generally up to the
 114 individual. In essence, the terminal actually invokes `xcodebuild' to
 115 build the very same targets contained in the Xcode project.
 116
 117 5 Building via Terminal
 118 ***********************
 119
 120 5.1 Checkout Sources
 121 ====================
 122
 123 Checkout HandBrake from the official source-code repository.
 124
 125      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 126      cd hb-trunk
 127
 128 Sources are checked out from the `trunk' branch. This document was
 129 generated from that very branch, and for example purposes, we will use
 130 exactly the same branch.
 131
 132 If you have write-access to the repository, then you may add the
 133 appropriate login/password information as needed. It is recommended to
 134 use Subversion 1.5.0 or higher. Lower versions should also work.
 135
 136 5.2 Configure
 137 =============
 138
 139 Configure the build system.
 140
 141      rm -fr build/
 142      mkdir build/
 143      cd build/
 144      ../configure
 145
 146 Create a scratch directory which will contain all files created during
 147 the build process. The directory name is arbitrary but we recommend
 148 something simple and descriptive. One directory is required for each
 149 distinctly configured build. We name our directory `build' for example
 150 purposes.
 151
 152 The `configure' utility accepts many options. It is recommended that
 153 you specify `--help' for the complete list of options. The following
 154 options are also documented here:
 155
 156 `--help'
 157      List available options.
 158
 159 `--prefix=PREFIX'
 160      Specify destination directory for final product install.  This
 161      defaults to a reasonable platform-specific value.
 162
 163 `--disable-xcode'
 164      Disable driving the build through Xcode. If this option is
 165      disabled only `HandBrakeCLI' will be produced and Xcode will not
 166      be invoked. Mac OS X only.
 167
 168 `--disable-gtk'
 169      Disable building the GTK GUI on applicable platforms such as
 170      Linux.
 171
 172 `--debug=MODE'
 173      Select debug mode. Must be one of `none', `min', `std', `max'.
 174      This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
 175
 176 `--optimize=MODE'
 177      Select optimize mode. Must be one of `none', `speed', `size'.
 178      This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
 179
 180 `--arch=MODE'
 181      Select build architecture. The available architectures vary by
 182      platform. Most platforms support exactly one architecture except
 183      Mac OS X which has support for various universal binary
 184      architectures. The available choices are hard-coded per platform
 185      and no sanity checks for the required tools are performed.
 186
 187 `--gcc=EXE'
 188      Specify the `gcc' executable to use where EXE is the executable
 189      name which is either absolute or environment `PATH' is searched
 190      accordingly.
 191
 192 Clean-room procedures dictate that when certain factors change, old
 193 builds should be scrapped and new builds configured. This is the main
 194 reason for requiring a scratch directory; to promote consistent,
 195 reliable and clean software builds. The following is a short list of
 196 some of the reasons why someone may choose to scrap an existing build:
 197
 198    * configure with different options
 199
 200    * subversion working dir is updated and you want configure to
 201      re-evaluate working dir metadata.
 202
 203    * build corruption is suspected
 204
 205 There are generally two methods for scrapping a build. The `build'
 206 directory can be recusrively removed which has the effect of loosing
 207 your existing configuration but does guarantee no residuals are left
 208 behind. The other method is to ask the build system to perform an `make
 209 xclean'. This is known to work well but will leave empty directories
 210 behind. However, the configuration is left intact.
 211
 212 5.3 Build
 213 =========
 214
 215 Build main product. All necessary dependencies are also built if
 216 required.
 217
 218      make
 219
 220 Parallel builds may optionally be enabled. Be aware that while a
 221 parallel build may save time on systems with additional cores, the
 222 output is often mixed, overlapped and sometimes even corrupted with
 223 binary characters. Thus if you experience a build issue, you should
 224 clean and redo the build in default serial mode to produce a readable
 225 log. The following command allows for up to 4 concurrent jobs via make:
 226
 227      make -j4
 228
 229 5.4 Make Targets
 230 ================
 231
 232 The build system supports passing many kinds of targets some of which
 233 become very useful in normal development cycles. The targets by
 234 convention are lower-case words passed to `make'. Global targets are
 235 one-word targets. Scoped targets are usually two-words seperated by a
 236 period.
 237
 238 5.4.1 Global
 239 ------------
 240
 241 `make'
 242      Alias for `make build'.
 243
 244 `make build'
 245      Build main product. All necessary dependencies are also built if
 246      required.
 247
 248 `make clean'
 249      Clean all build output excluding contrib modules. Configuration is
 250      retained.
 251
 252 `make xclean'
 253      Clean all build output including contrib modules. Configuration is
 254      retained.
 255
 256 `make doc'
 257      Build auto-generated project documentation. Various articles are
 258      produced and may be found in `build/doc/articles'.
 259
 260 5.4.2 General Modules
 261 ---------------------
 262
 263 General modules such as `libhb', `test' and `gtk' have the following
 264 scoped targets:
 265
 266 `make MODULE.build'
 267      Build MODULE.
 268
 269 `make MODULE.clean'
 270      Clean build output for MODULE.
 271
 272 5.4.3 Contrib Modules
 273 ---------------------
 274
 275 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 276 `lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
 277 `libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264',
 278 `xvidcore' and `zlib' have the following scoped targets:
 279
 280 `make MODULE.fetch'
 281      Download source tarball from the Internet and save to
 282      `TOP/downloads' directory. No checksumming is performed.
 283
 284 `make MODULE.extract'
 285      Extract source tarball into `build' tree.
 286
 287 `make MODULE.patch'
 288      Apply appropriate patches (if any) to module sources.
 289
 290 `make MODULE.configure'
 291      Configure module sources.  This usually invokes autotool configure.
 292
 293 `make MODULE.build'
 294      Build module.  This usually invokes autotool build.
 295
 296 `make MODULE.install'
 297      Install module products such as headers and libraries into `build'
 298      tree.  This usually invokes autotool install.
 299
 300 `make MODULE.uninstall'
 301      Uninstall module products; generally the reverse of install.  This
 302      usually invokes autotool uninstall.
 303
 304 `make MODULE.clean'
 305      Clean module; generally the reverse of build.  This usually
 306      invokes autotool clean.
 307
 308 `make MODULE.xclean'
 309      Extra clean module; first invokes uninstall then recursively
 310      removes the module build directory.
 311
 312 5.4.4 Contrib Aggregates
 313 ------------------------
 314
 315 For convenience, the following targets aggregate the all contrib
 316 modules' respective targets together:
 317
 318    * make contrib.fetch
 319
 320    * make contrib.extract
 321
 322    * make contrib.patch
 323
 324    * make contrib.configure
 325
 326    * make contrib.build
 327
 328    * make contrib.install
 329
 330    * make contrib.uninstall
 331
 332    * make contrib.clean
 333
 334    * make contrib.xclean
 335
 336 6 Building via Xcode
 337 ********************
 338
 339 6.1 Checkout Sources
 340 ====================
 341
 342 Checkout HandBrake from the official source-code repository.
 343
 344      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 345      cd hb-trunk
 346
 347 Sources are checked out from the `trunk' branch. This document was
 348 generated from that very branch, and for example purposes, we will use
 349 exactly the same branch.
 350
 351 If you have write-access to the repository, then you may add the
 352 appropriate login/password information as needed. It is recommended to
 353 use Subversion 1.5.0 or higher. Lower versions should also work.
 354
 355 6.2 Build
 356 =========
 357
 358 In Xcode perform the following steps to build the default configuration:
 359
 360    * open `macosx/HandBrake.xcodeproj'
 361
 362    * select active configuration standard
 363
 364    * select active target HandBrake
 365
 366    * click Build or Build and Go
 367
 368 The first time it builds will take a bit of time. You may use the Build
 369 Results window to watch it progress. A large partof the build is
 370 invoking the external build system which poduces quite a lot of log
 371 output. Much of that output are warnings and errors that are part of
 372 the normal build process for 3rd-party contributed modules so in
 373 general you need not do anything. However, if Xcode itself reports the
 374 build failed, then you must take corrective action.
 375
 376 Unfortunately, due to limitations of Xcode we do not have hooks in
 377 place to offer finer-grained control over per-module make actions for
 378 the (external) build system. Thus, you will have to use terminal to
 379 accomplish those tasks. Just `cd' into the build directory which is
 380 associated with your active configuration and perform any necessary
 381 `make' commands. Be careful not to issue commands from the terminal
 382 simultaneously with Xcode tasks as that will confuse both Xcode and
 383 make and likely corrupt your build directory.
 384
 385 When you click clean in Xcode it will not perform an external build
 386 clean. Basically HandBrakeCLI and HandBrake.app are the only products
 387 which have full Xcode iterative development flexibility.
 388
 389 Each configuration uses a different `build' directory. This makes it
 390 possible to build each configuration and switch between them without
 391 losing their respective build state. The description of each
 392 configuration and the name convention for build directories are as
 393 follows:
 394
 395 `standard'
 396      This configuration will build to the host native architecture.
 397      Build directory is `build.standard' .  The standard variant
 398      produces optimized code without debug information.
 399
 400 `debug'
 401      This configuration will build to the host native architecture.
 402      Build directory is `build.standard' .  The debug variant produces
 403      unoptimized code with debug information.
 404
 405 `standard.i386'
 406      This configuration is used to build for the i386 architecture.
 407      Build directory is `build.standard.i386' .
 408
 409 `standard.x86_64'
 410      This configuration is used to build for the x86_64 architecture.
 411      Build directory is `build.standard.x86_64' .
 412
 413 `standard.ppc'
 414      This configuration is used to build for the ppc architecture.
 415      Build directory is `build.standard.ppc' .
 416
 417 `standard.ppc64'
 418      This configuration is used to build for the ppc64 architecture.
 419      Build directory is `build.standard.ppc64' .
 420