1 Guide to Building HandBrake svn2413 (2009051201) on Cygwin
2 **********************************************************
11 5 Building via Terminal
19 5.4.4 Contrib Touch and Untouch
20 5.4.5 Contrib Aggregates
23 Appendix A Project Repository Details
29 This guide documents the recommended process to build HandBrake on
30 Cygwin hosts from the official source-code repository. Building from
31 any other source is not supported.
36 The following are the recommended specifications for building on
37 Cygwin; but is not necessarily the only configuration that is possible:
39 * Intel 32-bit or 64-bit hardware (only 32-bit product binaries are
44 * yasm 0.7.2.2153 (for i386 or x86_64 architectures)
46 Note: It is recommended to use the platform distribution's bundled
47 compiler for maximum C++ compatibility. If you build with a custom
48 compiler it will likely introduce non-standard runtime
49 requirements. There are of course many valid reasons to build with
50 unbundled compilers, but be aware it is generally unsupported and
51 left as an exercise to the reader.
53 Note: As of this writing, Cygwin has available to it several
54 versions of gcc; only one of which may be found and used in the
55 path as `gcc' and `g++'. Configure will thus find what is probably
56 the older version of gcc in a typical Cygwin environment. If you
57 desire to build with the newer gcc, it is found in the path as
58 `gcc-4' and `g++-4' respectively and you must indicate to
59 configure the desired versions. The following syntax should do the
62 ../configure --gcc=gcc-4
64 The following general tools are used on various platforms and it is
65 recommended you use these versions or similar:
69 * python - Python 2.4.6
71 * curl - curl 7.19.3 (or wget)
75 * make - GNU Make 3.81
79 * tar - GNU tar 1.15.1
81 * wget - GNU Wget 1.11.4 (or curl)
86 This chapter is for building from a terminal/shell environment in as
87 few commands as possible. Upon completion of the following commands you
88 should have a fresh build of HandBrake. Further instructions are
89 available beginning with *Note overview:: which describes procedures
90 suitable for repeating builds. This chapter should be skipped by those
91 seeking more than a minimalist build.
93 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
97 The special option `--launch' selects launch mode and performs the
100 * assert scratch directory `build/' does not exist
102 * create scratch directory `build/'
104 * change to directory `build/'
108 * capture build output to `build/log/build.txt'
114 * indicate if build ultimately succeeded or failed
119 Cygwin builds are performed from a terminal. There is no support for
120 building from any IDEs.
122 5 Building via Terminal
123 ***********************
128 Checkout HandBrake from the official source-code repository.
130 svn checkout svn://svn.handbrake.fr/HandBrake/trunk hb-trunk
133 Sources are checked out from the `trunk' branch. This document was
134 generated from that very branch, and for example purposes, we will use
135 exactly the same branch.
137 If you have write-access to the repository, then you may add the
138 appropriate login/password information as needed. It is recommended to
139 use Subversion 1.5.0 or higher. Lower versions should also work.
144 Configure the build system.
148 Configure will automatically create a scratch build directory `build'
149 unless you use GNU-style build procedures and first `cd' to a directory
150 other than top-level source. Additionally you may use `--build' to
151 specify the directory. The name of the directory is arbitrary but it is
152 recommended to use something which indicates transient files which are
153 not checked into the repository.
155 The `configure' utility accepts many options. It is recommended that
156 you specify `--help' for the complete list of options. The following
157 options are also documented here:
160 List available options.
163 Specify top-level source directory for HandBrake sources.
166 Specify destination directory for final product install. The
167 default is to use either `build' if in the top-level source
168 directory, otherwise `.'
171 Specify destination directory for final product install. This
172 defaults to a reasonable platform-specific value.
175 All-in-one option which launches the build and logs output
176 automatically. Useful for novices and quick-start procedures.
179 Disable shunting the build through `xcodebuild'. If this option is
180 applied, `HandBrakeCLI' will be produced in a similar fashion as
181 it is on other platforms; sans Xcode and the Cocoa application
182 will not be produced. Mac OS X only.
185 Disable building the GTK GUI on applicable platforms such as
189 Select debug mode. Must be one of `none', `min', `std', `max'.
190 This generally maps to gcc options `-g0', `-g1', `-g2', `-g3'.
193 Select optimize mode. Must be one of `none', `speed', `size'.
194 This generally maps to gcc options `-g0', `-O0', `-O3', `-Os'.
197 Select build architecture. The available architectures vary by
198 platform. Most platforms support exactly one architecture except
199 Mac OS X which has support for various universal binary
200 architectures. The available choices are hard-coded per platform
201 and no sanity checks for the required tools are performed.
204 Clean-room procedures dictate that when certain factors change, old
205 builds should be scrapped and new builds configured. This is the main
206 reason for requiring a scratch directory; to promote consistent,
207 reliable and clean software builds. The following is a short list of
208 some of the reasons why someone may choose to scrap an existing build:
210 * configure with different options
212 * subversion working dir is updated and you want configure to
213 re-evaluate working dir metadata.
215 * build corruption is suspected
217 There are generally two methods for scrapping a build. The `build'
218 directory can be recursively removed which has the effect of loosing
219 your existing configuration but does guarantee no residuals are left
220 behind. The other method is to ask the build system to perform an `make
221 xclean'. This is known to work well but will leave empty directories
222 behind. However, the configuration is left intact.
227 Build main product. All necessary dependencies are also built if
232 Parallel builds may optionally be enabled. Be aware that while a
233 parallel build may save time on systems with additional cores, the
234 output is often mixed, overlapped and sometimes even corrupted with
235 binary characters. Thus if you experience a build issue, you should
236 clean and redo the build in default serial mode to produce a readable
237 log. The following command allows for up to 4 concurrent jobs via make:
244 The build system supports passing many kinds of targets some of which
245 become very useful in normal development cycles. The targets by
246 convention are lower-case words passed to `make'. Global targets are
247 one-word targets. Scoped targets are usually two-words separated by a
254 Alias for `make build'.
257 Build main product. All necessary dependencies are also built if
261 Clean all build output excluding contrib modules. Configuration is
265 Perform final product(s) install. This will install build
266 products to a standard directory or one specified via `configure
270 Perform final product(s) uninstall. This will uninstall any
271 products which may have been previously installed.
274 Clean all build output including contrib modules. Configuration is
278 Build auto-generated project documentation. Various articles are
279 produced and may be found in `build/doc/articles'.
282 Print list of available makefile vars report targets. These
283 reports detail var definitions and expanded values used by the
284 build system. For experts only.
287 Convenience target which aggregates all reports. For experts only.
289 5.4.2 General Modules
290 ---------------------
292 General modules such as `libhb', `test' and `gtk' have the following
299 Clean build output for MODULE.
301 5.4.3 Contrib Modules
302 ---------------------
304 Contrib modules such as `a52dec', `bzip2', `faac', `faad2', `ffmpeg',
305 `lame', `libdca', `libdvdread', `libmkv', `libmp4v2', `libogg',
306 `libsamplerate', `libtheora', `libvorbis', `mpeg2dec', `x264',
307 `xvidcore' and `zlib' have the following scoped targets:
310 Download source tarball from the Internet and save to
311 `TOP/downloads' directory. No check-summing is performed.
313 `make MODULE.extract'
314 Extract source tarball into `build' tree.
317 Apply appropriate patches (if any) to module sources.
319 `make MODULE.configure'
320 Configure module sources. This usually invokes autotool configure.
323 Build module. This usually invokes autotool build.
325 `make MODULE.install'
326 Install module products such as headers and libraries into `build'
327 tree. This usually invokes autotool install.
329 `make MODULE.uninstall'
330 Uninstall module products; generally the reverse of install. This
331 usually invokes autotool uninstall.
334 Clean module; generally the reverse of build. This usually
335 invokes autotool clean.
338 Extra clean module; first invokes uninstall then recursively
339 removes the module build directory.
341 5.4.4 Contrib Touch and Untouch
342 -------------------------------
344 Also available are some very granular targets which help force builds
345 from specific cycle points. The following targets are available to
346 touch and untouch the respective module target; this will force the
347 build system to treat the target as satisfied after a touch or
348 unsatisfied after an untouch:
350 * make MODULE.extract.touch
352 * make MODULE.extract.untouch
354 * make MODULE.patch.touch
356 * make MODULE.patch.untouch
358 * make MODULE.configure.touch
360 * make MODULE.configure.untouch
362 * make MODULE.build.touch
364 * make MODULE.build.untouch
366 * make MODULE.install.touch
368 * make MODULE.install.untouch
370 5.4.5 Contrib Aggregates
371 ------------------------
373 For convenience, the following targets aggregate the all contrib
374 modules' respective targets together:
378 * make contrib.extract
382 * make contrib.configure
386 * make contrib.install
388 * make contrib.uninstall
392 * make contrib.xclean
397 If the need arises to override settings in the build system
398 (essentially gnu-make variables) the recommended method is to create
399 optional include files which are automatically included if present and
400 follow this naming convention; Do not check these files into the
404 Custom makevar definitions outside `build'. Suitable for settings
405 which apply across all builds for a particular checkout; or which
406 survives manual removal of `build'.
409 Custom make rules outside `build'. Suitable for rules which apply
410 across all builds for a particular checkout; or which survives
411 manual removal of `build'.
413 `_BUILD_/GNUmakefile.custom.defs'
414 Custom makevar definitions specific to a `build' directory.
416 `_BUILD_/GNUmakefile.custom.rules'
417 Custom makevar rules specific to a `build' directory.
420 The purpose is to allow a place to store local build settings for
421 testing, tweaking, and experimenting with build configuration without
422 losing your settings if `configure' is invoked; ie: `configure' would
423 overwrite `GNUmakefile' and any customizations contained therein would
424 be lost. Here is a short example of what the contents of
425 `_SRC_/custom.defs' might contain:
427 ## bump to gcc-4.2 in current path
430 ## replace optimize for 'speed' with more aggressive settings
431 GCC.args.O.speed = -O3 -fomit-frame-pointer -msse4.2
433 See also `make report.help' which displays a set of reports used to
439 When troubleshooting build issues, the following files relative to the
440 `build/' directory may be especially useful:
443 Top-level makefile which contains build settings generated via
446 `log/config.info.txt'
447 Record of output from configure.
449 `log/config.verbose.txt'
450 Record of verbose output from configure.
453 Record of output from `configure --launch'. Similar output may be
454 recorded using `make' depending on which shell is in use, eg:
455 `make >& log/build.txt' or `make > log/build.txt 2>&1'.
457 `log/xcodemake.env.txt'
458 Environment (variables) dump as seen when Xcode forks `make'.
461 Appendix A Project Repository Details
462 *************************************
464 url: svn://svn.handbrake.fr/HandBrake/trunk
465 root: svn://svn.handbrake.fr/HandBrake
467 uuid: b64f7644-9d1e-0410-96f1-a4d463321fa5
469 date: 2009-05-12 14:06:22 -0400