doc/texi/building/chapter.via.xcode.texi

   1 @anchor{xcode}
   2 @chapter Building via Xcode.app
   3
   4 @c %**-------------------------------------------------------------------------
   5 @anchor{xcode.checkout}
   6 @section Checkout Sources
   7 @include building/method.checkout.texi
   8
   9 @c %**-------------------------------------------------------------------------
  10 @anchor{xcode.build}
  11 @section Build
  12 Open Xcode.app from a terminal by using the @command{open} command which passes your shell environment and its @samp{PATH} setting to Xcode. Do not attempt to launch Xcode.app from Finder or by using Finder to open @file{HandBrake.xcodeproj} -- doing so will defeat any custom path settings which contain required tools.
  13
  14 @example
  15 open @file{macosx/HandBrake.xcodeproj}
  16 @end example
  17
  18 Once the HandBrake Xcode project is open, perform the following steps to build the default configuration:
  19
  20 @itemize
  21 @item select active configuration @b{standard}
  22 @item select active target @b{HandBrake}
  23 @item click @b{Build} or @b{Build and Go}
  24 @end itemize
  25
  26 When using Build and Go, xcode launches the application under the gdb debugger.  gdb will encounter a trap when starting the program.  This trap is harmless and you should just 'continue'.  For the curious, the trap occurs because we add some values to the environment with setenv, then do a brain transplant with execv. Restarting the application with execv triggers the trap.
  27
  28 The first build (on an empty @file{build} directory) will take a bit of time. You may use the Build Results window to observe progress. The most time-consuming part of the build is when the external build system (essentially the @b{terminal} method) is triggered by Xcode and a substantial amount of log transcript ensues. Much of that transcript are warnings and errors that are part of the normal build process for 3rd-party contributed modules so in general you need not do anything. However, if Xcode itself reports the build failed, then you must take corrective action.
  29
  30 Unfortunately, due to limitations of Xcode we do not have hooks in place to offer finer-grained control over per-module make actions for the (external) build system. Thus, you will have to use @b{terminal} to accomplish those tasks. Just @command{cd} into the build directory which is associated with your active configuration and perform any necessary @command{make} commands. @b{Be careful not to issue commands from the terminal simultaneously with Xcode tasks} as that will confuse both Xcode and make and likely corrupt your build directory.
  31
  32 When you click @b{clean} in Xcode it will not perform an external build clean. Basically @b{HandBrakeCLI} and @b{HandBrake.app} are the only products which have full Xcode iterative development flexibility.
  33
  34 Each configuration uses a different @file{build} directory. This makes it possible to build each configuration and switch between them without losing their respective build state. The description of each configuration and the name convention for build directories are as follows:
  35
  36 @table @samp
  37 @item standard
  38 This configuration will build @b{host native} architecture. Build directory is @file{build.standard} .
  39 The standard variant produces optimized code without debug information.
  40
  41 @item standard.i386
  42 This configuration will build @b{i386} architecture. Build directory is @file{build.standard.i386} .
  43
  44 @item standard.x86_64
  45 This configuration will build @b{x86_64} architecture. Build directory is @file{build.standard.x86_64} .
  46
  47 @item standard.ppc
  48 This configuration will build @b{ppc} architecture. Build directory is @file{build.standard.ppc} .
  49
  50 @item standard.ppc64
  51 This configuration will build @b{ppc64} architecture. Build directory is @file{build.standard.ppc64} .
  52
  53 @item debug
  54 This configuration will build @b{host native architecture}. Build directory is @file{build.debug} .
  55 The debug variant produces unoptimized code with debug information.
  56
  57 @item debug.i386
  58 This configuration will build @b{i386} architecture. Build directory is @file{build.debug.i386} .
  59 The debug variant produces unoptimized code with debug information.
  60
  61 @item debug.x86_64
  62 This configuration will build @b{x86_64} architecture. Build directory is @file{build.debug.x86_64} .
  63 The debug variant produces unoptimized code with debug information.
  64
  65 @item debug.ppc
  66 This configuration will build @b{ppc} architecture. Build directory is @file{build.debug.ppc} .
  67 The debug variant produces unoptimized code with debug information.
  68
  69 @item debug.ppc64
  70 This configuration will build @b{ppc64} architecture. Build directory is @file{build.debug.ppc64} .
  71 The debug variant produces unoptimized code with debug information.
  72 @end table
  73
  74 @c %**-------------------------------------------------------------------------
  75 @anchor{xcode.extenal}
  76 @section External Targets
  77 The following external targets appear in the Xcode project and perform @b{build} and @b{clean} actions.
  78
  79 @table @samp
  80 @item external
  81 Target maps to @command{make build} and @command{make clean} for everything Xcode products depend upon from the external build system.
  82
  83 @item libhb
  84 Target maps to @command{make libhb.build} and @command{make libhb.clean}.
  85
  86 @item contrib
  87 Target maps to @command{make contrib.build} and @command{make contrib.xclean}.
  88
  89 @end table
  90
  91 @c %**-------------------------------------------------------------------------
  92 @anchor{xcode.userdefined}
  93 @section User-Defined Settings
  94 The following user defined settings are used in Xcode project for the external build system:
  95
  96 @table @samp
  97 @item EXTERNAL_BUILD
  98 Specifies the build (scratch) directory for each configuration.
  99
 100 @item EXTERNAL_JOBS
 101 Specifies the concurrency factor for the external build system when builds are launched from within Xcode.
 102 Modify for faster external builds if your system has the horsepower and resources. Specifying a value greater than the number of CPU cores (or virtual cores) in your system is unlikely to produce gains and will needlessly consume extra resources.
 103
 104 @item EXTERNAL_METHOD
 105 Do not modify; Used for internal/external build coordination and must always be @samp{xcode}.
 106
 107 @item EXTERNAL_SRC
 108 Specifies the top-level source directory for @value{HB.name}.
 109
 110 @end table