@anchor{xcode}
@chapter Building via Xcode.app

@c %**-------------------------------------------------------------------------
@anchor{xcode.checkout}
@section Checkout Sources
@include building/method.checkout.texi

@c %**-------------------------------------------------------------------------
@anchor{xcode.build}
@section Build
Perform the following steps to build:

@itemize
@item Finder - navigate to @file{macosx/} in the @value{HB.name} source tree
@item Finder - open @file{HandBrake.xcodeproj}
@item Xcode workspace - select scheme @b{HandBrake [RELEASE]}
@item Xcode menu - select Product -> Build
@item Xcode workspace - Show the Log navigator
@item Xcode workspace Log navigator - select top Build item
@end itemize

@c %**-------------------------------------------------------------------------
@anchor{xcode.note.debug}
@section Note: Debugging
When debugging, 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.

@c %**-------------------------------------------------------------------------
@anchor{xcode.note.products}
@section Note: Finding Built Products
Under default Xcode.app options the products from a build are managed by the Xcode Organizer. Perform the following steps to open Finder at top of build tree and navigate to release products:

@itemize
@item Xcode menu - select Window -> Organizer
@item Xcode organizer - select Projects tab
@item Xcode organizer Projects - select @value{HB.name} item
@item @value{HB.name} item - click Derived Data location arrow (immediately right of path)
@item Finder - navigate to Build -> Products -> release
@end itemize

@quotation Note
There is a bug with Xcode Organizer. The very first time an Xcode project is opened the Project view Derived Data is greyed-out. Workaround glitch by selecting any other tab and then reselecting Projects tab.
@end quotation

@c %**-------------------------------------------------------------------------
@anchor{xcode.note.behaviors}
@section Note: Workspace Log Behaviors
The default Workspace behavior does not display latest Build log in the navigator and quickly becomes tedious. To automatically switch to Log navigator and show current log:

@itemize
@item Xcode menu - select Behaviors -> Edit Behaviors
@item Xcode behaviors - select Build starts
@item navigator - enable, select Show, select Log Navigator
@item nagivate to - select current log
@end itemize

@quotation Note
The Log navigator supports some possibly confusing options. It is recommended to only show results for the last build by selecting @b{Recent}. If @b{All} is selected then it will look as though Xcode is performing a build, but in reality it is bringing forward log output from prior builds and it becomes impossible to tell if any single log entry represents actual work performed or if it was brought forward from history.
@end quotation

@quotation Note
When building external target, many 3rd-party contributed modules have warnings and errors which may safely be ignored and are ignored by the external build system. Ultimately, look to the workspace status indicator for @b{Build Succeeded}.
@end quotation

@c %**-------------------------------------------------------------------------
@anchor{xcode.note.external}
@section External Target
The external target mechanism is used to launch a full terminal-based build from within Xcode. Unfortunately, we do not have hooks in place to offer finer-grained control over per-module make actions. However, you can still use @b{terminal} to accomplish those tasks after launching the build at least once or doing a clean from within Xcode. @b{Be careful to not issue terminal commands simultaneously with Xcode tasks.}

Invoking a clean from Xcode always destroys the entire external build tree and subsequently configures it. Changing settings in Xcode such as selecting xcconfig files should always be followed by a clean. This allows the external build system configuration to accurately reflect Xcode project changes.

The following are some examples of using @command{make} from the terminal to effect various components of the external build. But first, you must open a terminal at the top of the external build output tree. Here we navigate to external build configured for @b{release}:

@itemize
@item Xcode menu - select Window -> Organizer
@item Xcode organizer - select Projects tab
@item Xcode organizer Projects - select @value{HB.name} item
@item @value{HB.name} item - click Derived Data location arrow (immediately right of path)
@item Finder - navigate to Build -> Products -> release -> external
@end itemize

Example; external build failed but error is buried in a parallelized log; redo build sequentially:

@example
make xclean
make BUILD.jobs=1
@end example

Example; build external x264 module:

@example
make x264.clean
make x264
@end example

Example; extract, configure, build and install external x264 module:

@example
make x264.xclean
make x264.install
@end example

Example; something in a big module is failing; redo build sequentially:

@example
make ffmpeg.clean
make BUILD.jobs=1 ffmpeg
@end example

@c %**-------------------------------------------------------------------------
@anchor{xcode.userdefined}
@section User-Defined Settings
The following user defined settings are visible in Xcode project and are used
for the external build system.

@table @samp
@item EXTERNAL_BUILD
Do not modify; used to specify the build (scratch) directory.

@item EXTERNAL_DRIVER
Do not modify; used for internal/external build coordination and must always be @samp{xcode}.

@item EXTERNAL_JOBS
Specifies the concurrency factor for the external build system when builds are launched from within Xcode.
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. A special string value of @b{auto} sets the factor to the number of active CPUs on the host system.

@item EXTERNAL_SRC
Do not modify; specifies the top-level source directory for @value{HB.name}, relative to Xcode project.

@item EXTERNAL_XCCONFIG
Do not modify; specifies which xcconfig file is active. Defined inside xcconfig file.

@end table