doc/texi/building/chapter.via.terminal.texi

   1 @anchor{terminal}
   2 @chapter Building via Terminal
   3
   4 @c %**-------------------------------------------------------------------------
   5 @anchor{terminal.checkout}
   6 @section Checkout Sources
   7 @include building/method.checkout.texi
   8
   9 @c %**-------------------------------------------------------------------------
  10 @anchor{terminal.configure}
  11 @section Configure
  12 Configure the build system.
  13
  14 @example
  15 rm -fr build/
  16 mkdir build/
  17 cd build/
  18 ../configure
  19 @end example
  20
  21 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.
  22
  23 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:
  24
  25 @table @samp
  26 @item --help
  27 List available options.
  28
  29 @item --prefix=PREFIX
  30 Specify destination directory for final product install.
  31 This defaults to a reasonable platform-specific value.
  32
  33 @item --disable-xcode
  34 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.
  35
  36 @item --disable-gtk
  37 Disable building the GTK GUI on applicable platforms such as @value{OS.linux}.
  38
  39 @item --debug=MODE
  40 Select debug mode. Must be one of @samp{none}, @samp{min}, @samp{std}, @samp{max}.
  41 This generally maps to gcc options @samp{-g0}, @samp{-g1}, @samp{-g2}, @samp{-g3}.
  42
  43 @item --optimize=MODE
  44 Select optimize mode. Must be one of @samp{none}, @samp{speed}, @samp{size}.
  45 This generally maps to gcc options @samp{-g0}, @samp{-O0}, @samp{-O3}, @samp{-Os}.
  46
  47 @item --arch=MODE
  48 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.
  49
  50 @item --gcc=EXE
  51 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.
  52 @end table
  53
  54 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:
  55
  56 @itemize
  57 @item configure with different options
  58 @item subversion working dir is updated and you want configure to re-evaluate working dir metadata.
  59 @item build corruption is suspected
  60 @end itemize
  61
  62 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.
  63
  64 @c %**-------------------------------------------------------------------------
  65 @anchor{terminal.build}
  66 @section Build
  67 Build main product. All necessary dependencies are also built if required.
  68
  69 @example
  70 make
  71 @end example
  72
  73 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:
  74
  75 @example
  76 make -j4
  77 @end example
  78
  79 @c %**-------------------------------------------------------------------------
  80 @anchor{terminal.targets}
  81 @section Make Targets
  82
  83 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.
  84
  85 @anchor{terminal.targets.global}
  86 @subsection Global
  87
  88 @table @samp
  89 @item make
  90 Alias for @samp{make build}.
  91
  92 @item make build
  93 Build main product. All necessary dependencies are also built if required.
  94
  95 @item make clean
  96 Clean all build output excluding contrib modules. Configuration is retained.
  97
  98 @item make install
  99 Perform final product(s) install.
 100 This will install build products to a standard directory or one specified via @command{configure --prefix} option.
 101
 102 @item make uninstall
 103 Perform final product(s) uninstall.
 104 This will uninstall any products which may have been previously installed.
 105
 106 @item make xclean
 107 Clean all build output including contrib modules. Configuration is retained.
 108
 109 @item make doc
 110 Build auto-generated project documentation. Various articles are produced and may be found in @file{build/doc/articles}.
 111 @end table
 112
 113 @anchor{terminal.targets.general}
 114 @subsection General Modules
 115
 116 General modules such as @samp{libhb}, @samp{test} and @samp{gtk} have the following scoped targets:
 117
 118 @table @samp
 119 @item make @i{MODULE}.build
 120 Build @i{MODULE}.
 121
 122 @item make @i{MODULE}.clean
 123 Clean build output for @i{MODULE}.
 124 @end table
 125
 126 @anchor{terminal.targets.contrib}
 127 @subsection Contrib Modules
 128
 129 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:
 130
 131 @table @samp
 132 @item make @i{MODULE}.fetch
 133 Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed.
 134
 135 @item make @i{MODULE}.extract
 136 Extract source tarball into @file{build} tree.
 137
 138 @item make @i{MODULE}.patch
 139 Apply appropriate patches (if any) to module sources.
 140
 141 @item make @i{MODULE}.configure
 142 Configure module sources.
 143 This usually invokes autotool configure.
 144
 145 @item make @i{MODULE}.build
 146 Build module.
 147 This usually invokes autotool build.
 148
 149 @item make @i{MODULE}.install
 150 Install module products such as headers and libraries into @file{build} tree.
 151 This usually invokes autotool install.
 152
 153 @item make @i{MODULE}.uninstall
 154 Uninstall module products; generally the reverse of install.
 155 This usually invokes autotool uninstall.
 156
 157 @item make @i{MODULE}.clean
 158 Clean module; generally the reverse of build.
 159 This usually invokes autotool clean.
 160
 161 @item make @i{MODULE}.xclean
 162 Extra clean module; first invokes uninstall then recursively removes the module build directory.
 163 @end table
 164
 165 @anchor{terminal.targets.contrib.aggregate}
 166 @subsection Contrib Aggregates
 167
 168 For convenience, the following targets aggregate the all contrib modules' respective targets together:
 169
 170 @itemize
 171 @item make contrib.fetch
 172 @item make contrib.extract
 173 @item make contrib.patch
 174 @item make contrib.configure
 175 @item make contrib.build
 176 @item make contrib.install
 177 @item make contrib.uninstall
 178 @item make contrib.clean
 179 @item make contrib.xclean
 180 @end itemize
 181
 182 @c %**-------------------------------------------------------------------------
 183 @anchor{terminal.customizing}
 184 @section Customizing Make
 185 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:
 186
 187 @example
 188 ## bump to gcc-4.2 in current path
 189 GCC.gcc = gcc-4.2
 190
 191 ## replace optimize for 'speed' with more agressive settings
 192 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 193 @end example