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 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:
@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 quick-start 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 @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}.
@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:
@item build corruption is suspected
@end itemize
-There are generally two methods for scrapping a build. The @file{build} directory can be recusrively removed which has the effect of loosing your existing configuration but does guarantee no residuals are left behind. The other method is to ask the build system to perform an @command{make xclean}. This is known to work well but will leave empty directories behind. However, the configuration is left intact.
+There are generally two methods for scrapping a build. The @file{build} directory can be recursively removed which has the effect of loosing your existing configuration but does guarantee no residuals are left behind. The other method is to ask the build system to perform an @command{make xclean}. This is known to work well but will leave empty directories behind. However, the configuration is left intact.
@c %**-------------------------------------------------------------------------
@anchor{terminal.build}
@anchor{terminal.targets}
@section Make Targets
-The build system supports passing many kinds of targets some of which become very useful in normal development cycles. The targets by convention are lower-case words passed to @command{make}. Global targets are one-word targets. Scoped targets are usually two-words seperated by a period.
+The build system supports passing many kinds of targets some of which become very useful in normal development cycles. The targets by convention are lower-case words passed to @command{make}. Global targets are one-word targets. Scoped targets are usually two-words separated by a period.
@anchor{terminal.targets.global}
@subsection Global
@item make doc
Build auto-generated project documentation. Various articles are produced and may be found in @file{build/doc/articles}.
+
+@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.
+@b{For experts only}.
+
+@item make report.all
+Convenience target which aggregates all reports.
+@b{For experts only}.
@end table
@anchor{terminal.targets.general}
@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{libmp4v2}, @samp{libogg}, @samp{libsamplerate}, @samp{libtheora}, @samp{libvorbis}, @samp{mpeg2dec}, @samp{x264}, @samp{xvidcore} and @samp{zlib} have the following scoped targets:
+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:
@table @samp
@item make @i{MODULE}.fetch
-Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed.
+Download source tarball from the Internet and save to @file{TOP/downloads} directory. No check-summing is performed.
@item make @i{MODULE}.extract
Extract source tarball into @file{build} tree.
Extra clean module; first invokes uninstall then recursively removes the module build directory.
@end table
+@anchor{terminal.targets.contrib.touch}
+@subsection Contrib Touch and Untouch
+Also available are some very granular targets which help force builds from specific cycle points. The following targets are available to touch and untouch the respective module target; this will force the build system to treat the target as satisfied after a touch or unsatisfied after an untouch:
+
+@itemize
+@item make @i{MODULE}.extract.touch
+@item make @i{MODULE}.extract.untouch
+@item make @i{MODULE}.patch.touch
+@item make @i{MODULE}.patch.untouch
+@item make @i{MODULE}.configure.touch
+@item make @i{MODULE}.configure.untouch
+@item make @i{MODULE}.build.touch
+@item make @i{MODULE}.build.untouch
+@item make @i{MODULE}.install.touch
+@item make @i{MODULE}.install.untouch
+@end itemize
+
@anchor{terminal.targets.contrib.aggregate}
@subsection Contrib Aggregates
-
For convenience, the following targets aggregate the all contrib modules' respective targets together:
@itemize
@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 repository}:
+
+@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 rules 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
-GCC.gcc = gcc-4.2
+GCC.gcc = /usr/bin/gcc-4.2
-## replace optimize for 'speed' with more agressive settings
+## replace optimize for 'speed' with more aggressive settings
GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
@end example
+
+See also @command{make report.help} which displays a set of reports used to dump makefile vars.
OSDN Git Service
