1 Guide to Building HandBrake svn2194 (2009030201) on Cygwin
2 **********************************************************
11 5 Building via Terminal
19 5.4.4 Contrib Aggregates
25 This guide documents the recommended process to build HandBrake on
26 Cygwin hosts from the official source-code repository. Building from
27 any other source is not supported.
32 The following are the recommended specifications for building on
33 Cygwin; but is not necessarily the only configuration that is possible:
35 * Intel 32-bit or 64-bit hardware (only 32-bit product binaries are
40 * yasm 0.7.2.2153 (for i386 or x86_64 architectures)
42 Note: It is recommended to use the platform distribution's bundled
43 compiler for maximum C++ compatibility. If you build with a custom
44 compiler it will likely introduce non-standard runtime
45 requirements. There are of course many valid reasons to build with
46 unbundled compilers, but be aware it is generally unsupported and
47 left as an exercise to the reader.
49 Note: As of this writing, Cygwin has available to it several
50 versions of gcc; only one of which may be found and used in the
51 path as `gcc' and `g++'. Configure will thus find what is probably
52 the older version of gcc in a typical Cygwin environment. If you
53 desire to build with the newer gcc, it is found in the path as
54 `gcc-4' and `g++-4' respectively and you must indicate to
55 configure the desired versions. The following syntax should do the
58 ../configure --gcc=gcc-4
60 The following general tools are used on various platforms and it is
61 recommended you use these versions or similar:
65 * python - Python 2.4.6
67 * curl - curl 7.19.3 (or wget)
71 * make - GNU Make 3.81
75 * tar - GNU tar 1.15.1
77 * wget - GNU Wget 1.11.4 (or curl)
82 This chapter is for building from a terminal/shell environment in as
83 few commands as possible. If more flexibility is required you should
84 skip this chapter and jump to *Note overview::.
86 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
90 The special option `--launch' selected launch mode and performs the
93 * assert scratch directory `build/' does not exist
95 * create scratch directory `build/'
97 * change to directory `build/'
101 * capture build output to `build/log.txt'
108 Cygwin builds are performed from a terminal. There is no support for
109 building from any IDEs.
111 5 Building via Terminal
112 ***********************
117 Checkout HandBrake from the official source-code repository.
119 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
122 Sources are checked out from the `trunk' branch. This document was
123 generated from that very branch, and for example purposes, we will use
124 exactly the same branch.
126 If you have write-access to the repository, then you may add the
127 appropriate login/password information as needed. It is recommended to
128 use Subversion 1.5.0 or higher. Lower versions should also work.
133 Configure the build system.
140 Create a scratch directory which will contain all files created during
141 the build process. The directory name is arbitrary but we recommend
142 something simple and descriptive. One directory is required for each
143 distinctly configured build. We name our directory `build' for example
146 The `configure' utility accepts many options. It is recommended that
147 you specify `--help' for the complete list of options. The following
148 options are also documented here:
151 List available options.
154 Specify destination directory for final product install. This
155 defaults to a reasonable platform-specific value.
158 Disable driving the build through Xcode. If this option is
159 disabled only `HandBrakeCLI' will be produced and Xcode will not
160 be invoked. Mac OS X only.
163 Disable building the GTK GUI on applicable platforms such as
167 Select debug mode. Must be one of `none', `min', `std', `max'.
168 This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
171 Select optimize mode. Must be one of `none', `speed', `size'.
172 This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
175 Select build architecture. The available architectures vary by
176 platform. Most platforms support exactly one architecture except
177 Mac OS X which has support for various universal binary
178 architectures. The available choices are hard-coded per platform
179 and no sanity checks for the required tools are performed.
182 Specify the `gcc' executable to use where EXE is the executable
183 name which is either absolute or environment `PATH' is searched
186 Clean-room procedures dictate that when certain factors change, old
187 builds should be scrapped and new builds configured. This is the main
188 reason for requiring a scratch directory; to promote consistent,
189 reliable and clean software builds. The following is a short list of
190 some of the reasons why someone may choose to scrap an existing build:
192 * configure with different options
194 * subversion working dir is updated and you want configure to
195 re-evaluate working dir metadata.
197 * build corruption is suspected
199 There are generally two methods for scrapping a build. The `build'
200 directory can be recusrively removed which has the effect of loosing
201 your existing configuration but does guarantee no residuals are left
202 behind. The other method is to ask the build system to perform an `make
203 xclean'. This is known to work well but will leave empty directories
204 behind. However, the configuration is left intact.
209 Build main product. All necessary dependencies are also built if
214 Parallel builds may optionally be enabled. Be aware that while a
215 parallel build may save time on systems with additional cores, the
216 output is often mixed, overlapped and sometimes even corrupted with
217 binary characters. Thus if you experience a build issue, you should
218 clean and redo the build in default serial mode to produce a readable
219 log. The following command allows for up to 4 concurrent jobs via make:
226 The build system supports passing many kinds of targets some of which
227 become very useful in normal development cycles. The targets by
228 convention are lower-case words passed to `make'. Global targets are
229 one-word targets. Scoped targets are usually two-words seperated by a
236 Alias for `make build'.
239 Build main product. All necessary dependencies are also built if
243 Clean all build output excluding contrib modules. Configuration is
247 Clean all build output including contrib modules. Configuration is
251 Build auto-generated project documentation. Various articles are
252 produced and may be found in `build/doc/articles'.
254 5.4.2 General Modules
255 ---------------------
257 General modules such as `libhb', `test' and `gtk' have the following
264 Clean build output for MODULE.
266 5.4.3 Contrib Modules
267 ---------------------
269 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
270 `lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
271 `libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264',
272 `xvidcore' and `zlib' have the following scoped targets:
275 Download source tarball from the Internet and save to
276 `TOP/downloads' directory. No checksumming is performed.
278 `make MODULE.extract'
279 Extract source tarball into `build' tree.
282 Apply appropriate patches (if any) to module sources.
284 `make MODULE.configure'
285 Configure module sources. This usually invokes autotool configure.
288 Build module. This usually invokes autotool build.
290 `make MODULE.install'
291 Install module products such as headers and libraries into `build'
292 tree. This usually invokes autotool install.
294 `make MODULE.uninstall'
295 Uninstall module products; generally the reverse of install. This
296 usually invokes autotool uninstall.
299 Clean module; generally the reverse of build. This usually
300 invokes autotool clean.
303 Extra clean module; first invokes uninstall then recursively
304 removes the module build directory.
306 5.4.4 Contrib Aggregates
307 ------------------------
309 For convenience, the following targets aggregate the all contrib
310 modules' respective targets together:
314 * make contrib.extract
318 * make contrib.configure
322 * make contrib.install
324 * make contrib.uninstall
328 * make contrib.xclean