1 Guide to Building HandBrake svn2322 (2009041301) on Cygwin
2 **********************************************************
11 5 Building via Terminal
19 5.4.4 Contrib Touch and Untouch
20 5.4.5 Contrib Aggregates
22 Appendix A Project Repository Details
28 This guide documents the recommended process to build HandBrake on
29 Cygwin hosts from the official source-code repository. Building from
30 any other source is not supported.
35 The following are the recommended specifications for building on
36 Cygwin; but is not necessarily the only configuration that is possible:
38 * Intel 32-bit or 64-bit hardware (only 32-bit product binaries are
43 * yasm 0.7.2.2153 (for i386 or x86_64 architectures)
45 Note: It is recommended to use the platform distribution's bundled
46 compiler for maximum C++ compatibility. If you build with a custom
47 compiler it will likely introduce non-standard runtime
48 requirements. There are of course many valid reasons to build with
49 unbundled compilers, but be aware it is generally unsupported and
50 left as an exercise to the reader.
52 Note: As of this writing, Cygwin has available to it several
53 versions of gcc; only one of which may be found and used in the
54 path as `gcc' and `g++'. Configure will thus find what is probably
55 the older version of gcc in a typical Cygwin environment. If you
56 desire to build with the newer gcc, it is found in the path as
57 `gcc-4' and `g++-4' respectively and you must indicate to
58 configure the desired versions. The following syntax should do the
61 ../configure --gcc=gcc-4
63 The following general tools are used on various platforms and it is
64 recommended you use these versions or similar:
68 * python - Python 2.4.6
70 * curl - curl 7.19.3 (or wget)
74 * make - GNU Make 3.81
78 * tar - GNU tar 1.15.1
80 * wget - GNU Wget 1.11.4 (or curl)
85 This chapter is for building from a terminal/shell environment in as
86 few commands as possible. Upon completion of the following commands you
87 should have a fresh build of HandBrake. Further instructions are
88 available beginning with *Note overview:: which describes procedures
89 suitable for repeating builds. This chapter should be skipped by those
90 seeking more than a minimalist build.
92 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
96 The special option `--launch' selects launch mode and performs the
99 * assert scratch directory `build/' does not exist
101 * create scratch directory `build/'
103 * change to directory `build/'
107 * capture build output to `build/log/build.txt'
113 * indicate if build ultimately succeeded or failed
118 Cygwin builds are performed from a terminal. There is no support for
119 building from any IDEs.
121 5 Building via Terminal
122 ***********************
127 Checkout HandBrake from the official source-code repository.
129 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
132 Sources are checked out from the `trunk' branch. This document was
133 generated from that very branch, and for example purposes, we will use
134 exactly the same branch.
136 If you have write-access to the repository, then you may add the
137 appropriate login/password information as needed. It is recommended to
138 use Subversion 1.5.0 or higher. Lower versions should also work.
143 Configure the build system.
147 Configure will automatically create a scratch build directory `build'
148 unless you use GNU-style build procedures and first `cd' to a directory
149 other than top-level source. Additionally you may use `--build' to
150 specify the directory. The name of the directory is arbitrary but it is
151 recommended to use something which indicates transient files which are
152 not checked into the repository.
154 The `configure' utility accepts many options. It is recommended that
155 you specify `--help' for the complete list of options. The following
156 options are also documented here:
159 List available options.
162 Specify top-level source directory for HandBrake sources.
165 Specify destination directory for final product install. The
166 default is to use either `build' if in the top-level source
167 directory, otherwise `.'
170 Specify destination directory for final product install. This
171 defaults to a reasonable platform-specific value.
174 All-in-one option which launches the build and logs output
175 automatically. Useful for novices and quick-start procedures.
178 Disable shunting the build through `xcodebuild'. If this option is
179 applied, `HandBrakeCLI' will be produced in a similar fashion as
180 it is on other platforms; sans Xcode and the Cocoa application
181 will not be produced. Mac OS X only.
184 Disable building the GTK GUI on applicable platforms such as
188 Select debug mode. Must be one of `none', `min', `std', `max'.
189 This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
192 Select optimize mode. Must be one of `none', `speed', `size'.
193 This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
196 Select build architecture. The available architectures vary by
197 platform. Most platforms support exactly one architecture except
198 Mac OS X which has support for various universal binary
199 architectures. The available choices are hard-coded per platform
200 and no sanity checks for the required tools are performed.
203 Clean-room procedures dictate that when certain factors change, old
204 builds should be scrapped and new builds configured. This is the main
205 reason for requiring a scratch directory; to promote consistent,
206 reliable and clean software builds. The following is a short list of
207 some of the reasons why someone may choose to scrap an existing build:
209 * configure with different options
211 * subversion working dir is updated and you want configure to
212 re-evaluate working dir metadata.
214 * build corruption is suspected
216 There are generally two methods for scrapping a build. The `build'
217 directory can be recursively removed which has the effect of loosing
218 your existing configuration but does guarantee no residuals are left
219 behind. The other method is to ask the build system to perform an `make
220 xclean'. This is known to work well but will leave empty directories
221 behind. However, the configuration is left intact.
226 Build main product. All necessary dependencies are also built if
231 Parallel builds may optionally be enabled. Be aware that while a
232 parallel build may save time on systems with additional cores, the
233 output is often mixed, overlapped and sometimes even corrupted with
234 binary characters. Thus if you experience a build issue, you should
235 clean and redo the build in default serial mode to produce a readable
236 log. The following command allows for up to 4 concurrent jobs via make:
243 The build system supports passing many kinds of targets some of which
244 become very useful in normal development cycles. The targets by
245 convention are lower-case words passed to `make'. Global targets are
246 one-word targets. Scoped targets are usually two-words separated by a
253 Alias for `make build'.
256 Build main product. All necessary dependencies are also built if
260 Clean all build output excluding contrib modules. Configuration is
264 Perform final product(s) install. This will install build
265 products to a standard directory or one specified via `configure
269 Perform final product(s) uninstall. This will uninstall any
270 products which may have been previously installed.
273 Clean all build output including contrib modules. Configuration is
277 Build auto-generated project documentation. Various articles are
278 produced and may be found in `build/doc/articles'.
281 Print list of available makefile vars report targets. These
282 reports detail var definitions and expanded values used by the
283 build system. For experts only.
286 Convenience target which aggregates all reports. For experts only.
288 5.4.2 General Modules
289 ---------------------
291 General modules such as `libhb', `test' and `gtk' have the following
298 Clean build output for MODULE.
300 5.4.3 Contrib Modules
301 ---------------------
303 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
304 `lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
305 `libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264',
306 `xvidcore' and `zlib' have the following scoped targets:
309 Download source tarball from the Internet and save to
310 `TOP/downloads' directory. No check-summing is performed.
312 `make MODULE.extract'
313 Extract source tarball into `build' tree.
316 Apply appropriate patches (if any) to module sources.
318 `make MODULE.configure'
319 Configure module sources. This usually invokes autotool configure.
322 Build module. This usually invokes autotool build.
324 `make MODULE.install'
325 Install module products such as headers and libraries into `build'
326 tree. This usually invokes autotool install.
328 `make MODULE.uninstall'
329 Uninstall module products; generally the reverse of install. This
330 usually invokes autotool uninstall.
333 Clean module; generally the reverse of build. This usually
334 invokes autotool clean.
337 Extra clean module; first invokes uninstall then recursively
338 removes the module build directory.
340 5.4.4 Contrib Touch and Untouch
341 -------------------------------
343 Also available are some very granular targets which help force builds
344 from specific cycle points. The following targets are available to
345 touch and untouch the respective module target; this will force the
346 build system to treat the target as satisfied after a touch or
347 unsatisfied after an untouch:
349 * make MODULE.extract.touch
351 * make MODULE.extract.untouch
353 * make MODULE.patch.touch
355 * make MODULE.patch.untouch
357 * make MODULE.configure.touch
359 * make MODULE.configure.untouch
361 * make MODULE.build.touch
363 * make MODULE.build.untouch
365 * make MODULE.install.touch
367 * make MODULE.install.untouch
369 5.4.5 Contrib Aggregates
370 ------------------------
372 For convenience, the following targets aggregate the all contrib
373 modules' respective targets together:
377 * make contrib.extract
381 * make contrib.configure
385 * make contrib.install
387 * make contrib.uninstall
391 * make contrib.xclean
396 If the need arises to override settings in the build system
397 (essentially gnu-make variables) the recommended method is to create
398 optional include files which are automatically included if present and
399 follow this naming convention; Do not check these files into the
403 Custom makevar definitions outside `build'. Suitable for settings
404 which apply across all builds for a particular checkout; or which
405 survives manual removal of `build'.
408 Custom make rules outside `build'. Suitable for rules which apply
409 across all builds for a particular checkout; or which survives
410 manual removal of `build'.
412 `_BUILD_/GNUmakefile.custom.defs'
413 Custom makevar definitions specific to a `build' directory.
415 `_BUILD_/GNUmakefile.custom.rules'
416 Custom makevar rules specific to a `build' directory.
419 The purpose is to allow a place to store local build settings for
420 testing, tweaking, and experimenting with build configuration without
421 losing your settings if `configure' is invoked; ie: `configure' would
422 overwrite `GNUmakefile' and any customizations contained therein would
423 be lost. Here is a short example of what the contents of
424 `_SRC_/custom.defs' might contain:
426 ## bump to gcc-4.2 in current path
429 ## replace optimize for 'speed' with more aggressive settings
430 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
432 See also `make report.help' which displays a set of reports used to
435 Appendix A Project Repository Details
436 *************************************
438 url: svn://svn.handbrake.fr/HandBrake/trunk
439 root: svn://svn.handbrake.fr/HandBrake
441 uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
443 date: 2009-04-13 13:28:21 -0400