diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/BUILD-Cygwin | 66 | ||||
| -rw-r--r-- | doc/BUILD-Linux | 64 | ||||
| -rw-r--r-- | doc/BUILD-Mac | 361 | ||||
| -rw-r--r-- | doc/texi/Building.osx.texi | 20 | ||||
| -rw-r--r-- | doc/texi/building/chapter.via.terminal.texi | 17 | ||||
| -rw-r--r-- | doc/texi/building/chapter.via.xcode.texi | 147 | ||||
| -rw-r--r-- | doc/texi/building/method.checkout.texi | 2 | ||||
| -rw-r--r-- | doc/texi/building/prerequisites.bundled.texi | 2 | ||||
| -rw-r--r-- | doc/texi/building/prerequisites.common.texi | 10 |
9 files changed, 389 insertions, 300 deletions
diff --git a/doc/BUILD-Cygwin b/doc/BUILD-Cygwin index 7f03ca824..eadb7e346 100644 --- a/doc/BUILD-Cygwin +++ b/doc/BUILD-Cygwin @@ -1,4 +1,4 @@ -Guide to Building HandBrake svn2591 (2009062101) on Cygwin +Guide to Building HandBrake svn4394 (2012010401) on Cygwin ********************************************************** Table of Contents @@ -43,12 +43,13 @@ Cygwin; but is not necessarily the only configuration that is possible: * yasm 0.7.2.2153 (for i386 or x86_64 architectures) - Note: It is recommended to use the platform distribution's bundled - compiler for maximum C++ compatibility. If you build with a custom - compiler it will likely introduce non-standard runtime - requirements. There are of course many valid reasons to build with - unbundled compilers, but be aware it is generally unsupported and - left as an exercise to the reader. + Note: It is recommended to use the platform distribution's + standard compiler for maximum C++ compatibility. If you build with + a custom compiler it will likely introduce non-standard runtime + requirements and have new/delete, exception and RTTI + incompatibilities. There are of course many valid reasons to build + with unbundled compilers, but be aware it is generally unsupported + and left as an exercise to the reader. Note: As of this writing, Cygwin has available to it several versions of gcc; only one of which may be found and used in the @@ -64,11 +65,11 @@ Cygwin; but is not necessarily the only configuration that is possible: The following general tools are used on various platforms and it is recommended you use these versions or similar: - * subversion - 1.6.2 + * subversion - 1.6.16 - * python - Python 2.4.6 + * python - Python 2.7.1 - * curl - curl 7.19.4 (or wget) + * curl - curl 7.21.4 (or wget) * m4 - GNU M4 1.4.6 @@ -76,9 +77,9 @@ recommended you use these versions or similar: * patch - Patch 2.5.8 - * tar - GNU tar 1.15.1 + * tar - GNU tar 1.26 - * wget - GNU Wget 1.11.4 (or curl) + * wget - GNU Wget 1.13.4 (or curl) 3 QuickStart ************ @@ -86,7 +87,7 @@ recommended you use these versions or similar: This chapter is for building from a terminal/shell environment in as few commands as possible. Upon completion of the following commands you should have a fresh build of HandBrake. Further instructions are -available beginning with *Note overview:: which describes procedures +available beginning with *note overview:: which describes procedures suitable for repeating builds. This chapter should be skipped by those seeking more than a minimalist build. @@ -136,7 +137,7 @@ exactly the same branch. If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to -use Subversion 1.5.0 or higher. Lower versions should also work. +use Subversion 1.6.0 or higher. Lower versions should also work. 5.2 Configure ============= @@ -175,12 +176,6 @@ options are also documented here: All-in-one option which launches the build and logs output automatically. Useful for novices and quick-start procedures. -`--disable-xcode' - Disable shunting the build through `xcodebuild'. If this option is - applied, `HandBrakeCLI' will be produced in a similar fashion as - it is on other platforms; sans Xcode and the Cocoa application - will not be produced. Mac OS X only. - `--disable-gtk' Disable building the GTK GUI on applicable platforms such as Linux. @@ -200,6 +195,17 @@ options are also documented here: architectures. The available choices are hard-coded per platform and no sanity checks for the required tools are performed. +`--disable-xcode' + Disable shunting the build through `xcodebuild'. If this option is + applied, `HandBrakeCLI' will be produced in a similar fashion as + it is on other platforms; sans Xcode and the Cocoa application + will not be produced. Mac OS X only. + +`--xcconfig=MODE' + Select Xcode project configuration file. The available modes are + the basenames of files located in `macosx/xcconfig/*.xcconfig' + which direct Xcode to build using various architecture and Mac OS + X deployment options. Mac OS X only. Clean-room procedures dictate that when certain factors change, old builds should be scrapped and new builds configured. This is the main @@ -278,6 +284,10 @@ period. Build auto-generated project documentation. Various articles are produced and may be found in `build/doc/articles'. +`make doc.post' + Build auto-generated project documentation and post produced + articles directly to source tree. + `make report.help' Print list of available makefile vars report targets. These reports detail var definitions and expanded values used by the @@ -302,9 +312,11 @@ scoped targets: --------------------- Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg', -`lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate', -`libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have -the following scoped targets: +`fontconfig', `freetype', `fribidi', `lame', `libass', `libbluray', +`libdca', `libdvdnav', `libdvdread', `libdvdread', `libiconv', +`libmkv', `libogg', `libsamplerate', `libtheora', `libvorbis', +`libxml2', `mp4v2', `mpeg2dec', `x264', `yasm' and `zlib' have the +following scoped targets: `make MODULE.fetch' Download source tarball from the Internet and save to @@ -424,8 +436,8 @@ overwrite `GNUmakefile' and any customizations contained therein would be lost. Here is a short example of what the contents of `_SRC_/custom.defs' might contain: - ## bump to gcc-4.2 in current path - GCC.gcc = /usr/bin/gcc-4.2 + ## bump to gcc-4.6 in current path + GCC.gcc = /usr/bin/gcc-4.6 ## replace optimize for 'speed' with more aggressive settings GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2 @@ -465,7 +477,7 @@ Appendix A Project Repository Details root: svn://svn.handbrake.fr/HandBrake branch: trunk uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5 - rev: 2591 - date: 2009-06-21 13:15:04 -0400 + rev: 4394 + date: 2011-12-30 17:21:44 -0500 type: developer diff --git a/doc/BUILD-Linux b/doc/BUILD-Linux index e69baac3d..8d5deb9fd 100644 --- a/doc/BUILD-Linux +++ b/doc/BUILD-Linux @@ -1,4 +1,4 @@ -Guide to Building HandBrake svn4306 (2011102201) on Linux +Guide to Building HandBrake svn4394 (2012010401) on Linux ********************************************************* Table of Contents @@ -44,21 +44,22 @@ Linux; but is not necessarily the only configuration that is possible: * gcc 4.0.0 or higher is reported to work - Note: It is recommended to use the platform distribution's bundled - compiler for maximum C++ compatibility. If you build with a custom - compiler it will likely introduce non-standard runtime - requirements. There are of course many valid reasons to build with - unbundled compilers, but be aware it is generally unsupported and - left as an exercise to the reader. + Note: It is recommended to use the platform distribution's + standard compiler for maximum C++ compatibility. If you build with + a custom compiler it will likely introduce non-standard runtime + requirements and have new/delete, exception and RTTI + incompatibilities. There are of course many valid reasons to build + with unbundled compilers, but be aware it is generally unsupported + and left as an exercise to the reader. The following general tools are used on various platforms and it is recommended you use these versions or similar: - * subversion - 1.6.2 + * subversion - 1.6.16 - * python - Python 2.4.6 + * python - Python 2.7.1 - * curl - curl 7.19.4 (or wget) + * curl - curl 7.21.4 (or wget) * m4 - GNU M4 1.4.6 @@ -66,9 +67,9 @@ recommended you use these versions or similar: * patch - Patch 2.5.8 - * tar - GNU tar 1.15.1 + * tar - GNU tar 1.26 - * wget - GNU Wget 1.11.4 (or curl) + * wget - GNU Wget 1.13.4 (or curl) The GTK UI introduces some significant extra build requirements. If you intend to disable building the GUI with `configure --disable-gtk' you @@ -214,7 +215,7 @@ exactly the same branch. If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to -use Subversion 1.5.0 or higher. Lower versions should also work. +use Subversion 1.6.0 or higher. Lower versions should also work. 5.2 Configure ============= @@ -253,12 +254,6 @@ options are also documented here: All-in-one option which launches the build and logs output automatically. Useful for novices and quick-start procedures. -`--disable-xcode' - Disable shunting the build through `xcodebuild'. If this option is - applied, `HandBrakeCLI' will be produced in a similar fashion as - it is on other platforms; sans Xcode and the Cocoa application - will not be produced. Mac OS X only. - `--disable-gtk' Disable building the GTK GUI on applicable platforms such as Linux. @@ -278,6 +273,17 @@ options are also documented here: architectures. The available choices are hard-coded per platform and no sanity checks for the required tools are performed. +`--disable-xcode' + Disable shunting the build through `xcodebuild'. If this option is + applied, `HandBrakeCLI' will be produced in a similar fashion as + it is on other platforms; sans Xcode and the Cocoa application + will not be produced. Mac OS X only. + +`--xcconfig=MODE' + Select Xcode project configuration file. The available modes are + the basenames of files located in `macosx/xcconfig/*.xcconfig' + which direct Xcode to build using various architecture and Mac OS + X deployment options. Mac OS X only. Clean-room procedures dictate that when certain factors change, old builds should be scrapped and new builds configured. This is the main @@ -356,6 +362,10 @@ period. Build auto-generated project documentation. Various articles are produced and may be found in `build/doc/articles'. +`make doc.post' + Build auto-generated project documentation and post produced + articles directly to source tree. + `make report.help' Print list of available makefile vars report targets. These reports detail var definitions and expanded values used by the @@ -380,9 +390,11 @@ scoped targets: --------------------- Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg', -`lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate', -`libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have -the following scoped targets: +`fontconfig', `freetype', `fribidi', `lame', `libass', `libbluray', +`libdca', `libdvdnav', `libdvdread', `libdvdread', `libiconv', +`libmkv', `libogg', `libsamplerate', `libtheora', `libvorbis', +`libxml2', `mp4v2', `mpeg2dec', `x264', `yasm' and `zlib' have the +following scoped targets: `make MODULE.fetch' Download source tarball from the Internet and save to @@ -502,8 +514,8 @@ overwrite `GNUmakefile' and any customizations contained therein would be lost. Here is a short example of what the contents of `_SRC_/custom.defs' might contain: - ## bump to gcc-4.2 in current path - GCC.gcc = /usr/bin/gcc-4.2 + ## bump to gcc-4.6 in current path + GCC.gcc = /usr/bin/gcc-4.6 ## replace optimize for 'speed' with more aggressive settings GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2 @@ -543,7 +555,7 @@ Appendix A Project Repository Details root: svn://svn.handbrake.fr/HandBrake branch: trunk uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5 - rev: 4306 - date: 2011-10-22 09:38:47 -0700 + rev: 4394 + date: 2011-12-30 17:21:44 -0500 type: developer diff --git a/doc/BUILD-Mac b/doc/BUILD-Mac index 5416aae23..07f56df84 100644 --- a/doc/BUILD-Mac +++ b/doc/BUILD-Mac @@ -1,4 +1,4 @@ -Build Guide for HandBrake svn3349 on Mac OS X +Build Guide for HandBrake 4394svn on Mac OS X ********************************************* Table of Contents @@ -23,8 +23,11 @@ Table of Contents 6 Building via Xcode.app 6.1 Checkout Sources 6.2 Build - 6.3 External Targets - 6.4 User-Defined Settings + 6.3 Note: Debugging + 6.4 Note: Finding Built Products + 6.5 Note: Workspace Log Behaviors + 6.6 External Target + 6.7 User-Defined Settings 7 Troubleshooting Appendix A Project Repository Details @@ -46,29 +49,30 @@ possible: * Mac Intel hardware - * Mac OS X 10.5.7 + * Mac OS X 10.7.2 - * Xcode-3.1.2 + * Xcode 4.2.1 (Build version 4D502) - * gcc 4.0.1 (Apple Inc. build 5490) + * llvm-gcc-4.2 (GCC) 4.2.1 (Based on Apple Inc. build 5658) - * yasm 0.8.0.2194 (for i386 and x86_64 architectures) + * yasm 1.1.0.2352 - Note: It is recommended to use the platform distribution's bundled - compiler for maximum C++ compatibility. If you build with a custom - compiler it will likely introduce non-standard runtime - requirements. There are of course many valid reasons to build with - unbundled compilers, but be aware it is generally unsupported and - left as an exercise to the reader. + Note: It is recommended to use the platform distribution's + standard compiler for maximum C++ compatibility. If you build with + a custom compiler it will likely introduce non-standard runtime + requirements and have new/delete, exception and RTTI + incompatibilities. There are of course many valid reasons to build + with unbundled compilers, but be aware it is generally unsupported + and left as an exercise to the reader. The following general tools are used on various platforms and it is recommended you use these versions or similar: - * subversion - 1.6.2 + * subversion - 1.6.16 - * python - Python 2.4.6 + * python - Python 2.7.1 - * curl - curl 7.19.4 (or wget) + * curl - curl 7.21.4 (or wget) * m4 - GNU M4 1.4.6 @@ -76,9 +80,9 @@ recommended you use these versions or similar: * patch - Patch 2.5.8 - * tar - GNU tar 1.15.1 + * tar - GNU tar 1.26 - * wget - GNU Wget 1.11.4 (or curl) + * wget - GNU Wget 1.13.4 (or curl) 3 QuickStart ************ @@ -86,7 +90,7 @@ recommended you use these versions or similar: This chapter is for building from a terminal/shell environment in as few commands as possible. Upon completion of the following commands you should have a fresh build of HandBrake. Further instructions are -available beginning with *Note overview:: which describes procedures +available beginning with *note overview:: which describes procedures suitable for repeating builds. This chapter should be skipped by those seeking more than a minimalist build. @@ -141,7 +145,7 @@ exactly the same branch. If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to -use Subversion 1.5.0 or higher. Lower versions should also work. +use Subversion 1.6.0 or higher. Lower versions should also work. 5.2 Configure ============= @@ -180,12 +184,6 @@ options are also documented here: All-in-one option which launches the build and logs output automatically. Useful for novices and quick-start procedures. -`--disable-xcode' - Disable shunting the build through `xcodebuild'. If this option is - applied, `HandBrakeCLI' will be produced in a similar fashion as - it is on other platforms; sans Xcode and the Cocoa application - will not be produced. Mac OS X only. - `--disable-gtk' Disable building the GTK GUI on applicable platforms such as Linux. @@ -205,6 +203,17 @@ options are also documented here: architectures. The available choices are hard-coded per platform and no sanity checks for the required tools are performed. +`--disable-xcode' + Disable shunting the build through `xcodebuild'. If this option is + applied, `HandBrakeCLI' will be produced in a similar fashion as + it is on other platforms; sans Xcode and the Cocoa application + will not be produced. Mac OS X only. + +`--xcconfig=MODE' + Select Xcode project configuration file. The available modes are + the basenames of files located in `macosx/xcconfig/*.xcconfig' + which direct Xcode to build using various architecture and Mac OS + X deployment options. Mac OS X only. Clean-room procedures dictate that when certain factors change, old builds should be scrapped and new builds configured. This is the main @@ -283,6 +292,10 @@ period. Build auto-generated project documentation. Various articles are produced and may be found in `build/doc/articles'. +`make doc.post' + Build auto-generated project documentation and post produced + articles directly to source tree. + `make report.help' Print list of available makefile vars report targets. These reports detail var definitions and expanded values used by the @@ -307,9 +320,11 @@ scoped targets: --------------------- Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg', -`lame', `libdca', `libdvdread', `libmkv', `libogg', `libsamplerate', -`libtheora', `libvorbis', `mp4v2', `mpeg2dec', `x264' and `zlib' have -the following scoped targets: +`fontconfig', `freetype', `fribidi', `lame', `libass', `libbluray', +`libdca', `libdvdnav', `libdvdread', `libdvdread', `libiconv', +`libmkv', `libogg', `libsamplerate', `libtheora', `libvorbis', +`libxml2', `mp4v2', `mpeg2dec', `x264', `yasm' and `zlib' have the +following scoped targets: `make MODULE.fetch' Download source tarball from the Internet and save to @@ -429,8 +444,8 @@ overwrite `GNUmakefile' and any customizations contained therein would be lost. Here is a short example of what the contents of `_SRC_/custom.defs' might contain: - ## bump to gcc-4.2 in current path - GCC.gcc = /usr/bin/gcc-4.2 + ## bump to gcc-4.6 in current path + GCC.gcc = /usr/bin/gcc-4.6 ## replace optimize for 'speed' with more aggressive settings GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2 @@ -449,21 +464,22 @@ Binaries for all the architectures. make full use of Xcode. Create a dummy (container) build configuration and use it to launch a -nested-build for each architecture serially; optionally you may -substitute `make ub.build.serial' for `make ub.build.parallel' if your -machine has the horsepower: +nested-build for each architecture: ./configure --disable-xcode cd build/ - make ub.build.serial + make ub.build make ub.combine -To specify a subset of architectures to be built first create/edit -`_SRC_/custom.defs' with the following override to build UB for `i386' -and `x86_64' before invoking `make': +The list of architectures is hard coded to HandBrake's desired product +and currently is composed of combining the binaries produced from two +xcconfigs: osx106.i386 and osx106.x86_64. The following example shows +how to specify a different list of xcconfigs: - ## prefer i386 (order is important) - UB.archs = i386 x86_64 + ./configure --disable-xcode + cd build/ + make UB.xcconfigs="osx107.i386 osx107.x86_64" ub.build + make UB.xcconfigs="osx107.i386 osx107.x86_64" ub.combine 6 Building via Xcode.app ************************ @@ -482,135 +498,151 @@ exactly the same branch. If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to -use Subversion 1.5.0 or higher. Lower versions should also work. +use Subversion 1.6.0 or higher. Lower versions should also work. 6.2 Build ========= -Open Xcode.app from a terminal by using the `open' command which passes -your shell environment and its `PATH' setting to Xcode. Do not attempt -to launch Xcode.app from Finder or by using Finder to open -`HandBrake.xcodeproj' - doing so will defeat any custom path settings -which contain required tools. - - open `macosx/HandBrake.xcodeproj' - -Once the HandBrake Xcode project is open, perform the following steps -to build the default configuration: - - * select active configuration standard - - * select active target HandBrake - - * click Build or Build and Go - -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. - -The first build (on an empty `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 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. - -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 terminal to -accomplish those tasks. Just `cd' into the build directory which is -associated with your active configuration and perform any necessary -`make' commands. 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. - -When you click clean in Xcode it will not perform an external build -clean. Basically HandBrakeCLI and HandBrake.app are the only products -which have full Xcode iterative development flexibility. - -Each configuration uses a different `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: - -`standard' - This configuration will build host native architecture. Build - directory is `build.standard' . The standard variant produces - optimized code without debug information. - -`standard.i386' - This configuration will build i386 architecture. Build directory - is `build.standard.i386' . - -`standard.x86_64' - This configuration will build x86_64 architecture. Build directory - is `build.standard.x86_64' . - -`standard.ppc' - This configuration will build ppc architecture. Build directory is - `build.standard.ppc' . - -`standard.ppc64' - This configuration will build ppc64 architecture. Build directory - is `build.standard.ppc64' . - -`debug' - This configuration will build host native architecture. Build - directory is `build.debug' . The debug variant produces - unoptimized code with debug information. - -`debug.i386' - This configuration will build i386 architecture. Build directory - is `build.debug.i386' . The debug variant produces unoptimized - code with debug information. - -`debug.x86_64' - This configuration will build x86_64 architecture. Build directory - is `build.debug.x86_64' . The debug variant produces unoptimized - code with debug information. - -`debug.ppc' - This configuration will build ppc architecture. Build directory is - `build.debug.ppc' . The debug variant produces unoptimized code - with debug information. - -`debug.ppc64' - This configuration will build ppc64 architecture. Build directory - is `build.debug.ppc64' . The debug variant produces unoptimized - code with debug information. - -6.3 External Targets -==================== +Perform the following steps to build: + + * Finder - navigate to `macosx/' in the HandBrake source tree + + * Finder - open `HandBrake.xcodeproj' + + * Xcode workspace - select scheme HandBrake [RELEASE] + + * Xcode menu - select Product -> Build + + * Xcode workspace - Show the Log navigator + + * Xcode workspace Log navigator - select top Build item + +6.3 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. + +6.4 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: + + * Xcode menu - select Window -> Organizer + + * Xcode organizer - select Projects tab + + * Xcode organizer Projects - select HandBrake item -The following external targets appear in the Xcode project and perform -build and clean actions. + * HandBrake item - click Derived Data location arrow (immediately + right of path) -`external' - Target maps to `make build' and `make clean' for everything Xcode - products depend upon from the external build system. + * Finder - navigate to Build -> Products -> release -`libhb' - Target maps to `make libhb.build' and `make libhb.clean'. + 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. -`contrib' - Target maps to `make contrib.build' and `make contrib.xclean'. +6.5 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: -6.4 User-Defined Settings + * Xcode menu - select Behaviors -> Edit Behaviors + + * Xcode behaviors - select Build starts + + * navigator - enable, select Show, select Log Navigator + + * nagivate to - select current log + + Note: The Log navigator supports some possibly confusing options. + It is recommended to only show results for the last build by + selecting Recent. If 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. + + 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 Build Succeeded. + +6.6 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 terminal to accomplish those tasks after launching +the build at least once or doing a clean from within Xcode. 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 `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 release: + + * Xcode menu - select Window -> Organizer + + * Xcode organizer - select Projects tab + + * Xcode organizer Projects - select HandBrake item + + * HandBrake item - click Derived Data location arrow (immediately + right of path) + + * Finder - navigate to Build -> Products -> release -> external + +Example; external build failed but error is buried in a parallelized +log; redo build sequentially: + + make xclean + make BUILD.jobs=1 + +Example; build external x264 module: + + make x264.clean + make x264 + +Example; extract, configure, build and install external x264 module: + + make x264.xclean + make x264.install + +Example; something in a big module is failing; redo build sequentially: + + make ffmpeg.clean + make BUILD.jobs=1 ffmpeg + +6.7 User-Defined Settings ========================= -The following user defined settings are used in Xcode project for the -external build system: +The following user defined settings are visible in Xcode project and +are used for the external build system. `EXTERNAL_BUILD' - Specifies the build (scratch) directory for each configuration. + Do not modify; used to specify the build (scratch) directory. + +`EXTERNAL_DRIVER' + Do not modify; used for internal/external build coordination and + must always be `xcode'. `EXTERNAL_JOBS' Specifies the concurrency factor for the external build system @@ -618,14 +650,17 @@ external build system: 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. - -`EXTERNAL_METHOD' - Do not modify; Used for internal/external build coordination and - must always be `xcode'. + will needlessly consume extra resources. A special string value of + auto sets the factor to the number of active CPUs on the host + system. `EXTERNAL_SRC' - Specifies the top-level source directory for HandBrake. + Do not modify; specifies the top-level source directory for + HandBrake, relative to Xcode project. + +`EXTERNAL_XCCONFIG' + Do not modify; specifies which xcconfig file is active. Defined + inside xcconfig file. 7 Troubleshooting @@ -664,7 +699,7 @@ Appendix A Project Repository Details root: svn://svn.handbrake.fr/HandBrake branch: trunk uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5 - rev: 3349 - date: 2010-06-02 09:49:18 -0700 + rev: 4394 + date: 2011-12-30 17:21:44 -0500 type: developer diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi index 6afa9b543..5c661c5eb 100644 --- a/doc/texi/Building.osx.texi +++ b/doc/texi/Building.osx.texi @@ -20,10 +20,10 @@ Building on @value{OS.osx} is well supported. It is the reference platform for @ @itemize @bullet @item Mac Intel hardware -@item @value{OS.osx} 10.5.7 -@item Xcode-3.1.2 -@item gcc 4.0.1 (Apple Inc. build 5490) -@item yasm 0.8.0.2194 (for i386 and x86_64 architectures) +@item @value{OS.osx} 10.7.2 +@item Xcode 4.2.1 (Build version 4D502) +@item llvm-gcc-4.2 (GCC) 4.2.1 (Based on Apple Inc. build 5658) +@item yasm 1.1.0.2352 @end itemize @include building/prerequisites.bundled.texi @@ -49,20 +49,22 @@ This section outlines convenience procedures for creating Universal Binaries for The dummy (container) build configuration uses @command{--disable-xcode}; but the nested architecture builds will all make full use of Xcode. @end quotation -Create a dummy (container) build configuration and use it to launch a nested-build for each architecture @i{serially}; optionally you may substitute @command{make ub.build.serial} for @command{make ub.build.parallel} if your machine has the horsepower: +Create a dummy (container) build configuration and use it to launch a nested-build for each architecture: @example ./configure --disable-xcode cd build/ -make ub.build.serial +make ub.build make ub.combine @end example -To specify a subset of architectures to be built first create/edit @file{_SRC_/custom.defs} with the following override to build UB for @samp{i386} and @samp{x86_64} before invoking @command{make}: +The list of architectures is hard coded to @value{HB.name}'s desired product and currently is composed of combining the binaries produced from two xcconfigs: osx106.i386 and osx106.x86_64. The following example shows how to specify a different list of xcconfigs: @example -## prefer i386 (order is important) -UB.archs = i386 x86_64 +./configure --disable-xcode +cd build/ +make UB.xcconfigs="osx107.i386 osx107.x86_64" ub.build +make UB.xcconfigs="osx107.i386 osx107.x86_64" ub.combine @end example @c %**------------------------------------------------------------------------- diff --git a/doc/texi/building/chapter.via.terminal.texi b/doc/texi/building/chapter.via.terminal.texi index 69f1424db..bdd665e23 100644 --- a/doc/texi/building/chapter.via.terminal.texi +++ b/doc/texi/building/chapter.via.terminal.texi @@ -37,9 +37,6 @@ This defaults to a reasonable platform-specific value. All-in-one option which launches the build and logs output automatically. Useful for novices and quick-start procedures. -@item --disable-xcode -Disable shunting the build through @command{xcodebuild}. If this option is applied, @command{HandBrakeCLI} will be produced in a similar fashion as it is on other platforms; sans Xcode and the Cocoa application will not be produced. @value{OS.osx} only. - @item --disable-gtk Disable building the GTK GUI on applicable platforms such as @value{OS.linux}. @@ -54,6 +51,11 @@ This generally maps to gcc options @samp{-g0}, @samp{-O0}, @samp{-O3}, @samp{-Os @item --arch=MODE Select build architecture. The available architectures vary by platform. Most platforms support exactly one architecture except @value{OS.osx} which has support for various universal binary architectures. The available choices are hard-coded per platform and no sanity checks for the required tools are performed. +@item --disable-xcode +Disable shunting the build through @command{xcodebuild}. If this option is applied, @command{HandBrakeCLI} will be produced in a similar fashion as it is on other platforms; sans Xcode and the Cocoa application will not be produced. @value{OS.osx} only. + +@item --xcconfig=MODE +Select Xcode project configuration file. The available modes are the basenames of files located in @file{macosx/xcconfig/*.xcconfig} which direct Xcode to build using various architecture and @value{OS.osx} deployment options. @value{OS.osx} only. @end table Clean-room procedures dictate that when certain factors change, old builds should be scrapped and new builds configured. This is the main reason for requiring a scratch directory; to promote consistent, reliable and clean software builds. The following is a short list of some of the reasons why someone may choose to scrap an existing build: @@ -114,6 +116,9 @@ Clean all build output including contrib modules. Configuration is retained. @item make doc Build auto-generated project documentation. Various articles are produced and may be found in @file{build/doc/articles}. +@item make doc.post +Build auto-generated project documentation and post produced articles directly to source tree. + @item make report.help Print list of available makefile vars report targets. These reports detail var definitions and expanded values used by the build system. @@ -140,7 +145,7 @@ Clean build output for @i{MODULE}. @anchor{terminal.targets.contrib} @subsection Contrib Modules -Contrib modules such as @samp{a52dec}, @samp{bzip2}, @samp{faac}, @samp{faad2}, @samp{ffmpeg}, @samp{lame}, @samp{libdca}, @samp{libdvdread}, @samp{libmkv}, @samp{libogg}, @samp{libsamplerate}, @samp{libtheora}, @samp{libvorbis}, @samp{mp4v2}, @samp{mpeg2dec}, @samp{x264} and @samp{zlib} have the following scoped targets: +Contrib modules such as @samp{a52dec}, @samp{bzip2}, @samp{faac}, @samp{faad2}, @samp{ffmpeg}, @samp{fontconfig}, @samp{freetype}, @samp{fribidi}, @samp{lame}, @samp{libass}, @samp{libbluray}, @samp{libdca}, @samp{libdvdnav}, @samp{libdvdread}, @samp{libdvdread}, @samp{libiconv}, @samp{libmkv}, @samp{libogg}, @samp{libsamplerate}, @samp{libtheora}, @samp{libvorbis}, @samp{libxml2}, @samp{mp4v2}, @samp{mpeg2dec}, @samp{x264}, @samp{yasm} and @samp{zlib} have the following scoped targets: @table @samp @item make @i{MODULE}.fetch @@ -232,8 +237,8 @@ Custom makevar rules specific to a @file{build} directory. The purpose is to allow a place to store local build settings for testing, tweaking, and experimenting with build configuration without losing your settings if @command{configure} is invoked; ie: @command{configure} would overwrite @file{GNUmakefile} and any customizations contained therein would be lost. Here is a short example of what the contents of @file{_SRC_/custom.defs} might contain: @example -## bump to gcc-4.2 in current path -GCC.gcc = /usr/bin/gcc-4.2 +## bump to gcc-4.6 in current path +GCC.gcc = /usr/bin/gcc-4.6 ## replace optimize for 'speed' with more aggressive settings GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2 diff --git a/doc/texi/building/chapter.via.xcode.texi b/doc/texi/building/chapter.via.xcode.texi index 0b0c2b435..83d1e9362 100644 --- a/doc/texi/building/chapter.via.xcode.texi +++ b/doc/texi/building/chapter.via.xcode.texi @@ -9,102 +9,125 @@ @c %**------------------------------------------------------------------------- @anchor{xcode.build} @section Build -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. - -@example -open @file{macosx/HandBrake.xcodeproj} -@end example - -Once the HandBrake Xcode project is open, perform the following steps to build the default configuration: +Perform the following steps to build: @itemize -@item select active configuration @b{standard} -@item select active target @b{HandBrake} -@item click @b{Build} or @b{Build and Go} +@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 -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. +@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. -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. +@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: -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. +@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 -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. +@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 -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: +@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: -@table @samp -@item standard -This configuration will build @b{host native} architecture. Build directory is @file{build.standard} . -The standard variant produces optimized code without debug information. +@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 -@item standard.i386 -This configuration will build @b{i386} architecture. Build directory is @file{build.standard.i386} . +@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 -@item standard.x86_64 -This configuration will build @b{x86_64} architecture. Build directory is @file{build.standard.x86_64} . +@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 -@item standard.ppc -This configuration will build @b{ppc} architecture. Build directory is @file{build.standard.ppc} . +@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.} -@item standard.ppc64 -This configuration will build @b{ppc64} architecture. Build directory is @file{build.standard.ppc64} . +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. -@item debug -This configuration will build @b{host native architecture}. Build directory is @file{build.debug} . -The debug variant produces unoptimized code with debug information. +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}: -@item debug.i386 -This configuration will build @b{i386} architecture. Build directory is @file{build.debug.i386} . -The debug variant produces unoptimized code with debug information. +@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 -@item debug.x86_64 -This configuration will build @b{x86_64} architecture. Build directory is @file{build.debug.x86_64} . -The debug variant produces unoptimized code with debug information. +Example; external build failed but error is buried in a parallelized log; redo build sequentially: -@item debug.ppc -This configuration will build @b{ppc} architecture. Build directory is @file{build.debug.ppc} . -The debug variant produces unoptimized code with debug information. +@example +make xclean +make BUILD.jobs=1 +@end example -@item debug.ppc64 -This configuration will build @b{ppc64} architecture. Build directory is @file{build.debug.ppc64} . -The debug variant produces unoptimized code with debug information. -@end table +Example; build external x264 module: -@c %**------------------------------------------------------------------------- -@anchor{xcode.extenal} -@section External Targets -The following external targets appear in the Xcode project and perform @b{build} and @b{clean} actions. +@example +make x264.clean +make x264 +@end example -@table @samp -@item external -Target maps to @command{make build} and @command{make clean} for everything Xcode products depend upon from the external build system. +Example; extract, configure, build and install external x264 module: -@item libhb -Target maps to @command{make libhb.build} and @command{make libhb.clean}. +@example +make x264.xclean +make x264.install +@end example -@item contrib -Target maps to @command{make contrib.build} and @command{make contrib.xclean}. +Example; something in a big module is failing; redo build sequentially: -@end table +@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 used in Xcode project for the external build system: +The following user defined settings are visible in Xcode project and are used +for the external build system. @table @samp @item EXTERNAL_BUILD -Specifies the build (scratch) directory for each configuration. +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. - -@item EXTERNAL_METHOD -Do not modify; Used for internal/external build coordination and must always be @samp{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 -Specifies the top-level source directory for @value{HB.name}. +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 diff --git a/doc/texi/building/method.checkout.texi b/doc/texi/building/method.checkout.texi index ca2352cec..32f668635 100644 --- a/doc/texi/building/method.checkout.texi +++ b/doc/texi/building/method.checkout.texi @@ -6,4 +6,4 @@ Checkout @value{HB.name} from the official source-code repository. Sources are checked out from the @samp{@value{HB.repo.branch}} branch. This document was generated from that very branch, and for example purposes, we will use exactly the same branch. -If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to use Subversion 1.5.0 or higher. Lower versions should also work. +If you have write-access to the repository, then you may add the appropriate login/password information as needed. It is recommended to use Subversion 1.6.0 or higher. Lower versions should also work. diff --git a/doc/texi/building/prerequisites.bundled.texi b/doc/texi/building/prerequisites.bundled.texi index f5af0fcce..b9f5b7590 100644 --- a/doc/texi/building/prerequisites.bundled.texi +++ b/doc/texi/building/prerequisites.bundled.texi @@ -1,3 +1,3 @@ @quotation Note -It is recommended to use the platform distribution's bundled compiler for maximum C++ compatibility. If you build with a custom compiler it will likely introduce non-standard runtime requirements. There are of course many valid reasons to build with unbundled compilers, but be aware it is generally unsupported and left as an exercise to the reader. +It is recommended to use the platform distribution's standard compiler for maximum C++ compatibility. If you build with a custom compiler it will likely introduce non-standard runtime requirements and have new/delete, exception and RTTI incompatibilities. There are of course many valid reasons to build with unbundled compilers, but be aware it is generally unsupported and left as an exercise to the reader. @end quotation diff --git a/doc/texi/building/prerequisites.common.texi b/doc/texi/building/prerequisites.common.texi index a975f9d56..64c21fd38 100644 --- a/doc/texi/building/prerequisites.common.texi +++ b/doc/texi/building/prerequisites.common.texi @@ -1,12 +1,12 @@ The following general tools are used on various platforms and it is recommended you use these versions or similar: @itemize @bullet -@item subversion - 1.6.2 -@item python - Python 2.4.6 -@item curl - curl 7.19.4 (or wget) +@item subversion - 1.6.16 +@item python - Python 2.7.1 +@item curl - curl 7.21.4 (or wget) @item m4 - GNU M4 1.4.6 @item make - GNU Make 3.81 @item patch - Patch 2.5.8 -@item tar - GNU tar 1.15.1 -@item wget - GNU Wget 1.11.4 (or curl) +@item tar - GNU tar 1.26 +@item wget - GNU Wget 1.13.4 (or curl) @end itemize |