doc/BUILD-Mac

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