doc/BUILD-Mac

   1 Build Guide for HandBrake svn2252 on Mac OS X
   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   5.6 Universal Binaries
  23 6 Building via Xcode
  24   6.1 Checkout Sources
  25   6.2 Build
  26   6.3 External Targets
  27   6.4 User-Defined Settings
  28 Appendix A Project Repository Details
  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. 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 The two general methods to build on Mac OS X are building from terminal
 119 or Xcode. The preferred method for automated and repeatable builds is
 120 to use the terminal. Otherwise the choice is generally up to the
 121 individual. In essence, the terminal actually invokes `xcodebuild' to
 122 build the very same targets contained in the Xcode project.
 123
 124 5 Building via Terminal
 125 ***********************
 126
 127 5.1 Checkout Sources
 128 ====================
 129
 130 Checkout HandBrake from the official source-code repository.
 131
 132      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 133      cd hb-trunk
 134
 135 Sources are checked out from the `trunk' branch. This document was
 136 generated from that very branch, and for example purposes, we will use
 137 exactly the same branch.
 138
 139 If you have write-access to the repository, then you may add the
 140 appropriate login/password information as needed. It is recommended to
 141 use Subversion 1.5.0 or higher. Lower versions should also work.
 142
 143 5.2 Configure
 144 =============
 145
 146 Configure the build system.
 147
 148      ./configure
 149
 150 Configure will automatically create a scratch build directory `build'
 151 unless you use GNU-style build procedures and first `cd' to a directory
 152 other than top-level source. Additionally you may specify use `--build'
 153 to specify the directory. The name of the directory is arbitrary but it
 154 is recommended to use something which indicates transient files which
 155 are not checked into the repository.
 156
 157 The `configure' utility accepts many options. It is recommended that
 158 you specify `--help' for the complete list of options. The following
 159 options are also documented here:
 160
 161 `--help'
 162      List available options.
 163
 164 `--src=DIR'
 165      Specify top-level source directory for HandBrake sources.
 166
 167 `--build=DIR'
 168      Specify destination directory for final product install. The
 169      default is to use either `build' if in the top-level source
 170      directory, otherwise `.'
 171
 172 `--prefix=DIR'
 173      Specify destination directory for final product install.  This
 174      defaults to a reasonable platform-specific value.
 175
 176 `--launch'
 177      All-in-one option which launches the build and logs output
 178      automatically.  Useful for novices and quickstart procedures.
 179
 180 `--disable-xcode'
 181      Disable shunting the build through Xcode. If this option is
 182      applied, `HandBrakeCLI' will be produced in a similare fashion as
 183      it is on other platforms; sans Xcode. Mac OS X only.
 184
 185 `--disable-gtk'
 186      Disable building the GTK GUI on applicable platforms such as
 187      Linux.
 188
 189 `--debug=MODE'
 190      Select debug mode. Must be one of `none', `min', `std', `max'.
 191      This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
 192
 193 `--optimize=MODE'
 194      Select optimize mode. Must be one of `none', `speed', `size'.
 195      This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
 196
 197 `--arch=MODE'
 198      Select build architecture. The available architectures vary by
 199      platform. Most platforms support exactly one architecture except
 200      Mac OS X which has support for various universal binary
 201      architectures. The available choices are hard-coded per platform
 202      and no sanity checks for the required tools are performed.
 203
 204
 205 Clean-room procedures dictate that when certain factors change, old
 206 builds should be scrapped and new builds configured. This is the main
 207 reason for requiring a scratch directory; to promote consistent,
 208 reliable and clean software builds. The following is a short list of
 209 some of the reasons why someone may choose to scrap an existing build:
 210
 211    * configure with different options
 212
 213    * subversion working dir is updated and you want configure to
 214      re-evaluate working dir metadata.
 215
 216    * build corruption is suspected
 217
 218 There are generally two methods for scrapping a build. The `build'
 219 directory can be recusrively removed which has the effect of loosing
 220 your existing configuration but does guarantee no residuals are left
 221 behind. The other method is to ask the build system to perform an `make
 222 xclean'. This is known to work well but will leave empty directories
 223 behind. However, the configuration is left intact.
 224
 225 5.3 Build
 226 =========
 227
 228 Build main product. All necessary dependencies are also built if
 229 required.
 230
 231      make
 232
 233 Parallel builds may optionally be enabled. Be aware that while a
 234 parallel build may save time on systems with additional cores, the
 235 output is often mixed, overlapped and sometimes even corrupted with
 236 binary characters. Thus if you experience a build issue, you should
 237 clean and redo the build in default serial mode to produce a readable
 238 log. The following command allows for up to 4 concurrent jobs via make:
 239
 240      make -j4
 241
 242 5.4 Make Targets
 243 ================
 244
 245 The build system supports passing many kinds of targets some of which
 246 become very useful in normal development cycles. The targets by
 247 convention are lower-case words passed to `make'. Global targets are
 248 one-word targets. Scoped targets are usually two-words seperated by a
 249 period.
 250
 251 5.4.1 Global
 252 ------------
 253
 254 `make'
 255      Alias for `make build'.
 256
 257 `make build'
 258      Build main product. All necessary dependencies are also built if
 259      required.
 260
 261 `make clean'
 262      Clean all build output excluding contrib modules. Configuration is
 263      retained.
 264
 265 `make install'
 266      Perform final product(s) install.  This will install build
 267      products to a standard directory or one specified via `configure
 268      --prefix' option.
 269
 270 `make uninstall'
 271      Perform final product(s) uninstall.  This will uninstall any
 272      products which may have been previously installed.
 273
 274 `make xclean'
 275      Clean all build output including contrib modules. Configuration is
 276      retained.
 277
 278 `make doc'
 279      Build auto-generated project documentation. Various articles are
 280      produced and may be found in `build/doc/articles'.
 281
 282 `make report.help'
 283      Print list of available makefile vars report targets.  These
 284      reports detail var definitions and expanded values used by the
 285      build system.  For experts only.
 286
 287 `make report.all'
 288      Convenience target which aggregates all reports.  For experts only.
 289
 290 5.4.2 General Modules
 291 ---------------------
 292
 293 General modules such as `libhb', `test' and `gtk' have the following
 294 scoped targets:
 295
 296 `make MODULE.build'
 297      Build MODULE.
 298
 299 `make MODULE.clean'
 300      Clean build output for MODULE.
 301
 302 5.4.3 Contrib Modules
 303 ---------------------
 304
 305 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 306 `lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
 307 `libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264',
 308 `xvidcore' and `zlib' have the following scoped targets:
 309
 310 `make MODULE.fetch'
 311      Download source tarball from the Internet and save to
 312      `TOP/downloads' directory. No checksumming is performed.
 313
 314 `make MODULE.extract'
 315      Extract source tarball into `build' tree.
 316
 317 `make MODULE.patch'
 318      Apply appropriate patches (if any) to module sources.
 319
 320 `make MODULE.configure'
 321      Configure module sources.  This usually invokes autotool configure.
 322
 323 `make MODULE.build'
 324      Build module.  This usually invokes autotool build.
 325
 326 `make MODULE.install'
 327      Install module products such as headers and libraries into `build'
 328      tree.  This usually invokes autotool install.
 329
 330 `make MODULE.uninstall'
 331      Uninstall module products; generally the reverse of install.  This
 332      usually invokes autotool uninstall.
 333
 334 `make MODULE.clean'
 335      Clean module; generally the reverse of build.  This usually
 336      invokes autotool clean.
 337
 338 `make MODULE.xclean'
 339      Extra clean module; first invokes uninstall then recursively
 340      removes the module build directory.
 341
 342 5.4.4 Contrib Touch and Untouch
 343 -------------------------------
 344
 345 Also available are some very granular targets which help force builds
 346 from specific cycle points. The following targets are available to
 347 touch and untouch the respective module target; this will force the
 348 build system to treat the target as satisfied after a touch or
 349 unsatisfied after an untouch:
 350
 351    * make MODULE.extract.touch
 352
 353    * make MODULE.extract.untouch
 354
 355    * make MODULE.patch.touch
 356
 357    * make MODULE.patch.untouch
 358
 359    * make MODULE.configure.touch
 360
 361    * make MODULE.configure.untouch
 362
 363    * make MODULE.build.touch
 364
 365    * make MODULE.build.untouch
 366
 367    * make MODULE.install.touch
 368
 369    * make MODULE.install.untouch
 370
 371 5.4.5 Contrib Aggregates
 372 ------------------------
 373
 374 For convenience, the following targets aggregate the all contrib
 375 modules' respective targets together:
 376
 377    * make contrib.fetch
 378
 379    * make contrib.extract
 380
 381    * make contrib.patch
 382
 383    * make contrib.configure
 384
 385    * make contrib.build
 386
 387    * make contrib.install
 388
 389    * make contrib.uninstall
 390
 391    * make contrib.clean
 392
 393    * make contrib.xclean
 394
 395 5.5 Customizing Make
 396 ====================
 397
 398 If the need arises to override settings in the build system
 399 (essentially gnu-make variables) the recommended method is to create
 400 optional include files which are automatically included if present and
 401 follow this naming convention; Do not check these files into the
 402 respository:
 403
 404 `_SRC_/custom.defs'
 405      Custom makevar definitions outside `build'. Suitable for settings
 406      which apply across all builds for a particular checkout; or which
 407      survives manual removal of `build'.
 408
 409 `_SRC_/custom.rules'
 410      Custom make rules outside `build'. Suitable for rules which apply
 411      across all builds for a particular checkout; or which survives
 412      manual removal of `build'.
 413
 414 `_BUILD_/GNUmakefile.custom.defs'
 415      Custom makevar definitions specific to a `build' directory.
 416
 417 `_BUILD_/GNUmakefile.custom.rules'
 418      Custom makevar rules specific to a `build' directory.
 419
 420
 421 The purpose is to allow a place to store local build settings for
 422 testing, tweaking, and experimenting with build configuration without
 423 losing your settings if `configure' is invoked; ie: `configure' would
 424 overwrite `GNUmakefile' and any customizations contained therein would
 425 be lost. Here is a short example of what the contents of
 426 `_SRC_/custom.defs' might contain:
 427
 428      ## bump to gcc-4.2 in current path
 429      GCC.gcc = gcc-4.2
 430
 431      ## replace optimize for 'speed' with more agressive settings
 432      GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 433
 434 See also `make report.help' which displays a set of reports used to
 435 dump makefile vars.
 436
 437 5.6 Universal Binaries
 438 ======================
 439
 440 This section outlines convenience procedures for creating Universal
 441 Binaries for all the architectures.
 442
 443      Note: The dummy (container) build configuration uses
 444      `--disable-xcode'; but the nested architecture builds will all
 445      make full use of Xcode.
 446
 447 Create a dummy (container) build configuration and use it to launch a
 448 nested-build for each architecture serially; optionally you may
 449 substitute `make ub.build.serial' for `make ub.build.parallel' if your
 450 machine has the horsepower:
 451
 452      ./configure --disable-xcode
 453      cd build/
 454      make ub.build.serial
 455      make ub.combine
 456
 457 To specify a subset of architectures to be built first create/edit
 458 `_SRC_/custom.defs' with the following override to build UB for `i386'
 459 and `x86_64' before invoking `make':
 460
 461      ## prefer i386 (order is important)
 462      UB.archs = i386 x86_64
 463
 464 6 Building via Xcode
 465 ********************
 466
 467 6.1 Checkout Sources
 468 ====================
 469
 470 Checkout HandBrake from the official source-code repository.
 471
 472      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 473      cd hb-trunk
 474
 475 Sources are checked out from the `trunk' branch. This document was
 476 generated from that very branch, and for example purposes, we will use
 477 exactly the same branch.
 478
 479 If you have write-access to the repository, then you may add the
 480 appropriate login/password information as needed. It is recommended to
 481 use Subversion 1.5.0 or higher. Lower versions should also work.
 482
 483 6.2 Build
 484 =========
 485
 486 In Xcode perform the following steps to build the default configuration:
 487
 488    * open `macosx/HandBrake.xcodeproj'
 489
 490    * select active configuration standard
 491
 492    * select active target HandBrake
 493
 494    * click Build or Build and Go
 495
 496 The first build (on an empty `build' directory) will take a bit of
 497 time. You may use the Build Results window to observe progress. The
 498 most time-consuming part of the build is when the external build system
 499 (essentially the terminal method) is triggered by Xcode and a
 500 substantial amount of log transcript ensues. Much of that transcript
 501 are warnings and errors that are part of the normal build process for
 502 3rd-party contributed modules so in general you need not do anything.
 503 However, if Xcode itself reports the build failed, then you must take
 504 corrective action.
 505
 506 Unfortunately, due to limitations of Xcode we do not have hooks in
 507 place to offer finer-grained control over per-module make actions for
 508 the (external) build system. Thus, you will have to use terminal to
 509 accomplish those tasks. Just `cd' into the build directory which is
 510 associated with your active configuration and perform any necessary
 511 `make' commands. Be careful not to issue commands from the terminal
 512 simultaneously with Xcode tasks as that will confuse both Xcode and
 513 make and likely corrupt your build directory.
 514
 515 When you click clean in Xcode it will not perform an external build
 516 clean. Basically HandBrakeCLI and HandBrake.app are the only products
 517 which have full Xcode iterative development flexibility.
 518
 519 Each configuration uses a different `build' directory. This makes it
 520 possible to build each configuration and switch between them without
 521 losing their respective build state. The description of each
 522 configuration and the name convention for build directories are as
 523 follows:
 524
 525 `standard'
 526      This configuration will build host native architecture. Build
 527      directory is `build.standard' .  The standard variant produces
 528      optimized code without debug information.
 529
 530 `standard.i386'
 531      This configuration will build i386 architecture. Build directory
 532      is `build.standard.i386' .
 533
 534 `standard.x86_64'
 535      This configuration will build x86_64 architecture. Build directory
 536      is `build.standard.x86_64' .
 537
 538 `standard.ppc'
 539      This configuration will build ppc architecture. Build directory is
 540      `build.standard.ppc' .
 541
 542 `standard.ppc64'
 543      This configuration will build ppc64 architecture. Build directory
 544      is `build.standard.ppc64' .
 545
 546 `debug'
 547      This configuration will build host native architecture. Build
 548      directory is `build.debug' .  The debug variant produces
 549      unoptimized code with debug information.
 550
 551 `debug.i386'
 552      This configuration will build i386 architecture. Build directory
 553      is `build.debug.i386' .  The debug variant produces unoptimized
 554      code with debug information.
 555
 556 `debug.x86_64'
 557      This configuration will build x86_64 architecture. Build directory
 558      is `build.debug.x86_64' .  The debug variant produces unoptimized
 559      code with debug information.
 560
 561 `debug.ppc'
 562      This configuration will build ppc architecture. Build directory is
 563      `build.debug.ppc' .  The debug variant produces unoptimized code
 564      with debug information.
 565
 566 `debug.ppc64'
 567      This configuration will build ppc64 architecture. Build directory
 568      is `build.debug.ppc64' .  The debug variant produces unoptimized
 569      code with debug information.
 570
 571 6.3 External Targets
 572 ====================
 573
 574 The following external targets appear in the Xcode project and perform
 575 build and clean actions.
 576
 577 `external'
 578      Target maps to `make build' and `make clean' for everything Xcode
 579      products depend upon from the external build system.
 580
 581 `libhb'
 582      Target maps to `make libhb.build' and `make libhb.clean'.
 583
 584 `contrib'
 585      Target maps to `make contrib.build' and `make contrib.xclean'.
 586
 587
 588 6.4 User-Defined Settings
 589 =========================
 590
 591 The following user defined settings are used in Xcode project for the
 592 external build system:
 593
 594 `EXTERNAL_BUILD'
 595      Specifies the build (scratch) directory for each configuration.
 596
 597 `EXTERNAL_JOBS'
 598      Specifies the concurrency factor for the external build system
 599      when builds are launched from within Xcode.  Modify for faster
 600      external builds if your system has the horsepower and resources.
 601      Specifying a value greater than the number of CPU cores (or
 602      virtual cores) in your system is unlikely to produce gains and
 603      will needlessly consume extra resources.
 604
 605 `EXTERNAL_METHOD'
 606      Do not modify; Used for internal/external build coordination and
 607      must always be `xcode'.
 608
 609 `EXTERNAL_SRC'
 610      Specifies the top-level source directory for HandBrake.
 611
 612
 613 Appendix A Project Repository Details
 614 *************************************
 615
 616      url:    svn://svn.handbrake.fr/HandBrake/trunk
 617      root:   svn://svn.handbrake.fr/HandBrake
 618      branch: trunk
 619      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
 620      rev:    2252
 621      date:   2009-03-10 18:43:11 -0400
 622      type:   developer
 623