2 @chapter Building via Terminal
4 @c %**-------------------------------------------------------------------------
5 @anchor{terminal.checkout}
6 @section Checkout Sources
7 @include building/method.checkout.texi
9 @c %**-------------------------------------------------------------------------
10 @anchor{terminal.configure}
12 Configure the build system.
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.
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:
27 List available options.
30 Specify destination directory for final product install.
31 This defaults to a reasonable platform-specific value.
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.
37 Disable building the GTK GUI on applicable platforms such as @value{OS.linux}.
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}.
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}.
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.
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.
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:
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
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.
64 @c %**-------------------------------------------------------------------------
65 @anchor{terminal.build}
67 Build main product. All necessary dependencies are also built if required.
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:
79 @c %**-------------------------------------------------------------------------
80 @anchor{terminal.targets}
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.
85 @anchor{terminal.targets.global}
90 Alias for @samp{make build}.
93 Build main product. All necessary dependencies are also built if required.
96 Clean all build output excluding contrib modules. Configuration is retained.
99 Clean all build output including contrib modules. Configuration is retained.
102 Build auto-generated project documentation. Various articles are produced and may be found in @file{build/doc/articles}.
105 @anchor{terminal.targets.general}
106 @subsection General Modules
108 General modules such as @samp{libhb}, @samp{test} and @samp{gtk} have the following scoped targets:
111 @item make @i{MODULE}.build
114 @item make @i{MODULE}.clean
115 Clean build output for @i{MODULE}.
118 @anchor{terminal.targets.contrib}
119 @subsection Contrib Modules
121 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:
124 @item make @i{MODULE}.fetch
125 Download source tarball from the Internet and save to @file{TOP/downloads} directory. No checksumming is performed.
127 @item make @i{MODULE}.extract
128 Extract source tarball into @file{build} tree.
130 @item make @i{MODULE}.patch
131 Apply appropriate patches (if any) to module sources.
133 @item make @i{MODULE}.configure
134 Configure module sources.
135 This usually invokes autotool configure.
137 @item make @i{MODULE}.build
139 This usually invokes autotool build.
141 @item make @i{MODULE}.install
142 Install module products such as headers and libraries into @file{build} tree.
143 This usually invokes autotool install.
145 @item make @i{MODULE}.uninstall
146 Uninstall module products; generally the reverse of install.
147 This usually invokes autotool uninstall.
149 @item make @i{MODULE}.clean
150 Clean module; generally the reverse of build.
151 This usually invokes autotool clean.
153 @item make @i{MODULE}.xclean
154 Extra clean module; first invokes uninstall then recursively removes the module build directory.
157 @anchor{terminal.targets.contrib.aggregate}
158 @subsection Contrib Aggregates
160 For convenience, the following targets aggregate the all contrib modules' respective targets together:
163 @item make contrib.fetch
164 @item make contrib.extract
165 @item make contrib.patch
166 @item make contrib.configure
167 @item make contrib.build
168 @item make contrib.install
169 @item make contrib.uninstall
170 @item make contrib.clean
171 @item make contrib.xclean