Advanced Building Topics

Building (the hard way)

We try to make the build (relatively) easy, but sometimes, on some 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 composed of two targets: a -java target and a -native target. For example, to compile just the java source code, run ant compile-java.

The ant build-suite will first attempt to build all the native code required for Xuggler, and then build all the Java code. It creates a sub-directories under the build/ directory for all build-generated artifacts. Of particular importance, it creates a directory under build/native for all C/C++ generated files, and runs configure to try to keep your main directory as clean 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 does something similar, only this time it runs make install to have the native build system install all shared libraries in the right system. On some operating systems this requires a re-linking of the shared libraries. Sorry about that.

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

Building on Microsoft Windows

Building on Windows is much harder than any other OS because you can'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. If you haven't already done this, and built the very latest FFmpeg, you may want to check out this link for instructions on how to do that: FFmpeg on Windows Help.

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

Also, the ant / autotools build system doesn't do well with $XUGGLE_HOME set to a directory name that contains 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 a brief description of what those are:

SWIG

Swig version 1.3.36 or higher.

By default if SWIG is not installed on your system, the Xuggler build system uses some "already generated" java and C++ bindings. But you can regenerate from scratch if you want, provided the following software is installed.

Note: our distributions are built with a special version of SWIG that converts Javadoc comments in C++ into Javadoc comments in Java. If you're poking in this area let us know, and we'll point you in the direction 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 memory self-checks on Linux systems using the Valgrind tool. If you install that, 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-graph methods to analyze code, and will use graphviz's dot tool to do this.

GNU Autotools

Autoconf 2.63 or higher, Automake 1.10.2 or higher, and Libtool 2.2.6a or higher.

Xuggle's native code is built using a gnu autotools build system. If you want to modify the library (e.g. add or remove files 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'll include lots of assembly optimizations in libx264 and FFmpeg that can result in big speed-ups, especially when encoding. By default our Windows installer is built with yasm, but other OS's builds must install yasm themselves.

A word on Captives and using your own version of FFmpeg

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

FFmpeg

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.
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.
LAME

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).
Speex

The Speex audio encoder and decoder.
Theora

The Theora video encoder and decoder.
Vorbis

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 to build these tools and install them prior to building and installing the Xuggler.

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

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

ant clobber
mkdir mybuild
cd mybuild
../configure --disable-captives
make
make check
sudo make install
cd ..
ant stage-java run-tests-java
sudo 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 still use our ant build system to build the java files. You should however only use the -java targets.

Xuggler Source-Tree Directory Structure

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

  • 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.