From 8cfa7b9504c66677bff67d9097541f62ea7e3a40 Mon Sep 17 00:00:00 2001 From: konablend Date: Mon, 2 Mar 2009 07:30:13 +0000 Subject: BuildSystem: - split build guide into 3 articles, one for each platform - populated root of tree with 3 platform Building guides: osx, cygwin, linux for convenience - added python script (needs python3.0) to optionally generate wiki from .texi articles git-svn-id: svn://svn.handbrake.fr/HandBrake/trunk@2195 b64f7644-9d1e-0410-96f1-a4d463321fa5 --- doc/texi/BuildUserGuide.texi | 280 --------------------------- doc/texi/Building.cygwin.texi | 45 +++++ doc/texi/Building.linux.texi | 58 ++++++ doc/texi/Building.osx.texi | 45 +++++ doc/texi/build/command.texi | 27 --- doc/texi/build/platform.common.bundled.texi | 3 - doc/texi/building/chapter.introduction.texi | 3 + doc/texi/building/chapter.overview.texi | 21 ++ doc/texi/building/chapter.quickstart.texi | 19 ++ doc/texi/building/chapter.via.terminal.texi | 172 ++++++++++++++++ doc/texi/building/chapter.via.xcode.texi | 49 +++++ doc/texi/building/command.texi | 4 + doc/texi/building/method.checkout.texi | 9 + doc/texi/building/prerequisites.bundled.texi | 3 + doc/texi/building/prerequisites.common.texi | 12 ++ 15 files changed, 440 insertions(+), 310 deletions(-) delete mode 100644 doc/texi/BuildUserGuide.texi create mode 100644 doc/texi/Building.cygwin.texi create mode 100644 doc/texi/Building.linux.texi create mode 100644 doc/texi/Building.osx.texi delete mode 100644 doc/texi/build/command.texi delete mode 100644 doc/texi/build/platform.common.bundled.texi create mode 100644 doc/texi/building/chapter.introduction.texi create mode 100644 doc/texi/building/chapter.overview.texi create mode 100644 doc/texi/building/chapter.quickstart.texi create mode 100644 doc/texi/building/chapter.via.terminal.texi create mode 100644 doc/texi/building/chapter.via.xcode.texi create mode 100644 doc/texi/building/command.texi create mode 100644 doc/texi/building/method.checkout.texi create mode 100644 doc/texi/building/prerequisites.bundled.texi create mode 100644 doc/texi/building/prerequisites.common.texi (limited to 'doc/texi') diff --git a/doc/texi/BuildUserGuide.texi b/doc/texi/BuildUserGuide.texi deleted file mode 100644 index 7fb3a4d66..000000000 --- a/doc/texi/BuildUserGuide.texi +++ /dev/null @@ -1,280 +0,0 @@ -@input texinfo @c -*- Texinfo -*- -@c %**start of header -@setfilename BuildUserGuide.info -@include base/article.texi -@include build/command.texi -@paragraphindent none -@c %**end of header - -@majorheading @value{HB.title} Build User Guide -@contents - -@c %**------------------------------------------------------------------------- -@chapter Introduction -This guide documents the recommended process to build @value{HB.name} from the official source-code repository. @b{Building from any other source is not unsupported}. - -@chapter Quickstart -This chapter is for the impatient or those just looking for a quick summary of the commands used to launch a typical build with the fewest commands possible. For more control over the build process please skip this section and jump to @ref{Build Process} for full details. - -@example -@COMMAND.checkout{} -@COMMAND.configure.launch{} -@end example - -The above is an special streamlined invocation of @command{configure} which performs the following steps automatically: - -@itemize -@item assert scratch directory @file{build/} does not exist -@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 echo build output -@end itemize - -@c %**------------------------------------------------------------------------- -@anchor{Build Process} -@chapter Build Process - -@anchor{Checkout} -@section Checkout Sources -Checkout @value{HB.name} from the official source-code repository. - -@example -@COMMAND.checkout{} -@end example - -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. - -@anchor{Configure} -@section Configure -Configure the build system. - -@example -@COMMAND.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. - -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 detailed: - -@table @samp -@item --help -List available options. - -@item --debug=MODE -Select debug mode. Must be one of @samp{none}, @samp{min}, @samp{std}, @samp{max}. -This generally maps to gcc options @samp{-g0}, @samp{-g1}, @samp{-g2}, @samp{-g3}. - -@item --optimize=MODE -Select optimize mode. Must be one of @samp{none}, @samp{speed}, @samp{size}. -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: - -@itemize -@item configure with different options -@item subversion working dir is updated and you want configure to re-evaluate working dir metadata. -@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 use ask the build system to perform an @command{xclean}. This is known to work well but will leave empty directories behind. However, the configuration is left intact. See @ref{Extra Clean} for further details. - -@anchor{Build} -@section Build -Build main product. All necessary dependencies are also built if required. - -@example -@COMMAND.build{} -@end example - -Parallel builds may optionally be enabled. Be aware that while a parallel build may save time on systems with additional cores, the output is often mixed, overlapped and sometimes even corrupted with binary characters. Thus if you experience a build issue, you should clean and redo the build in default serial mode to produce a readable log. The following command allows for up to 4 concurrent jobs via make: - -@example -make -j4 -@end example - -@anchor{Clean} -@section Clean -Clean all build output excluding contrib modules. Configuration is retained. - -@example -@COMMAND.clean{} -@end example - -@anchor{Extra Clean} -@section Extra Clean -Clean all build output including contrib modules. Configuration is retained. - -@example -@COMMAND.xclean{} -@end example - -@c %**------------------------------------------------------------------------- -@anchor{Make Targets} -@chapter 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. - -@anchor{Global Targets} -@section Global - -@table @samp -@item make -Alias for @samp{make build}. - -@item make build -Build main product. All necessary dependencies are also built if required. - -@item make clean -Clean all build output excluding contrib modules. Configuration is retained. - -@item make xclean -Clean all build output including contrib modules. Configuration is retained. -@end table - -@anchor{General Module Targets} -@section General Modules - -General modules such as @samp{libhb} and @samp{test} have the following scoped targets: - -@table @samp -@item make @i{MODULE}.build -Build @i{MODULE}. - -@item make @i{MODULE}.clean -Clean build output for @i{MODULE}. -@end table - -@anchor{Contrib Module Targets} -@section 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: - -@table @samp -@item make @i{MODULE}.fetch -Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed. - -@item make @i{MODULE}.extract -Extract source tarball into @file{build} tree. - -@item make @i{MODULE}.patch -Apply appropriate patches (if any) to module sources. - -@item make @i{MODULE}.configure -Configure module sources. -This usually invokes autotool configure. - -@item make @i{MODULE}.build -Build module. -This usually invokes autotool build. - -@item make @i{MODULE}.install -Install module products such as headers and libraries into @file{build} tree. -This usually invokes autotool install. - -@item make @i{MODULE}.uninstall -Uninstall module products; generally the reverse of install. -This usually invokes autotool uninstall. - -@item make @i{MODULE}.clean -Clean module; generally the reverse of build. -This usually invokes autotool clean. - -@item make @i{MODULE}.xclean -Extra clean module; first invokes uninstall then recursively removes the module build directory. -@end table - -@anchor{Contrib Aggregate Targets} -@section Contrib Aggregate - -For convenience, the following targets aggregate the all contrib modules' respective targets together: - -@itemize -@item make contrib.fetch -@item make contrib.extract -@item make contrib.patch -@item make contrib.configure -@item make contrib.build -@item make contrib.install -@item make contrib.uninstall -@item make contrib.clean -@item make contrib.xclean -@end itemize - -@c %**------------------------------------------------------------------------- -@anchor{Platform} -@chapter Platform Requirements and Notes - -The build system supports various platforms of interest to the project. However this does not mean it supports all plaforms. If the platform is not listed in this chapter, then it is not supported. - -The following tools are used on various platforms and it is recommended you use these versions or newer: - -@itemize @bullet -@item python - Python 2.4.6 -@item curl - curl 7.19.3 (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) -@end itemize - -@anchor{@value{OS.osx}} -@section @value{OS.osx} - -Building on @value{OS.osx} is well supported. It is the reference platform for @value{HB.name}. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible: - -@itemize @bullet -@item Mac Intel hardware -@item @value{OS.osx} 10.5.6 -@item Xcode-3.1.2 -@item gcc 4.0.1 (Apple Inc. build 5490) -@item yasm 0.7.2.2153 (for i386 or x86_64 architectures) -@end itemize - -@include build/platform.common.bundled.texi - -@anchor{@value{OS.cygwin}} -@section @value{OS.cygwin} - -Building on @value{OS.cygwin} is supported. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible: - -@itemize @bullet -@item Intel 32-bit or 64-bit hardware -@item @value{OS.cygwin}, gcc 4.3.2 -@item yasm 0.7.1.2093 (for i386 or x86_64 architectures) -@end itemize - -@quotation Note -As of this writing, @value{OS.cygwin} has available to it several versions of gcc; only one of which may be found and -used in the path as @code{gcc} and @code{g++}. Configure will thus find what is probably the older version of gcc in a typical @value{OS.cygwin} environment. If you desire to build with the newer gcc, it is found in the path as @command{gcc-4} and @command{g++-4} respectively and you must indicate to configure the desired versions. The following syntax should do the trick: -@end quotation - -@example -../configure --gcc=gcc-4 -@end example - -@anchor{@value{OS.linux}} -@section @value{OS.linux} - -Building on @value{OS.linux} is supported. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible: - -@itemize @bullet -@item Intel 32-bit or 64-bit hardware -@item Fedora 8, gcc 4.1.2, yasm 0.6.2.1985 -@item Fedora 9, gcc 4.3.0, yasm 0.6.2.1985 -@item Fedora 10, gcc 4.3.2, yasm 0.7.1.2093 -@item gcc 4.0.0 or higher is reported to work -@end itemize - -@include build/platform.common.bundled.texi diff --git a/doc/texi/Building.cygwin.texi b/doc/texi/Building.cygwin.texi new file mode 100644 index 000000000..a2fda9ab3 --- /dev/null +++ b/doc/texi/Building.cygwin.texi @@ -0,0 +1,45 @@ +@input texinfo @c -*- Texinfo -*- +@c %**start of header +@setfilename Building.cygwin.info +@include base/article.texi +@include building/command.texi +@paragraphindent none + +@set BG.platform cygwin +@c %**end of header + +@majorheading Guide to Building @value{HB.title} on @value{OS.@value{BG.platform}} +@contents +@include building/chapter.introduction.texi + +@c %**------------------------------------------------------------------------- +@anchor{prerequisites} +@chapter Prerequisites +The following are the recommended specifications for building on @value{OS.cygwin}; but is not necessarily the only configuration that is possible: + +@itemize @bullet +@item Intel 32-bit or 64-bit hardware (only 32-bit product binaries are supported) +@item @value{OS.cygwin}, gcc 4.2.4 +@item yasm 0.7.2.2153 (for i386 or x86_64 architectures) +@end itemize + +@include building/prerequisites.bundled.texi + +@quotation Note +As of this writing, @value{OS.cygwin} has available to it several versions of gcc; only one of which may be found and used in the path as @code{gcc} and @code{g++}. Configure will thus find what is probably the older version of gcc in a typical @value{OS.cygwin} environment. If you desire to build with the newer gcc, it is found in the path as @command{gcc-4} and @command{g++-4} respectively and you must indicate to configure the desired versions. The following syntax should do the trick: +@end quotation + +@example +../configure --gcc=gcc-4 +@end example + +@include building/prerequisites.common.texi + +@c %**------------------------------------------------------------------------- +@include building/chapter.quickstart.texi + +@anchor{overview} +@chapter Overview +@value{OS.cygwin} builds are performed from a @b{terminal}. There is no support for building from any IDEs. + +@include building/chapter.via.terminal.texi diff --git a/doc/texi/Building.linux.texi b/doc/texi/Building.linux.texi new file mode 100644 index 000000000..b7aa14505 --- /dev/null +++ b/doc/texi/Building.linux.texi @@ -0,0 +1,58 @@ +@input texinfo @c -*- Texinfo -*- +@c %**start of header +@setfilename Building.linux.info +@include base/article.texi +@include building/command.texi +@paragraphindent none + +@set BG.platform linux +@c %**end of header + +@majorheading Guide to Building @value{HB.title} on @value{OS.@value{BG.platform}} +@contents +@include building/chapter.introduction.texi + +@c %**------------------------------------------------------------------------- +@anchor{prerequisites} +@chapter Prerequisites +The following are the recommended specifications for building on @value{OS.linux}; but is not necessarily the only configuration that is possible: + +@itemize @bullet +@item Intel 32-bit or 64-bit kernel +@item Fedora 8, gcc 4.1.2, yasm 0.6.2.1985 +@item Fedora 9, gcc 4.3.0, yasm 0.6.2.1985 +@item Fedora 10, gcc 4.3.2, yasm 0.7.1.2093 +@item gcc 4.0.0 or higher is reported to work +@end itemize + +@include building/prerequisites.bundled.texi + +The @b{GTK UI} introduces some significant extra build requirements. If you intend to disable building the GUI with @command{configure --disable-gtk} you may not need any of these packages installed: + +@itemize @bullet +@item build-essential +@item autoconf +@item intltool +@item libtool +@item zlib1g-dev +@item libbz2-dev +@item libglib2.0-dev +@item libdbus-glib-1-dev +@item libgtk2.0-dev +@item libhal-dev +@item libhal-storage-dev +@item libgtkhtml3.14-dev +@item libgstreamer0.10-dev +@item libgstreamer-plugins-base0.10-dev +@end itemize + +@include building/prerequisites.common.texi + +@c %**------------------------------------------------------------------------- +@include building/chapter.quickstart.texi + +@anchor{overview} +@chapter Overview +@value{OS.linux} builds are performed from a @b{terminal}. There is no support for building from any IDEs. + +@include building/chapter.via.terminal.texi diff --git a/doc/texi/Building.osx.texi b/doc/texi/Building.osx.texi new file mode 100644 index 000000000..00501c4c6 --- /dev/null +++ b/doc/texi/Building.osx.texi @@ -0,0 +1,45 @@ +@input texinfo @c -*- Texinfo -*- +@c %**start of header +@setfilename Building.osx.info +@include base/article.texi +@include building/command.texi +@paragraphindent none + +@set BG.platform osx +@c %**end of header + +@majorheading Guide to Building @value{HB.title} on @value{OS.@value{BG.platform}} + +@quotation Warning +Parallel builds on @value{OS.osx} are currently broken when building in a @b{terminal} with Xcode. You @b{must not use} the @command{make -jN} jobs option. A workaround is available if you do not need to build HandBrake.app (MacGUI): use @command{configure --disable-xcode} to disable Xcode. +@end quotation + +@contents +@include building/chapter.introduction.texi + +@c %**------------------------------------------------------------------------- +@anchor{prerequisites} +@chapter Prerequisites +Building on @value{OS.osx} is well supported. It is the reference platform for @value{HB.name}. The following are the recommended specifications for this platform; but is not necessarily the only configuration that is possible: + +@itemize @bullet +@item Mac Intel hardware +@item @value{OS.osx} 10.5.6 +@item Xcode-3.1.2 +@item gcc 4.0.1 (Apple Inc. build 5490) +@item yasm 0.7.2.2153 (for i386 and x86_64 architectures) +@end itemize + +@include building/prerequisites.bundled.texi +@include building/prerequisites.common.texi + +@c %**------------------------------------------------------------------------- +@include building/chapter.quickstart.texi + +@c %**------------------------------------------------------------------------- +@anchor{overview} +@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. + +@include building/chapter.via.terminal.texi +@include building/chapter.via.xcode.texi diff --git a/doc/texi/build/command.texi b/doc/texi/build/command.texi deleted file mode 100644 index db6b0b493..000000000 --- a/doc/texi/build/command.texi +++ /dev/null @@ -1,27 +0,0 @@ -@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} -@end macro - -@macro COMMAND.configure.launch{} -./configure --launch -@end macro - -@macro COMMAND.configure{} -rm -fr build/ -mkdir build/ -cd build/ -../configure -@end macro - -@macro COMMAND.build{} -make -@end macro - -@macro COMMAND.clean{} -make clean -@end macro - -@macro COMMAND.xclean{} -make xclean -@end macro diff --git a/doc/texi/build/platform.common.bundled.texi b/doc/texi/build/platform.common.bundled.texi deleted file mode 100644 index f5af0fcce..000000000 --- a/doc/texi/build/platform.common.bundled.texi +++ /dev/null @@ -1,3 +0,0 @@ -@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. -@end quotation diff --git a/doc/texi/building/chapter.introduction.texi b/doc/texi/building/chapter.introduction.texi new file mode 100644 index 000000000..9c6053349 --- /dev/null +++ b/doc/texi/building/chapter.introduction.texi @@ -0,0 +1,3 @@ +@anchor{introduction} +@chapter Introduction +This guide documents the recommended process to build @value{HB.name} on @value{OS.@value{BG.platform}} hosts from the official source-code repository. @b{Building from any other source is not supported}. diff --git a/doc/texi/building/chapter.overview.texi b/doc/texi/building/chapter.overview.texi new file mode 100644 index 000000000..29dec0394 --- /dev/null +++ b/doc/texi/building/chapter.overview.texi @@ -0,0 +1,21 @@ +@anchor{overview} +@chapter Build Overview +The build system has several + +This chapter is for building from a terminal/shell environment in as few commands as possible. If more flexibility is required you should skip this chapter and jump to @ref{process}. + +@example +@COMMAND.checkout{} +./configure --launch +@end example + +The special option @command{--launch} selected launch mode and performs the following steps: + +@itemize +@item assert scratch directory @file{build/} does not exist +@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 echo build output +@end itemize diff --git a/doc/texi/building/chapter.quickstart.texi b/doc/texi/building/chapter.quickstart.texi new file mode 100644 index 000000000..7829087e4 --- /dev/null +++ b/doc/texi/building/chapter.quickstart.texi @@ -0,0 +1,19 @@ +@anchor{quickstart} +@chapter QuickStart +This chapter is for building from a terminal/shell environment in as few commands as possible. If more flexibility is required you should skip this chapter and jump to @ref{overview}. + +@example +@COMMAND.checkout{} +./configure --launch +@end example + +The special option @command{--launch} selected launch mode and performs the following steps: + +@itemize +@item assert scratch directory @file{build/} does not exist +@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 echo build output +@end itemize diff --git a/doc/texi/building/chapter.via.terminal.texi b/doc/texi/building/chapter.via.terminal.texi new file mode 100644 index 000000000..5f2135a61 --- /dev/null +++ b/doc/texi/building/chapter.via.terminal.texi @@ -0,0 +1,172 @@ +@anchor{terminal} +@chapter Building via Terminal + +@c %**------------------------------------------------------------------------- +@anchor{terminal.checkout} +@section Checkout Sources +@include building/method.checkout.texi + +@c %**------------------------------------------------------------------------- +@anchor{terminal.configure} +@section Configure +Configure the build system. + +@example +rm -fr build/ +mkdir build/ +cd build/ +../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. + +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: + +@table @samp +@item --help +List available options. + +@item --prefix=PREFIX +Specify destination directory for final product install. +This defaults to a reasonable platform-specific value. + +@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. + +@item --disable-gtk +Disable building the GTK GUI on applicable platforms such as @value{OS.linux}. + +@item --debug=MODE +Select debug mode. Must be one of @samp{none}, @samp{min}, @samp{std}, @samp{max}. +This generally maps to gcc options @samp{-g0}, @samp{-g1}, @samp{-g2}, @samp{-g3}. + +@item --optimize=MODE +Select optimize mode. Must be one of @samp{none}, @samp{speed}, @samp{size}. +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: + +@itemize +@item configure with different options +@item subversion working dir is updated and you want configure to re-evaluate working dir metadata. +@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. + +@c %**------------------------------------------------------------------------- +@anchor{terminal.build} +@section Build +Build main product. All necessary dependencies are also built if required. + +@example +make +@end example + +Parallel builds may optionally be enabled. Be aware that while a parallel build may save time on systems with additional cores, the output is often mixed, overlapped and sometimes even corrupted with binary characters. Thus if you experience a build issue, you should clean and redo the build in default serial mode to produce a readable log. The following command allows for up to 4 concurrent jobs via make: + +@example +make -j4 +@end example + +@c %**------------------------------------------------------------------------- +@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. + +@anchor{terminal.targets.global} +@subsection Global + +@table @samp +@item make +Alias for @samp{make build}. + +@item make build +Build main product. All necessary dependencies are also built if required. + +@item make clean +Clean all build output excluding contrib modules. Configuration is retained. + +@item make xclean +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}. +@end table + +@anchor{terminal.targets.general} +@subsection General Modules + +General modules such as @samp{libhb}, @samp{test} and @samp{gtk} have the following scoped targets: + +@table @samp +@item make @i{MODULE}.build +Build @i{MODULE}. + +@item make @i{MODULE}.clean +Clean build output for @i{MODULE}. +@end table + +@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: + +@table @samp +@item make @i{MODULE}.fetch +Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed. + +@item make @i{MODULE}.extract +Extract source tarball into @file{build} tree. + +@item make @i{MODULE}.patch +Apply appropriate patches (if any) to module sources. + +@item make @i{MODULE}.configure +Configure module sources. +This usually invokes autotool configure. + +@item make @i{MODULE}.build +Build module. +This usually invokes autotool build. + +@item make @i{MODULE}.install +Install module products such as headers and libraries into @file{build} tree. +This usually invokes autotool install. + +@item make @i{MODULE}.uninstall +Uninstall module products; generally the reverse of install. +This usually invokes autotool uninstall. + +@item make @i{MODULE}.clean +Clean module; generally the reverse of build. +This usually invokes autotool clean. + +@item make @i{MODULE}.xclean +Extra clean module; first invokes uninstall then recursively removes the module build directory. +@end table + +@anchor{terminal.targets.contrib.aggregate} +@subsection Contrib Aggregates + +For convenience, the following targets aggregate the all contrib modules' respective targets together: + +@itemize +@item make contrib.fetch +@item make contrib.extract +@item make contrib.patch +@item make contrib.configure +@item make contrib.build +@item make contrib.install +@item make contrib.uninstall +@item make contrib.clean +@item make contrib.xclean +@end itemize diff --git a/doc/texi/building/chapter.via.xcode.texi b/doc/texi/building/chapter.via.xcode.texi new file mode 100644 index 000000000..f01874522 --- /dev/null +++ b/doc/texi/building/chapter.via.xcode.texi @@ -0,0 +1,49 @@ +@anchor{xcode} +@chapter Building via Xcode + +@c %**------------------------------------------------------------------------- +@anchor{xcode.checkout} +@section Checkout Sources +@include building/method.checkout.texi + +@c %**------------------------------------------------------------------------- +@anchor{xcode.build} +@section Build +In Xcode perform the following steps to build the default configuration: + +@itemize +@item open @file{macosx/HandBrake.xcodeproj} +@item select active configuration @b{standard} +@item select active target @b{HandBrake} +@item click @b{Build} or @b{Build and Go} +@end itemize + +The first time it builds will take a bit of time. You may use the Build Results window to watch it progress. A large partof the build is invoking the external build system which poduces quite a lot of log output. Much of that output 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 @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. + +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. + +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: + +@table @samp +@item standard +This configuration will build to the host native architecture. Build directory is @file{build.standard} . +The standard variant produces optimized code without debug information. + +@item debug +This configuration will build to the host native architecture. Build directory is @file{build.standard} . +The debug variant produces unoptimized code with debug information. + +@item standard.i386 +This configuration is used to build for the i386 architecture. Build directory is @file{build.standard.i386} . + +@item standard.x86_64 +This configuration is used to build for the x86_64 architecture. Build directory is @file{build.standard.x86_64} . + +@item standard.ppc +This configuration is used to build for the ppc architecture. Build directory is @file{build.standard.ppc} . + +@item standard.ppc64 +This configuration is used to build for the ppc64 architecture. Build directory is @file{build.standard.ppc64} . +@end table diff --git a/doc/texi/building/command.texi b/doc/texi/building/command.texi new file mode 100644 index 000000000..3acddc3a0 --- /dev/null +++ b/doc/texi/building/command.texi @@ -0,0 +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} +@end macro diff --git a/doc/texi/building/method.checkout.texi b/doc/texi/building/method.checkout.texi new file mode 100644 index 000000000..ca2352cec --- /dev/null +++ b/doc/texi/building/method.checkout.texi @@ -0,0 +1,9 @@ +Checkout @value{HB.name} from the official source-code repository. + +@example +@COMMAND.checkout{} +@end example + +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. diff --git a/doc/texi/building/prerequisites.bundled.texi b/doc/texi/building/prerequisites.bundled.texi new file mode 100644 index 000000000..f5af0fcce --- /dev/null +++ b/doc/texi/building/prerequisites.bundled.texi @@ -0,0 +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. +@end quotation diff --git a/doc/texi/building/prerequisites.common.texi b/doc/texi/building/prerequisites.common.texi new file mode 100644 index 000000000..a3e368073 --- /dev/null +++ b/doc/texi/building/prerequisites.common.texi @@ -0,0 +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.5.5 +@item python - Python 2.4.6 +@item curl - curl 7.19.3 (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) +@end itemize -- cgit v1.2.3