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 ./configure
  16 @end example
  17
  18 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.
  19
  20 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:
  21
  22 @table @samp
  23 @item --help
  24 List available options.
  25
  26 @item --src=DIR
  27 Specify top-level source directory for @value{HB.name} sources.
  28
  29 @item --build=DIR
  30 Specify destination directory for final product install. The default is to use either @file{build} if in the top-level source directory, otherwise @file{.}
  31
  32 @item --prefix=DIR
  33 Specify destination directory for final product install.
  34 This defaults to a reasonable platform-specific value.
  35
  36 @item --launch
  37 All-in-one option which launches the build and logs output automatically.
  38 Useful for novices and quick-start procedures.
  39
  40 @item --disable-xcode
  41 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.
  42
  43 @item --disable-gtk
  44 Disable building the GTK GUI on applicable platforms such as @value{OS.linux}.
  45
  46 @item --debug=MODE
  47 Select debug mode. Must be one of @samp{none}, @samp{min}, @samp{std}, @samp{max}.
  48 This generally maps to gcc options @samp{-g0}, @samp{-g1}, @samp{-g2}, @samp{-g3}.
  49
  50 @item --optimize=MODE
  51 Select optimize mode. Must be one of @samp{none}, @samp{speed}, @samp{size}.
  52 This generally maps to gcc options @samp{-g0}, @samp{-O0}, @samp{-O3}, @samp{-Os}.
  53
  54 @item --arch=MODE
  55 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.
  56
  57 @end table
  58
  59 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:
  60
  61 @itemize
  62 @item configure with different options
  63 @item subversion working dir is updated and you want configure to re-evaluate working dir metadata.
  64 @item build corruption is suspected
  65 @end itemize
  66
  67 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.
  68
  69 @c %**-------------------------------------------------------------------------
  70 @anchor{terminal.build}
  71 @section Build
  72 Build main product. All necessary dependencies are also built if required.
  73
  74 @example
  75 make
  76 @end example
  77
  78 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:
  79
  80 @example
  81 make -j4
  82 @end example
  83
  84 @c %**-------------------------------------------------------------------------
  85 @anchor{terminal.targets}
  86 @section Make Targets
  87
  88 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.
  89
  90 @anchor{terminal.targets.global}
  91 @subsection Global
  92
  93 @table @samp
  94 @item make
  95 Alias for @samp{make build}.
  96
  97 @item make build
  98 Build main product. All necessary dependencies are also built if required.
  99
 100 @item make clean
 101 Clean all build output excluding contrib modules. Configuration is retained.
 102
 103 @item make install
 104 Perform final product(s) install.
 105 This will install build products to a standard directory or one specified via @command{configure --prefix} option.
 106
 107 @item make uninstall
 108 Perform final product(s) uninstall.
 109 This will uninstall any products which may have been previously installed.
 110
 111 @item make xclean
 112 Clean all build output including contrib modules. Configuration is retained.
 113
 114 @item make doc
 115 Build auto-generated project documentation. Various articles are produced and may be found in @file{build/doc/articles}.
 116
 117 @item make report.help
 118 Print list of available makefile vars report targets.
 119 These reports detail var definitions and expanded values used by the build system.
 120 @b{For experts only}.
 121
 122 @item make report.all
 123 Convenience target which aggregates all reports.
 124 @b{For experts only}.
 125 @end table
 126
 127 @anchor{terminal.targets.general}
 128 @subsection General Modules
 129
 130 General modules such as @samp{libhb}, @samp{test} and @samp{gtk} have the following scoped targets:
 131
 132 @table @samp
 133 @item make @i{MODULE}.build
 134 Build @i{MODULE}.
 135
 136 @item make @i{MODULE}.clean
 137 Clean build output for @i{MODULE}.
 138 @end table
 139
 140 @anchor{terminal.targets.contrib}
 141 @subsection Contrib Modules
 142
 143 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:
 144
 145 @table @samp
 146 @item make @i{MODULE}.fetch
 147 Download source tarball from the Internet and save to @file{TOP/downloads} directory. No check-summing is performed.
 148
 149 @item make @i{MODULE}.extract
 150 Extract source tarball into @file{build} tree.
 151
 152 @item make @i{MODULE}.patch
 153 Apply appropriate patches (if any) to module sources.
 154
 155 @item make @i{MODULE}.configure
 156 Configure module sources.
 157 This usually invokes autotool configure.
 158
 159 @item make @i{MODULE}.build
 160 Build module.
 161 This usually invokes autotool build.
 162
 163 @item make @i{MODULE}.install
 164 Install module products such as headers and libraries into @file{build} tree.
 165 This usually invokes autotool install.
 166
 167 @item make @i{MODULE}.uninstall
 168 Uninstall module products; generally the reverse of install.
 169 This usually invokes autotool uninstall.
 170
 171 @item make @i{MODULE}.clean
 172 Clean module; generally the reverse of build.
 173 This usually invokes autotool clean.
 174
 175 @item make @i{MODULE}.xclean
 176 Extra clean module; first invokes uninstall then recursively removes the module build directory.
 177 @end table
 178
 179 @anchor{terminal.targets.contrib.touch}
 180 @subsection Contrib Touch and Untouch
 181 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:
 182
 183 @itemize
 184 @item make @i{MODULE}.extract.touch
 185 @item make @i{MODULE}.extract.untouch
 186 @item make @i{MODULE}.patch.touch
 187 @item make @i{MODULE}.patch.untouch
 188 @item make @i{MODULE}.configure.touch
 189 @item make @i{MODULE}.configure.untouch
 190 @item make @i{MODULE}.build.touch
 191 @item make @i{MODULE}.build.untouch
 192 @item make @i{MODULE}.install.touch
 193 @item make @i{MODULE}.install.untouch
 194 @end itemize
 195
 196 @anchor{terminal.targets.contrib.aggregate}
 197 @subsection Contrib Aggregates
 198 For convenience, the following targets aggregate the all contrib modules' respective targets together:
 199
 200 @itemize
 201 @item make contrib.fetch
 202 @item make contrib.extract
 203 @item make contrib.patch
 204 @item make contrib.configure
 205 @item make contrib.build
 206 @item make contrib.install
 207 @item make contrib.uninstall
 208 @item make contrib.clean
 209 @item make contrib.xclean
 210 @end itemize
 211
 212 @c %**-------------------------------------------------------------------------
 213 @anchor{terminal.customizing}
 214 @section Customizing Make
 215 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}:
 216
 217 @table @file
 218 @item _SRC_/custom.defs
 219 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}.
 220
 221 @item _SRC_/custom.rules
 222 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}.
 223
 224 @item _BUILD_/GNUmakefile.custom.defs
 225 Custom makevar definitions specific to a @file{build} directory.
 226
 227 @item _BUILD_/GNUmakefile.custom.rules
 228 Custom makevar rules specific to a @file{build} directory.
 229
 230 @end table
 231
 232 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:
 233
 234 @example
 235 ## bump to gcc-4.2 in current path
 236 GCC.gcc = /usr/bin/gcc-4.2
 237
 238 ## replace optimize for 'speed' with more aggressive settings
 239 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 240 @end example
 241
 242 See also @command{make report.help} which displays a set of reports used to dump makefile vars.