diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/module.defs | 2 | ||||
| -rw-r--r-- | doc/module.rules | 2 | ||||
| -rw-r--r-- | doc/texi/Building.osx.texi | 28 | ||||
| -rw-r--r-- | doc/texi/base/handbrake.texi.m4 | 1 | ||||
| -rw-r--r-- | doc/texi/building/chapter.quickstart.texi | 5 | ||||
| -rw-r--r-- | doc/texi/building/chapter.via.terminal.texi | 42 | ||||
| -rw-r--r-- | doc/texi/building/chapter.via.xcode.texi | 11 | ||||
| -rw-r--r-- | doc/texi/building/command.texi | 4 |
8 files changed, 73 insertions, 22 deletions
diff --git a/doc/module.defs b/doc/module.defs index 1697c9b69..84d924ab7 100644 --- a/doc/module.defs +++ b/doc/module.defs @@ -1,6 +1,6 @@ $(eval $(call import.MODULE.defs,DOC,doc)) -DOC.in/ = $(PROJECT/)doc/ +DOC.in/ = $(SRC/)doc/ DOC.out/ = $(BUILD/)doc/ DOC.out.api/ = $(DOC.out/)api/ diff --git a/doc/module.rules b/doc/module.rules index f86b66c09..54fec6dc7 100644 --- a/doc/module.rules +++ b/doc/module.rules @@ -32,6 +32,8 @@ $(DOC.m4.out): $(DOC.M4.deps) $(DOC.m4.out): $(DOC.out/)%: $(DOC.in/)%.m4 $(call DOC.M4,$@,$<) +clean: doc.clean + ############################################################################### #.PHONY: wiki.post wiki.sync wiki.rm wiki.add wiki.propset wiki.clean diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi index a554f7a0e..a02ec6131 100644 --- a/doc/texi/Building.osx.texi +++ b/doc/texi/Building.osx.texi @@ -37,5 +37,33 @@ Building on @value{OS.osx} is well supported. It is the reference platform for @ @chapter Overview The two general methods to build on @value{OS.osx} are building from @b{terminal} or @b{Xcode}. The preferred method for automated and repeatable builds is to use the terminal. Otherwise the choice is generally up to the individual. In essence, the terminal actually invokes @command{xcodebuild} to build the very same targets contained in the Xcode project. +@c %**------------------------------------------------------------------------- @include building/chapter.via.terminal.texi + +@c %**------------------------------------------------------------------------- +@anchor{terminal.ub} +@section Universal Binaries +This section outlines convenience procedures for creating Universal Binaries for all the architectures. + +@quotation Note +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: + +@example +./configure --disable-xcode +cd build/ +make ub.build.serial +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}: + +@example +## prefer i386 (order is important) +UB.archs = i386 x86_64 +@end example + +@c %**------------------------------------------------------------------------- @include building/chapter.via.xcode.texi diff --git a/doc/texi/base/handbrake.texi.m4 b/doc/texi/base/handbrake.texi.m4 index efcfa8d82..0466df77c 100644 --- a/doc/texi/base/handbrake.texi.m4 +++ b/doc/texi/base/handbrake.texi.m4 @@ -25,6 +25,5 @@ dnl @set HB.repo.uuid __HB_repo_uuid @set HB.repo.rev __HB_repo_rev @set HB.repo.date __HB_repo_date -@set HB.repo.wcversion __HB_repo_wcversion @set HB.repo.official __HB_repo_official @set HB.repo.type __HB_repo_type diff --git a/doc/texi/building/chapter.quickstart.texi b/doc/texi/building/chapter.quickstart.texi index 9e18db756..6aee76b91 100644 --- a/doc/texi/building/chapter.quickstart.texi +++ b/doc/texi/building/chapter.quickstart.texi @@ -5,7 +5,6 @@ This chapter is for building from a terminal/shell environment in as few command @example @COMMAND.checkout{} ./configure --launch -cd build/ @end example The special option @command{--launch} selects launch mode and performs the following steps: @@ -15,6 +14,8 @@ The special option @command{--launch} selects launch mode and performs the follo @item create scratch directory @file{build/} @item change to directory @file{build/} @item launch @command{make} -@item capture build output to @file{build/log.txt} +@item capture build output to @file{build/log/build.txt} @item echo build output +@item print elapsed time +@item indicate if build ultimately succeeded or failed @end itemize diff --git a/doc/texi/building/chapter.via.terminal.texi b/doc/texi/building/chapter.via.terminal.texi index 29014819e..56afb8168 100644 --- a/doc/texi/building/chapter.via.terminal.texi +++ b/doc/texi/building/chapter.via.terminal.texi @@ -12,13 +12,10 @@ Configure the build system. @example -rm -fr build/ -mkdir build/ -cd build/ -../configure +./configure @end example -Create a scratch directory which will contain all files created during the build process. The directory name is arbitrary but we recommend something simple and descriptive. One directory is required for each distinctly configured build. We name our directory @file{build} for example purposes. +Configure will automatically create a scratch build directory @file{build} unless you use GNU-style build procedures and first @command{cd} to a directory other than top-level source. Additionally you may specify use @command{--build} to specify the directory. The name of the directory is arbitrary but it is recommended to use something which indicates transient files which are @b{not} checked into the repository. The @command{configure} utility accepts many options. It is recommended that you specify @command{--help} for the complete list of options. The following options are also documented here: @@ -26,12 +23,22 @@ The @command{configure} utility accepts many options. It is recommended that you @item --help List available options. -@item --prefix=PREFIX +@item --src=DIR +Specify top-level source directory for @value{HB.name} sources. + +@item --build=DIR +Specify destination directory for final product install. The default is to use either @file{build} if in the top-level source directory, otherwise @file{.} + +@item --prefix=DIR Specify destination directory for final product install. This defaults to a reasonable platform-specific value. +@item --launch +All-in-one option which launches the build and logs output automatically. +Useful for novices and quickstart procedures. + @item --disable-xcode -Disable driving the build through Xcode. If this option is disabled only @command{HandBrakeCLI} will be produced and Xcode will not be invoked. @value{OS.osx} only. +Disable shunting the build through Xcode. If this option is applied, @command{HandBrakeCLI} will be produced in a similare fashion as it is on other platforms; sans Xcode. @value{OS.osx} only. @item --disable-gtk Disable building the GTK GUI on applicable platforms such as @value{OS.linux}. @@ -47,8 +54,6 @@ 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 --gcc=EXE -Specify the @command{gcc} executable to use where @b{EXE} is the executable name which is either absolute or environment @samp{PATH} is searched accordingly. @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: @@ -207,7 +212,24 @@ For convenience, the following targets aggregate the all contrib modules' respec @c %**------------------------------------------------------------------------- @anchor{terminal.customizing} @section Customizing Make -If the need arises to override settings in the build system (essentially gnu-make variables) the recommended method is to create/edit the optional include file @file{build/GNUmakefile.custom} which sits adjacent to the top-level makefile. @b{Do not check this file into the respository}. The sole 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{build/GNUmakefile.custom} might contain: +If the need arises to override settings in the build system (essentially gnu-make variables) the recommended method is to create optional include files which are automatically included if present and follow this naming convention; @b{Do not check these files into the respository}: + +@table @file +@item _SRC_/custom.defs +Custom makevar definitions @i{outside} @file{build}. Suitable for settings which apply across all builds for a particular checkout; or which survives manual removal of @file{build}. + +@item _SRC_/custom.rules +Custom make rules @i{outside} @file{build}. Suitable for settings which apply across all builds for a particular checkout; or which survives manual removal of @file{build}. + +@item _BUILD_/GNUmakefile.custom.defs +Custom makevar definitions specific to a @file{build} directory. + +@item _BUILD_/GNUmakefile.custom.rules +Custom makevar rules specific to a @file{build} directory. + +@end table + +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 diff --git a/doc/texi/building/chapter.via.xcode.texi b/doc/texi/building/chapter.via.xcode.texi index df42faca0..a78e0808d 100644 --- a/doc/texi/building/chapter.via.xcode.texi +++ b/doc/texi/building/chapter.via.xcode.texi @@ -72,17 +72,16 @@ The following user defined settings are used in Xcode project for the external b @table @samp @item EXTERNAL_BUILD -Specifies the build location for each configuration. -It is highly recommended the locations always evaluate to a unique pathname when factoring the configuration name. +Specifies the build (scratch) directory for each configuration. @item EXTERNAL_JOBS Specifies the concurrency factor for the external build system when builds are launched from within Xcode. -This variable is meant to be customized by the developer for faster builds if the host supports it. +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 -This variable is used for internal/external build coordination and must always be @samp{xcode}. +Do not modify; Used for internal/external build coordination and must always be @samp{xcode}. -@item EXTERNAL_PROJECT -Specifies the directory which is top of @value{HB.name} source tree. +@item EXTERNAL_SRC +Specifies the top-level source directory for @value{HB.name}. @end table diff --git a/doc/texi/building/command.texi b/doc/texi/building/command.texi index 4c21e9892..3acddc3a0 100644 --- a/doc/texi/building/command.texi +++ b/doc/texi/building/command.texi @@ -1,4 +1,4 @@ @macro COMMAND.checkout{} -svn checkout @value{HB.repo.url} @value{HB.acro.lower}@value{HB.repo.branch} -cd @value{HB.acro.lower}@value{HB.repo.branch} +svn checkout @value{HB.repo.url} @value{HB.acro.lower}-@value{HB.repo.branch} +cd @value{HB.acro.lower}-@value{HB.repo.branch} @end macro |