xuggler _ Advanced Building Topics

Advanced Building Topics

Building (the hard way)

We try to make the build (relatively) easy, but sometimes, onsome systems, things might break. To help you debug what's going on,here's how the ant build system works.

First, every ant target (e.g. compile,install, run-tests, etc.) is actually composedof two targets: a -java target and a -nativetarget. For example, to compile just the java source code, run antcompile-java.

The ant build-suite will first attempt to build allthe native code required for Xuggler, and then build all the Java code.It creates a sub-directories under the build/ directory forall build-generated artifacts. Of particular importance, it creates adirectory under build/native for all C/C++ generated files,and runs configure to try to keep your main directory asclean as possible.

It does this by:

1. creating a directory under build/native based on the OS-name (as given by config.guess)
2. cd-ing to that directory, and running sh ../../../configure. If you're curious, you can run configure --help to see a list of the advanced configuration options that Xuggler supports.
3. running make all check to build all the native code, and run all native tests.
4. cd-ing back to the top directory, and running ant compile-java run-tests-java.

If all this succeeds , the ant install doessomething similar, only this time it runs make install tohave the native build system install all shared libraries in the rightsystem. On some operating systems this requires a re-linking of theshared libraries. Sorry about that.

You can feel free to do any of the sub-steps yourself, andhopefully that'll help you get this working.

Building on Microsoft Windows

Building on Windows is much harder than any other OS because youcan't use the Microsoft Visual C Compiler suite (FFmpeg will not build with it).

This means you need to install the GNU C++/C suite on Windows. Ifyou haven't already done this, and built the very latest FFmpeg, you may want to check outthis link for instructions on how to do that: FFmpeg on Windows Help.

In general, if you can already build FFmpeg on Windows, you'll beable to build the Xuggler.

Also, the ant / autotools build system doesn't dowell with $XUGGLE_HOME set to a directory name thatcontains spaces or isn't on your C: drive. A good setting to use is c:\msys\local.

Optional Build Software

Xuggler has some extra features that aren't enabled by default,but are enabled if you have additional software installed. Here's abrief description of what those are:

SWIG

Swig version 1.3.36 or higher.

By default if SWIG is not installed on your system, the Xugglerbuild system uses some "already generated" java and C++ bindings. Butyou can regenerate from scratch if you want, provided the followingsoftware is installed.

Note: our distributions are built with a special version of SWIGthat converts Javadoc comments in C++ into Javadoc comments in Java. Ifyou're poking in this area let us know, and we'll point you in thedirection of how to do this, but it's not that easy.

Valgrind

Valgrind version 3.3.1 or higher.

Xuggler comes with the ability to run a set of robust memoryself-checks on Linux systems using the Valgrind tool. If you installthat, then:

make memcheck

or

ant run-memcheck

will run this test.

Be warned, it takes a really long time to run, and will (falsely)report lots of errors if you abort it early.

Doxygen

Doxygen 1.5.8 or higher.

Xuggler comes with self-documenting code. If you want the C++version, you'll need Doxygen installed.

Graphviz

Version 2.20.3 or higher.

Doxygen can generate really helpful object-graphmethods to analyze code, and will use graphviz's dottool to do this.

GNU Autotools

Autoconf 2.63or higher, Automake1.10.2 or higher, and Libtool2.2.6a or higher.

Xuggle's native code is built using a gnu autotoolsbuild system. If you want to modify the library (e.g. add or removefiles from the build), you'll need these tools installed.

YASM

yasm version 0.7.2 or later

If you have yasm installed when you configure Xuggler, we'llinclude lots of assembly optimizations in libx264 and FFmpegthat can result in big speed-ups, especially when encoding. By defaultour Windows installer is built with yasm, but other OS's builds mustinstall yasm themselves.

A word on Captives and using your own version of FFmpeg

In order to (believe it or not) simplify the builds for mostpeople, Xuggler bundles in it's own versions of:

	The best and fastest (and free) raw tool for decoding and encoding media files. It's what does the heavy lifting underneath Xuggler; Xuggler adds a simpler API, additional automatic testing, the ability to embed in other languages with simple memory semantics, and time-stamp adjusting to the core libav* libraries in FFmpeg.
	VideoLAN's libx264 encoder: a free library for encoding H264/AVC video streams. libx264 is the leading open source implementation of H264/AVC encoding. Then you'll be able to use the ICodec.ID.CODEC_ID_H264 encoder.
	An MP3 encoder that works with FFmpeg. This means by default, Xuggler ships with the ability to encode MP3 audio (FFmpeg does not come with an MP3 encoder by default).
	The Speex audio encoder and decoder.
	The Theora video encoder and decoder.
	The Vorbis audio encoder and decoder.
FAAC	The Free Advanced Audio Coder (FAAC) is an open source library that encodes audio into AAC, the same format iPods and iPhones use.

This is helpful for most people, as it means they don't have tobuild these tools and install them prior to building and installing theXuggler.

But sometimes you want to use a version of FFmpeg you've builtyourself (for special codecs). We do support this, but you'll need tobuild the hard way. When running configure yourself, pass --disable-captives.Then our build script will not use our internal captive libraries, andinstead look for the required libraries (really just FFmpeg) on yoursystem.

