Xcode: Working with libvpx

This guide explains the steps required to build libvpx examples and to debug libvpx using Xcode.

Step 1: Build VPX.framework

This process is vastly simplified by using build/make/iosbuild.sh to produce a framework containing all necessary libvpx targets. The iOS simulator targets used to build the framework are basically identical to the Darwin targets that would be used for normal development builds of libvpx on Mac OS X.

1. Open a terminal window.

2. Create a directory in which to build the framework.

3. From within the directory just created:

     $ path/to/libvpx/build/make/iosbuild.sh --extra-configure-args --disable-webm-io

Notes

1. WebM IO is disabled to keep this guide simple.

2. Additional arguments are required if you wish to be able to step into libvpx with the debugger:

     $ path/to/libvpx/build/make/iosbuild.sh \

       --extra-configure-args "--disable-webm-io --enable-debug"

Step 2: Build a libvpx Example

Create a new command line tool project in Xcode, and:

1. Excluding files whose names start with webm, vpxdec, and vpxenc, add all .c and .h files from the root of the libvpx repository to the new project.

   • This is more than is necessary for any single example, but is harmless and keeps this guide short and simple (and ensures it works for most examples).

2. Add VPX.framework to the project.

3. Select an example to build, and add it to the project.

   • This can be vpxdec.c, vpxenc.c, or most of the files in the examples directory within the libvpx repository:

     • vp8_multi_resolution_encoder.c requires libyuv, which is well beyond the scope of this guide.

     • vp9_spatial_svc_encoder.c requires that additional undocumented flags are passed via --extra-configure-args when building VPX.framework.

4. Add the path to the Headers directory within VPX.framework to User Header Search Paths in your Xcode project settings, and make it recursive.

   • Mine is /Users/tomfinegan/libvpx/framework/VPX.framework/Headers

   • This is required because libvpx examples don't know anything about VPX.framework.

If all that is desired is the ability to build and hack on the examples, you're now done. 

Step 3: Debugging (Optional)

Debugging libvpx within Xcode can be achieved by setting breakpoints on calls into libvpx and stepping into those calls.

Deeper breakpoints can be set by adding additional libvpx source files to the project:

1. Add a file as you normally would.

2. Uncheck the box that adds the file to the current target.

   • The files will not compile, and would cause duplicate symbol linker errors anyway.

3. Set command line args for the current example (all examples define a usage() function, documenting required arguments).

4. Debug as you normally would.