doc/texi/BuildUserGuide.texi

   1 @input texinfo @c -*- Texinfo -*-
   2 @c %**start of header
   3 @setfilename BuildUserGuide.info
   4 @include base/article.texi
   5 @include build/command.texi
   6 @paragraphindent none
   7 @c %**end of header
   8
   9 @majorheading @value{HB.title} Build User Guide
  10 @contents
  11
  12 @c %**-------------------------------------------------------------------------
  13 @chapter Introduction
  14 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}.
  15
  16 @chapter Quickstart
  17 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.
  18
  19 @example
  20 @COMMAND.checkout{}
  21 @COMMAND.configure.launch{}
  22 @end example
  23
  24 The above is an special streamlined invocation of @command{configure} which performs the following steps automatically:
  25
  26 @itemize
  27 @item assert scratch directory @file{build/} does not exist
  28 @item create scratch directory @file{build/}
  29 @item change to directory @file{build/}
  30 @item launch @command{make}
  31 @item capture build output to @file{build/log.txt}
  32 @item echo build output
  33 @end itemize
  34
  35 @c %**-------------------------------------------------------------------------
  36 @anchor{Build Process}
  37 @chapter Build Process
  38
  39 @anchor{Checkout}
  40 @section Checkout Sources
  41 Checkout @value{HB.name} from the official source-code repository.
  42
  43 @example
  44 @COMMAND.checkout{}
  45 @end example
  46
  47 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.
  48
  49 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.
  50
  51 @anchor{Configure}
  52 @section Configure
  53 Configure the build system.
  54
  55 @example
  56 @COMMAND.configure{}
  57 @end example
  58
  59 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.
  60
  61 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:
  62
  63 @table @samp
  64 @item --help
  65 List available options.
  66
  67 @item --debug=MODE
  68 Select debug mode. Must be one of @samp{none}, @samp{min}, @samp{std}, @samp{max}.
  69 This generally maps to gcc options @samp{-g0}, @samp{-g1}, @samp{-g2}, @samp{-g3}.
  70
  71 @item --optimize=MODE
  72 Select optimize mode. Must be one of @samp{none}, @samp{speed}, @samp{size}.
  73 This generally maps to gcc options @samp{-g0}, @samp{-O0}, @samp{-O3}, @samp{-Os}.
  74
  75 @item --arch=MODE
  76 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.
  77
  78 @item --gcc=EXE
  79 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.
  80 @end table
  81
  82 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:
  83
  84 @itemize
  85 @item configure with different options
  86 @item subversion working dir is updated and you want configure to re-evaluate working dir metadata.
  87 @item build corruption is suspected
  88 @end itemize
  89
  90 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.
  91
  92 @anchor{Build}
  93 @section Build
  94 Build main product. All necessary dependencies are also built if required.
  95
  96 @example
  97 @COMMAND.build{}
  98 @end example
  99
 100 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:
 101
 102 @example
 103 make -j4
 104 @end example
 105
 106 @anchor{Clean}
 107 @section Clean
 108 Clean all build output excluding contrib modules. Configuration is retained.
 109
 110 @example
 111 @COMMAND.clean{}
 112 @end example
 113
 114 @anchor{Extra Clean}
 115 @section Extra Clean
 116 Clean all build output including contrib modules. Configuration is retained.
 117
 118 @example
 119 @COMMAND.xclean{}
 120 @end example
 121
 122 @c %**-------------------------------------------------------------------------
 123 @anchor{Make Targets}
 124 @chapter Make Targets
 125
 126 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.
 127
 128 @anchor{Global Targets}
 129 @section Global
 130
 131 @table @samp
 132 @item make
 133 Alias for @samp{make build}.
 134
 135 @item make build
 136 Build main product. All necessary dependencies are also built if required.
 137
 138 @item make clean
 139 Clean all build output excluding contrib modules. Configuration is retained.
 140
 141 @item make xclean
 142 Clean all build output including contrib modules. Configuration is retained.
 143 @end table
 144
 145 @anchor{General Module Targets}
 146 @section General Modules
 147
 148 General modules such as @samp{libhb} and @samp{test} have the following scoped targets:
 149
 150 @table @samp
 151 @item make @i{MODULE}.build
 152 Build @i{MODULE}.
 153
 154 @item make @i{MODULE}.clean
 155 Clean build output for @i{MODULE}.
 156 @end table
 157
 158 @anchor{Contrib Module Targets}
 159 @section Contrib Modules
 160
 161 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:
 162
 163 @table @samp
 164 @item make @i{MODULE}.fetch
 165 Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed.
 166
 167 @item make @i{MODULE}.extract
 168 Extract source tarball into @file{build} tree.
 169
 170 @item make @i{MODULE}.patch
 171 Apply appropriate patches (if any) to module sources.
 172
 173 @item make @i{MODULE}.configure
 174 Configure module sources.
 175 This usually invokes autotool configure.
 176
 177 @item make @i{MODULE}.build
 178 Build module.
 179 This usually invokes autotool build.
 180
 181 @item make @i{MODULE}.install
 182 Install module products such as headers and libraries into @file{build} tree.
 183 This usually invokes autotool install.
 184
 185 @item make @i{MODULE}.uninstall
 186 Uninstall module products; generally the reverse of install.
 187 This usually invokes autotool uninstall.
 188
 189 @item make @i{MODULE}.clean
 190 Clean module; generally the reverse of build.
 191 This usually invokes autotool clean.
 192
 193 @item make @i{MODULE}.xclean
 194 Extra clean module; first invokes uninstall then recursively removes the module build directory.
 195 @end table
 196
 197 @anchor{Contrib Aggregate Targets}
 198 @section Contrib Aggregate
 199
 200 For convenience, the following targets aggregate the all contrib modules' respective targets together:
 201
 202 @itemize
 203 @item make contrib.fetch
 204 @item make contrib.extract
 205 @item make contrib.patch
 206 @item make contrib.configure
 207 @item make contrib.build
 208 @item make contrib.install
 209 @item make contrib.uninstall
 210 @item make contrib.clean
 211 @item make contrib.xclean
 212 @end itemize
 213
 214 @c %**-------------------------------------------------------------------------
 215 @anchor{Platform}
 216 @chapter Platform Requirements and Notes
 217
 218 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.
 219
 220 The following tools are used on various platforms and it is recommended you use these versions or newer:
 221
 222 @itemize @bullet
 223 @item python - Python 2.4.6
 224 @item curl - curl 7.19.3 (or wget)
 225 @item m4 - GNU M4 1.4.6
 226 @item make - GNU Make 3.81
 227 @item patch - Patch 2.5.8
 228 @item tar - GNU tar 1.15.1
 229 @item wget - GNU Wget 1.11.4 (or curl)
 230 @end itemize
 231
 232 @anchor{@value{OS.osx}}
 233 @section @value{OS.osx}
 234
 235 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:
 236
 237 @itemize @bullet
 238 @item Mac Intel hardware
 239 @item @value{OS.osx} 10.5.6
 240 @item Xcode-3.1.2
 241 @item gcc 4.0.1 (Apple Inc. build 5490)
 242 @item yasm 0.7.2.2153 (for i386 or x86_64 architectures)
 243 @end itemize
 244
 245 @include build/platform.common.bundled.texi
 246
 247 @anchor{@value{OS.cygwin}}
 248 @section @value{OS.cygwin}
 249
 250 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:
 251
 252 @itemize @bullet
 253 @item Intel 32-bit or 64-bit hardware
 254 @item @value{OS.cygwin}, gcc 4.3.2
 255 @item yasm 0.7.1.2093 (for i386 or x86_64 architectures)
 256 @end itemize
 257
 258 @quotation Note
 259 As of this writing, @value{OS.cygwin} has available to it several versions of gcc; only one of which may be found and
 260 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:
 261 @end quotation
 262
 263 @example
 264 ../configure --gcc=gcc-4
 265 @end example
 266
 267 @anchor{@value{OS.linux}}
 268 @section @value{OS.linux}
 269
 270 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:
 271
 272 @itemize @bullet
 273 @item Intel 32-bit or 64-bit hardware
 274 @item Fedora 8, gcc 4.1.2, yasm 0.6.2.1985
 275 @item Fedora 9, gcc 4.3.0, yasm 0.6.2.1985
 276 @item Fedora 10, gcc 4.3.2, yasm 0.7.1.2093
 277 @item gcc 4.0.0 or higher is reported to work
 278 @end itemize
 279
 280 @include build/platform.common.bundled.texi