The recommended way to build your own version of Xuggler's nativelibraries without captive libraries (or with any custom configurationoptions) is as follows

ant clobbermkdir mybuildcd mybuild../configure --disable-captivesmakemake checksudo make installcd ..ant stage-java run-tests-javasudo ant install-java

Once you've installed and build the native ffmpeg of your choice,and built your version of the Xuggler native libraries, you can stilluse our ant build system to build the java files. Youshould however only use the -java targets.

Xuggler Source-Tree Directory Structure

The directory structure used for Xuggler's source tree is asfollows:

• src/: Java source code
• csrc/: Native (C/C++) source code
• test/: Test source code
  • src/: Java source code
  • csrc/: Native (C/C++) source code
  • fixtures/: Any files needed or used by the tests. Copied during the build process to build/test/output/fixtures.
• generated/: Generated source code
  • java/: Java source code generated from SWIG.
  • native/: Native (C/C++) source code generated from SWIG or CXXTest.
• captive/: The captive directory contains the source for any additional libraries Xugger also builds (e.g. FFmpeg), along with scripts to integrate them into our build system (the process of integrating a "captive" library is called "incarcerating").
• mk/: The ant, make, and shell scripts needed to build Xuggler.
• doc/: The location of generated documentation.
  • java/: javadoc-generated documentation.
  • cpp/: doxygen-generated documentation.
  • test/: The results of the latest junit test run.
• share/: Any other shared Xuggle libraries with similar build systems.
• lib/: Any libraries required for the build process.
• build/: Where all object files and class files get built during the build process, and where all tests run from. This directory is destroyed when ant clobber is called.
  • native/: Where all native object (.o) files, shared libraries (e.g. .dll or .so files) are built.
    • OS-SPECIFIC-DIRECTORY/: A directory named based on the output of config.guess from the top level directory.
  • classes/: Where all Java class files for the src/ directory are placed.
  • lib/: Where all Ivy retrieved libraries are placed.
    • default/: Libraries needed at runtime.
    • compile/: Libraries needed to compile (includes all libraries in default/).
    • test/: Libraries needed to test with (includes all libraries in default/).
  • test/: Where all Java class files for the test/src directory are placed.
    • output/: Where all JUnit tests run from, and where any test data files are created.
      • fixtures/: Location of fixtures the JUnit tests use. Copied from test/fixtures at the top level directory.
• dist/: Where final versions of shared libraries and JAR files get deposited to.
  • lib/: Any required jar files that must also be installed with the jar files published by this application.
  • stage/: The final installtion files are installed here, ant install just copies the entire contents of this directory to /.
  • ivys/: If you don't define the environment variable $XUGGLE_REPO, then all ivy published files are published here, and builds search here for dependencies.
• build.xml: The ant build script.
• configure: The autools-generated configure script. In general do not run this script yourself. The ant build system will run it for you from build/native/OS-SPECIFIC-DIRECTORY

Xuggler Installation Tree Directory Structure

The directory structure used for Xuggler's installation tree (i.e$XUGGLE_HOME) is as follows:

• bin/: Any executable programs (and .dll files under Windows).
• lib/: Any shared libraries (.so or .dylib files), and static-linkage (.a) files.
• include/: Any C/C++ header files needed to for external libraries to integrate Xuggler into their builds.
• share/: Any os-independent data files (such as Java .jar files).
  • java/jars: Java .jar files for the installed library and its dependencies.

Xuggler Build System Targets

ant clean	Clean all generated Java and Native files
ant clean-java	Clean just the generated Java files (e.g. .class files).
ant clean-native	Clean just the generated Native files (e.g. .o files). Really runs make clean in the Native build tree.
ant clobber	Clean all generated Java and Native files, and force a reconfiguration on next build
ant clobber-java	Remove all generated java directories (and Native) and forces a reconfiguration on the next build. This is the fastest way to nuke everything.
ant clobber-native	Remove all generated Native files, and force a reconfiguration on the next build. Really runs make distclean in the Native build tree.
ant compile	Compile the Native and then the Java files.
ant compile-java	Compile just the Java (.java) files.
ant compile-native	Compile just the Native (.cpp) files, and optionally generated any required .java files. Really just runs make all in the Native build tree.
ant run-tests	Compile and run the Native and Java test suites.
ant run-tests-java	Compile and run the Java test suite; requires a build of the Native code.
ant run-tests-native	Compile and run the Native test suite. Really just runs make check in the Native build tree.
ant stage	Compile and link all native and java libraries, and install them in their final locations but prefixed with dist/stage
ant stage-java	Compile and link all native and java libraries, and install them in their final locations but prefixed with dist/stage
ant stage-native	Compile and link all native and java libraries, and install them in their final locations but prefixed with dist/stage
ant install	Copies staged installation from dist/stage to their final homes in $XUGGLE_HOME. ant stage must be run first.
ant doc	Build all documentation.
ant doc-java	Build all javadoc documentation.
ant doc-native	Build all native documentation. doxygen must have been installed during the configure run in order for this to work.