doc/BUILD-Mac

   1 Build Guide for HandBrake svn3349 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.app
  24   6.1 Checkout Sources
  25   6.2 Build
  26   6.3 External Targets
  27   6.4 User-Defined Settings
  28 7 Troubleshooting
  29 Appendix A Project Repository Details
  30
  31
  32 1 Introduction
  33 **************
  34
  35 This guide documents the recommended process to build HandBrake on
  36 Mac OS X hosts from the official source-code repository. Building from
  37 any other source is not supported.
  38
  39 2 Prerequisites
  40 ***************
  41
  42 Building on Mac OS X is well supported. It is the reference platform
  43 for HandBrake. The following are the recommended specifications for
  44 this platform; but is not necessarily the only configuration that is
  45 possible:
  46
  47    * Mac Intel hardware
  48
  49    * Mac OS X 10.5.7
  50
  51    * Xcode-3.1.2
  52
  53    * gcc 4.0.1 (Apple Inc. build 5490)
  54
  55    * yasm 0.8.0.2194 (for i386 and x86_64 architectures)
  56
  57      Note: It is recommended to use the platform distribution's bundled
  58      compiler for maximum C++ compatibility. If you build with a custom
  59      compiler it will likely introduce non-standard runtime
  60      requirements. There are of course many valid reasons to build with
  61      unbundled compilers, but be aware it is generally unsupported and
  62      left as an exercise to the reader.
  63
  64 The following general tools are used on various platforms and it is
  65 recommended you use these versions or similar:
  66
  67    * subversion - 1.6.2
  68
  69    * python - Python 2.4.6
  70
  71    * curl - curl 7.19.4 (or wget)
  72
  73    * m4 - GNU M4 1.4.6
  74
  75    * make - GNU Make 3.81
  76
  77    * patch - Patch 2.5.8
  78
  79    * tar - GNU tar 1.15.1
  80
  81    * wget - GNU Wget 1.11.4 (or curl)
  82
  83 3 QuickStart
  84 ************
  85
  86 This chapter is for building from a terminal/shell environment in as
  87 few commands as possible. Upon completion of the following commands you
  88 should have a fresh build of HandBrake. Further instructions are
  89 available beginning with *Note overview:: which describes procedures
  90 suitable for repeating builds. This chapter should be skipped by those
  91 seeking more than a minimalist build.
  92
  93      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
  94      cd hb-trunk
  95      ./configure --launch
  96
  97 The special option `--launch' selects launch mode and performs the
  98 following steps:
  99
 100    * assert scratch directory `build/' does not exist
 101
 102    * create scratch directory `build/'
 103
 104    * change to directory `build/'
 105
 106    * launch `make'
 107
 108    * capture build output to `build/log/build.txt'
 109
 110    * echo build output
 111
 112    * print elapsed time
 113
 114    * indicate if build ultimately succeeded or failed
 115
 116 4 Overview
 117 **********
 118
 119 The two general methods to build on Mac OS X are from terminal or
 120 Xcode.app. The preferred method for automated and repeatable builds is
 121 to use the terminal. Otherwise the choice is generally up to the
 122 individual. To be extra clear, building from the terminal by default
 123 actually invokes `xcodebuild' to build the very same targets contained
 124 in the Xcode project. Think of it as building with Xcode but without
 125 the GUI.
 126
 127 5 Building via Terminal
 128 ***********************
 129
 130 5.1 Checkout Sources
 131 ====================
 132
 133 Checkout HandBrake from the official source-code repository.
 134
 135      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 136      cd hb-trunk
 137
 138 Sources are checked out from the `trunk' branch. This document was
 139 generated from that very branch, and for example purposes, we will use
 140 exactly the same branch.
 141
 142 If you have write-access to the repository, then you may add the
 143 appropriate login/password information as needed. It is recommended to
 144 use Subversion 1.5.0 or higher. Lower versions should also work.
 145
 146 5.2 Configure
 147 =============
 148
 149 Configure the build system.
 150
 151      ./configure
 152
 153 Configure will automatically create a scratch build directory `build'
 154 unless you use GNU-style build procedures and first `cd' to a directory
 155 other than top-level source. Additionally you may use `--build' to
 156 specify the directory. The name of the directory is arbitrary but it is
 157 recommended to use something which indicates transient files which are
 158 not checked into the repository.
 159
 160 The `configure' utility accepts many options. It is recommended that
 161 you specify `--help' for the complete list of options. The following
 162 options are also documented here:
 163
 164 `--help'
 165      List available options.
 166
 167 `--src=DIR'
 168      Specify top-level source directory for HandBrake sources.
 169
 170 `--build=DIR'
 171      Specify destination directory for final product install. The
 172      default is to use either `build' if in the top-level source
 173      directory, otherwise `.'
 174
 175 `--prefix=DIR'
 176      Specify destination directory for final product install.  This
 177      defaults to a reasonable platform-specific value.
 178
 179 `--launch'
 180      All-in-one option which launches the build and logs output
 181      automatically.  Useful for novices and quick-start procedures.
 182
 183 `--disable-xcode'
 184      Disable shunting the build through `xcodebuild'. If this option is
 185      applied, `HandBrakeCLI' will be produced in a similar fashion as
 186      it is on other platforms; sans Xcode and the Cocoa application
 187      will not be produced. Mac OS X only.
 188
 189 `--disable-gtk'
 190      Disable building the GTK GUI on applicable platforms such as
 191      Linux.
 192
 193 `--debug=MODE'
 194      Select debug mode. Must be one of `none', `min', `std', `max'.
 195      This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
 196
 197 `--optimize=MODE'
 198      Select optimize mode. Must be one of `none', `speed', `size'.
 199      This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
 200
 201 `--arch=MODE'
 202      Select build architecture. The available architectures vary by
 203      platform. Most platforms support exactly one architecture except
 204      Mac OS X which has support for various universal binary
 205      architectures. The available choices are hard-coded per platform
 206      and no sanity checks for the required tools are performed.
 207
 208
 209 Clean-room procedures dictate that when certain factors change, old
 210 builds should be scrapped and new builds configured. This is the main
 211 reason for requiring a scratch directory; to promote consistent,
 212 reliable and clean software builds. The following is a short list of
 213 some of the reasons why someone may choose to scrap an existing build:
 214
 215    * configure with different options
 216
 217    * subversion working dir is updated and you want configure to
 218      re-evaluate working dir metadata.
 219
 220    * build corruption is suspected
 221
 222 There are generally two methods for scrapping a build. The `build'
 223 directory can be recursively removed which has the effect of loosing
 224 your existing configuration but does guarantee no residuals are left
 225 behind. The other method is to ask the build system to perform an `make
 226 xclean'. This is known to work well but will leave empty directories
 227 behind. However, the configuration is left intact.
 228
 229 5.3 Build
 230 =========
 231
 232 Build main product. All necessary dependencies are also built if
 233 required.
 234
 235      make
 236
 237 Parallel builds may optionally be enabled. Be aware that while a
 238 parallel build may save time on systems with additional cores, the
 239 output is often mixed, overlapped and sometimes even corrupted with
 240 binary characters. Thus if you experience a build issue, you should
 241 clean and redo the build in default serial mode to produce a readable
 242 log. The following command allows for up to 4 concurrent jobs via make:
 243
 244      make -j4
 245
 246 5.4 Make Targets
 247 ================
 248
 249 The build system supports passing many kinds of targets some of which
 250 become very useful in normal development cycles. The targets by
 251 convention are lower-case words passed to `make'. Global targets are
 252 one-word targets. Scoped targets are usually two-words separated by a
 253 period.
 254
 255 5.4.1 Global
 256 ------------
 257
 258 `make'
 259      Alias for `make build'.
 260
 261 `make build'
 262      Build main product. All necessary dependencies are also built if
 263      required.
 264
 265 `make clean'
 266      Clean all build output excluding contrib modules. Configuration is
 267      retained.
 268
 269 `make install'
 270      Perform final product(s) install.  This will install build
 271      products to a standard directory or one specified via `configure
 272      --prefix' option.
 273
 274 `make uninstall'
 275      Perform final product(s) uninstall.  This will uninstall any
 276      products which may have been previously installed.
 277
 278 `make xclean'
 279      Clean all build output including contrib modules. Configuration is
 280      retained.
 281
 282 `make doc'
 283      Build auto-generated project documentation. Various articles are
 284      produced and may be found in `build/doc/articles'.
 285
 286 `make report.help'
 287      Print list of available makefile vars report targets.  These
 288      reports detail var definitions and expanded values used by the
 289      build system.  For experts only.
 290
 291 `make report.all'
 292      Convenience target which aggregates all reports.  For experts only.
 293
 294 5.4.2 General Modules
 295 ---------------------
 296
 297 General modules such as `libhb', `test' and `gtk' have the following
 298 scoped targets:
 299
 300 `make MODULE.build'
 301      Build MODULE.
 302
 303 `make MODULE.clean'
 304      Clean build output for MODULE.
 305
 306 5.4.3 Contrib Modules
 307 ---------------------
 308
 309 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
 310 `lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate',
 311 `libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have
 312 the following scoped targets:
 313
 314 `make MODULE.fetch'
 315      Download source tarball from the Internet and save to
 316      `TOP/downloads' directory. No check-summing is performed.
 317
 318 `make MODULE.extract'
 319      Extract source tarball into `build' tree.
 320
 321 `make MODULE.patch'
 322      Apply appropriate patches (if any) to module sources.
 323
 324 `make MODULE.configure'
 325      Configure module sources.  This usually invokes autotool configure.
 326
 327 `make MODULE.build'
 328      Build module.  This usually invokes autotool build.
 329
 330 `make MODULE.install'
 331      Install module products such as headers and libraries into `build'
 332      tree.  This usually invokes autotool install.
 333
 334 `make MODULE.uninstall'
 335      Uninstall module products; generally the reverse of install.  This
 336      usually invokes autotool uninstall.
 337
 338 `make MODULE.clean'
 339      Clean module; generally the reverse of build.  This usually
 340      invokes autotool clean.
 341
 342 `make MODULE.xclean'
 343      Extra clean module; first invokes uninstall then recursively
 344      removes the module build directory.
 345
 346 5.4.4 Contrib Touch and Untouch
 347 -------------------------------
 348
 349 Also available are some very granular targets which help force builds
 350 from specific cycle points. The following targets are available to
 351 touch and untouch the respective module target; this will force the
 352 build system to treat the target as satisfied after a touch or
 353 unsatisfied after an untouch:
 354
 355    * make MODULE.extract.touch
 356
 357    * make MODULE.extract.untouch
 358
 359    * make MODULE.patch.touch
 360
 361    * make MODULE.patch.untouch
 362
 363    * make MODULE.configure.touch
 364
 365    * make MODULE.configure.untouch
 366
 367    * make MODULE.build.touch
 368
 369    * make MODULE.build.untouch
 370
 371    * make MODULE.install.touch
 372
 373    * make MODULE.install.untouch
 374
 375 5.4.5 Contrib Aggregates
 376 ------------------------
 377
 378 For convenience, the following targets aggregate the all contrib
 379 modules' respective targets together:
 380
 381    * make contrib.fetch
 382
 383    * make contrib.extract
 384
 385    * make contrib.patch
 386
 387    * make contrib.configure
 388
 389    * make contrib.build
 390
 391    * make contrib.install
 392
 393    * make contrib.uninstall
 394
 395    * make contrib.clean
 396
 397    * make contrib.xclean
 398
 399 5.5 Customizing Make
 400 ====================
 401
 402 If the need arises to override settings in the build system
 403 (essentially gnu-make variables) the recommended method is to create
 404 optional include files which are automatically included if present and
 405 follow this naming convention; Do not check these files into the
 406 repository:
 407
 408 `_SRC_/custom.defs'
 409      Custom makevar definitions outside `build'. Suitable for settings
 410      which apply across all builds for a particular checkout; or which
 411      survives manual removal of `build'.
 412
 413 `_SRC_/custom.rules'
 414      Custom make rules outside `build'. Suitable for rules which apply
 415      across all builds for a particular checkout; or which survives
 416      manual removal of `build'.
 417
 418 `_BUILD_/GNUmakefile.custom.defs'
 419      Custom makevar definitions specific to a `build' directory.
 420
 421 `_BUILD_/GNUmakefile.custom.rules'
 422      Custom makevar rules specific to a `build' directory.
 423
 424
 425 The purpose is to allow a place to store local build settings for
 426 testing, tweaking, and experimenting with build configuration without
 427 losing your settings if `configure' is invoked; ie: `configure' would
 428 overwrite `GNUmakefile' and any customizations contained therein would
 429 be lost. Here is a short example of what the contents of
 430 `_SRC_/custom.defs' might contain:
 431
 432      ## bump to gcc-4.2 in current path
 433      GCC.gcc = /usr/bin/gcc-4.2
 434
 435      ## replace optimize for 'speed' with more aggressive settings
 436      GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 437
 438 See also `make report.help' which displays a set of reports used to
 439 dump makefile vars.
 440
 441 5.6 Universal Binaries
 442 ======================
 443
 444 This section outlines convenience procedures for creating Universal
 445 Binaries for all the architectures.
 446
 447      Note: The dummy (container) build configuration uses
 448      `--disable-xcode'; but the nested architecture builds will all
 449      make full use of Xcode.
 450
 451 Create a dummy (container) build configuration and use it to launch a
 452 nested-build for each architecture serially; optionally you may
 453 substitute `make ub.build.serial' for `make ub.build.parallel' if your
 454 machine has the horsepower:
 455
 456      ./configure --disable-xcode
 457      cd build/
 458      make ub.build.serial
 459      make ub.combine
 460
 461 To specify a subset of architectures to be built first create/edit
 462 `_SRC_/custom.defs' with the following override to build UB for `i386'
 463 and `x86_64' before invoking `make':
 464
 465      ## prefer i386 (order is important)
 466      UB.archs = i386 x86_64
 467
 468 6 Building via Xcode.app
 469 ************************
 470
 471 6.1 Checkout Sources
 472 ====================
 473
 474 Checkout HandBrake from the official source-code repository.
 475
 476      svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
 477      cd hb-trunk
 478
 479 Sources are checked out from the `trunk' branch. This document was
 480 generated from that very branch, and for example purposes, we will use
 481 exactly the same branch.
 482
 483 If you have write-access to the repository, then you may add the
 484 appropriate login/password information as needed. It is recommended to
 485 use Subversion 1.5.0 or higher. Lower versions should also work.
 486
 487 6.2 Build
 488 =========
 489
 490 Open Xcode.app from a terminal by using the `open' command which passes
 491 your shell environment and its `PATH' setting to Xcode. Do not attempt
 492 to launch Xcode.app from Finder or by using Finder to open
 493 `HandBrake.xcodeproj' - doing so will defeat any custom path settings
 494 which contain required tools.
 495
 496      open `macosx/HandBrake.xcodeproj'
 497
 498 Once the HandBrake Xcode project is open, perform the following steps
 499 to build the default configuration:
 500
 501    * select active configuration standard
 502
 503    * select active target HandBrake
 504
 505    * click Build or Build and Go
 506
 507 When using Build and Go, xcode launches the application under the gdb
 508 debugger.  gdb will encounter a trap when starting the program.  This
 509 trap is harmless and you should just 'continue'.  For the curious, the
 510 trap occurs because we add some values to the environment with setenv,
 511 then do a brain transplant with execv. Restarting the application with
 512 execv triggers the trap.
 513
 514 The first build (on an empty `build' directory) will take a bit of
 515 time. You may use the Build Results window to observe progress. The
 516 most time-consuming part of the build is when the external build system
 517 (essentially the terminal method) is triggered by Xcode and a
 518 substantial amount of log transcript ensues. Much of that transcript
 519 are warnings and errors that are part of the normal build process for
 520 3rd-party contributed modules so in general you need not do anything.
 521 However, if Xcode itself reports the build failed, then you must take
 522 corrective action.
 523
 524 Unfortunately, due to limitations of Xcode we do not have hooks in
 525 place to offer finer-grained control over per-module make actions for
 526 the (external) build system. Thus, you will have to use terminal to
 527 accomplish those tasks. Just `cd' into the build directory which is
 528 associated with your active configuration and perform any necessary
 529 `make' commands. Be careful not to issue commands from the terminal
 530 simultaneously with Xcode tasks as that will confuse both Xcode and
 531 make and likely corrupt your build directory.
 532
 533 When you click clean in Xcode it will not perform an external build
 534 clean. Basically HandBrakeCLI and HandBrake.app are the only products
 535 which have full Xcode iterative development flexibility.
 536
 537 Each configuration uses a different `build' directory. This makes it
 538 possible to build each configuration and switch between them without
 539 losing their respective build state. The description of each
 540 configuration and the name convention for build directories are as
 541 follows:
 542
 543 `standard'
 544      This configuration will build host native architecture. Build
 545      directory is `build.standard' .  The standard variant produces
 546      optimized code without debug information.
 547
 548 `standard.i386'
 549      This configuration will build i386 architecture. Build directory
 550      is `build.standard.i386' .
 551
 552 `standard.x86_64'
 553      This configuration will build x86_64 architecture. Build directory
 554      is `build.standard.x86_64' .
 555
 556 `standard.ppc'
 557      This configuration will build ppc architecture. Build directory is
 558      `build.standard.ppc' .
 559
 560 `standard.ppc64'
 561      This configuration will build ppc64 architecture. Build directory
 562      is `build.standard.ppc64' .
 563
 564 `debug'
 565      This configuration will build host native architecture. Build
 566      directory is `build.debug' .  The debug variant produces
 567      unoptimized code with debug information.
 568
 569 `debug.i386'
 570      This configuration will build i386 architecture. Build directory
 571      is `build.debug.i386' .  The debug variant produces unoptimized
 572      code with debug information.
 573
 574 `debug.x86_64'
 575      This configuration will build x86_64 architecture. Build directory
 576      is `build.debug.x86_64' .  The debug variant produces unoptimized
 577      code with debug information.
 578
 579 `debug.ppc'
 580      This configuration will build ppc architecture. Build directory is
 581      `build.debug.ppc' .  The debug variant produces unoptimized code
 582      with debug information.
 583
 584 `debug.ppc64'
 585      This configuration will build ppc64 architecture. Build directory
 586      is `build.debug.ppc64' .  The debug variant produces unoptimized
 587      code with debug information.
 588
 589 6.3 External Targets
 590 ====================
 591
 592 The following external targets appear in the Xcode project and perform
 593 build and clean actions.
 594
 595 `external'
 596      Target maps to `make build' and `make clean' for everything Xcode
 597      products depend upon from the external build system.
 598
 599 `libhb'
 600      Target maps to `make libhb.build' and `make libhb.clean'.
 601
 602 `contrib'
 603      Target maps to `make contrib.build' and `make contrib.xclean'.
 604
 605
 606 6.4 User-Defined Settings
 607 =========================
 608
 609 The following user defined settings are used in Xcode project for the
 610 external build system:
 611
 612 `EXTERNAL_BUILD'
 613      Specifies the build (scratch) directory for each configuration.
 614
 615 `EXTERNAL_JOBS'
 616      Specifies the concurrency factor for the external build system
 617      when builds are launched from within Xcode.  Modify for faster
 618      external builds if your system has the horsepower and resources.
 619      Specifying a value greater than the number of CPU cores (or
 620      virtual cores) in your system is unlikely to produce gains and
 621      will needlessly consume extra resources.
 622
 623 `EXTERNAL_METHOD'
 624      Do not modify; Used for internal/external build coordination and
 625      must always be `xcode'.
 626
 627 `EXTERNAL_SRC'
 628      Specifies the top-level source directory for HandBrake.
 629
 630
 631 7 Troubleshooting
 632 *****************
 633
 634 When troubleshooting build issues, the following files relative to the
 635 `build/' directory may be especially useful:
 636
 637 `GNUmakefile'
 638      Top-level makefile which contains build settings generated via
 639      configure.
 640
 641 `log/config.info.txt'
 642      Record of output from configure.
 643
 644 `log/config.verbose.txt'
 645      Record of verbose output from configure.
 646
 647 `log/build.txt'
 648      Record of output from `configure --launch'. Similar output may be
 649      recorded using `make' depending on which shell is in use, eg:
 650      `make >& log/build.txt' or `make > log/build.txt 2>&1'.
 651
 652 `log/xcodemake.env.txt'
 653      Environment (variables) dump as seen when Xcode forks `make'.
 654      Mac OS X only.
 655
 656 A note about gdb: We perform an extra execv when starting the
 657 application.  This triggers a trap in gdb.  It is harmless.  You should
 658 just 'continue' from the trap.
 659
 660 Appendix A Project Repository Details
 661 *************************************
 662
 663      url:    svn://svn.handbrake.fr/HandBrake/trunk
 664      root:   svn://svn.handbrake.fr/HandBrake
 665      branch: trunk
 666      uuid:   b64f7644-9d1e-0410-96f1-a4d463321fa5
 667      rev:    3349
 668      date:   2010-06-02 09:49:18 -0700
 669      type:   developer
 670