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
 112 @item make report.help
 113 Print list of available makefile vars report targets.
 114 These reports detail var definitions and expanded values used by the build system.
 115 @b{For experts only}.
 116
 117 @item make report.all
 118 Convenience target which aggregates all reports.
 119 @b{For experts only}.
 120 @end table
 121
 122 @anchor{terminal.targets.general}
 123 @subsection General Modules
 124
 125 General modules such as @samp{libhb}, @samp{test} and @samp{gtk} have the following scoped targets:
 126
 127 @table @samp
 128 @item make @i{MODULE}.build
 129 Build @i{MODULE}.
 130
 131 @item make @i{MODULE}.clean
 132 Clean build output for @i{MODULE}.
 133 @end table
 134
 135 @anchor{terminal.targets.contrib}
 136 @subsection Contrib Modules
 137
 138 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:
 139
 140 @table @samp
 141 @item make @i{MODULE}.fetch
 142 Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed.
 143
 144 @item make @i{MODULE}.extract
 145 Extract source tarball into @file{build} tree.
 146
 147 @item make @i{MODULE}.patch
 148 Apply appropriate patches (if any) to module sources.
 149
 150 @item make @i{MODULE}.configure
 151 Configure module sources.
 152 This usually invokes autotool configure.
 153
 154 @item make @i{MODULE}.build
 155 Build module.
 156 This usually invokes autotool build.
 157
 158 @item make @i{MODULE}.install
 159 Install module products such as headers and libraries into @file{build} tree.
 160 This usually invokes autotool install.
 161
 162 @item make @i{MODULE}.uninstall
 163 Uninstall module products; generally the reverse of install.
 164 This usually invokes autotool uninstall.
 165
 166 @item make @i{MODULE}.clean
 167 Clean module; generally the reverse of build.
 168 This usually invokes autotool clean.
 169
 170 @item make @i{MODULE}.xclean
 171 Extra clean module; first invokes uninstall then recursively removes the module build directory.
 172 @end table
 173
 174 @anchor{terminal.targets.contrib.aggregate}
 175 @subsection Contrib Aggregates
 176
 177 For convenience, the following targets aggregate the all contrib modules' respective targets together:
 178
 179 @itemize
 180 @item make contrib.fetch
 181 @item make contrib.extract
 182 @item make contrib.patch
 183 @item make contrib.configure
 184 @item make contrib.build
 185 @item make contrib.install
 186 @item make contrib.uninstall
 187 @item make contrib.clean
 188 @item make contrib.xclean
 189 @end itemize
 190
 191 @c %**-------------------------------------------------------------------------
 192 @anchor{terminal.customizing}
 193 @section Customizing Make
 194 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:
 195
 196 @example
 197 ## bump to gcc-4.2 in current path
 198 GCC.gcc = gcc-4.2
 199
 200 ## replace optimize for 'speed' with more agressive settings
 201 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
 202 @end example
 203
 204 See also @command{make report.help} which displays a set of reports used to dump makefile vars.