Part 1 and Part 2 of this series got you started with the OpenCable Application Platform Reference Implementation (OCAP RI) from the standpoint of an application developer. You learned how to run applications on the RI platform and how to create new applications for the RI or other OCAP devices. This final installment describes the OCAP RI from a platform perspective and shows how to build the RI from source. With the deep understanding of the OCAP RI stack that you'll gain from this article, you'll be equipped to optimize or enhance the platform, or port it to your choice of hardware.

The RI architecture

The OCAP RI uses the architecture shown in Figure 1:

The following bulleted information highlights Figure 1:

• The OCAP stack runs on a JVM, but some of the methods are implemented in native code. Accordingly, Figure 1 separates the Java language part of the OCAP stack from the native part of the OCAP stack.
  
  
• The JVM runs the Connected Device Configuration (CDC), Foundation Profile (FP), and Personal Basis Profile (PBP), as described in Part 1. The OCAP RI's JVM uses a modified version of an open source project called phoneME Advanced (see Resources).
  
  
• The native implementations of the OCAP stack and the JVM itself are ported to a layer of platform-independent code called the Multimedia Platform Extensions (MPE).
  
  
• MPE, in turn, calls platform-dependent code in the MPEOS layer. MPEOS is the part that needs to be ported to each device that runs on the OCAP stack.
  
  
• The RI platform is a kind of virtual device or device simulator. The RI platform itself can be built and run on either Windows or Linux to form a device simulator. When you use an MPEOS implementation that calls into the RI platform, the result is a functional OCAP stack running on a device simulator on a desktop computer.

Next, I'll show you how to build the OCAP RI on Windows.

Back to top

Tooling up

The OCAP RI must be built in a Linux-like environment. The fundamental build tools are:

• make
• gcc
• The Java compiler
• Ant

To build the OCAP RI on Windows, you need to install three packages:

• Cygwin
• Java Development Kit (JDK)
• Ant

Cygwin

The first step is to install Cygwin, which provides a Linux-like environment on Windows (see Resources). The OCAP RI project provides a version of Cygwin that already includes all the of the necessary additional packages. The hard way to get Cygwin installed correctly is to download and install it, then follow the OCAP RI documentation to install a specific list of required packages into Cygwin.

Begin by downloading the customized version of Cygwin. It's a ZIP file, about 64MB. When you have it, unzip it somewhere on your hard disk. You'll have a directory called cygwin-minimal-20090611. Open this directory, then run the setup.exe file that is inside.

For the most part, you can accept the defaults in the installer, but one thing you must change is to select the Install from Local Directory option on the Choose A Download Source screen, as shown in Figure 2:

In addition, you must tell the installer to install all of its packages. On the Select Packages screen, click next to All so that it says Install instead of Default, as shown in Figure 3:

JDK

Next, you need a JDK. I used the Sun (Oracle) kit. Begin by downloading an installer package.

The JDK provides javac (the Java compiler), jar (a tool that creates JAR files), and other tools.

Run the installer. You can accept most of the defaults, but I strongly suggest changing the installation directory, which will default to something inside C:\Program Files. Path names with spaces in them can be confusing, for you and for your tools, so choose something simpler. I chose C:\jdk1.6.0_18.

Ant

Ant is a sophisticated build tool that is especially well-suited for building Java code. The OCAP RI's build system is a hybrid of both Ant and make. Although make is installed as part of the Cygwin package, you need to download and install Ant separately.

Download a binary installer from the Ant Web site. Unzip it to a location of your choice. Again, I strongly suggest choosing a simple path (something without spaces), such as C:\apache-ant-1.8.0.

It's possible to build the OCAP RI even if the JDK and Ant are installed in more exotic locations such as C:\Program Files, but it's a little tricky.

Back to top

Getting the source

Now that you have all the tools you need, open up a Cygwin terminal by choosing Start > All Programs > Cygwin > Cygwin Bash Shell. You're ready to get the OCAP RI source.

As before, I suggest using an uncomplicated path. I put the OCAP RI source at the root of my Cygwin installation. The source files are contained in a Subversion repository, for which you can use guest credentials (username and password both cruise) to access the files. Use this sequence in the Cygwin shell to check out the code and put it in the root of your Cygwin installation:

$ cd /
$ export SVN_USER=cruise
$ export SVN_PASSWORD=cruise
$ svn checkout -N https://community.cablelabs.com/svn/OCAPRI

Subversion might give you a message about identifying the CableLabs server, because it's probably the first time you've accessed the machine. If that happens, you need to accept the server's certificate to proceed. Type p in response to the (R)eject, accept (t)emporarily or accept (p)ermanently? prompt:

Error validating server certificate for 'https://community.cablelabs.com:443':
 - The certificate is not issued by a trusted authority. Use the
   fingerprint to validate the certificate manually!
Certificate information:
 - Hostname: community.cablelabs.com
 - Valid: from Tue, 15 Dec 2009 00:00:00 GMT until Wed, 15 Dec 2010 23:59:59 GMT
 - Issuer: www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign,
           VeriSign International Server CA - Class 3,
           VeriSign, Inc., VeriSign Trust Network
 - Fingerprint: 8a:02:31:2e:5d:3b:5b:6c:c8:70:85:e6:4d:8b:02:1f:93:1c:f3:cf
(R)eject, accept (t)emporarily or accept (p)ermanently? p
A    OCAPRI/checkout_dev_env.sh
A    OCAPRI/README
 U   OCAPRI
Checked out revision 7167.
$

This first part of the checkout goes quickly and retrieves two files from the Subversion repository.

Next, run the script called checkout_dev_env.sh to retrieve all the remaining source files you'll need:

$ cd OCAPRI
$ ./checkout_dev_env.sh trunk

This checkout step takes a long time, around 90 minutes on my computer. Your time will vary based on your computer's speed, the speed of your network connection, and how the CableLabs server is feeling.

I received some messages about network timeouts and did not get all the files I needed. If you run the checkout_dev_env.sh script a second time and it retrieves no files, you can be sure you have a complete set of source files.

Back to top

Time to build

The build requires two steps, both accomplished with a single build command. First, you need to build the RI platform itself, which is that close-to-the-bottom layer that sits above the device OS and supports the weight of the OCAP stack. The second step is building the OCAP implementation.

Setting environment variables

Before you can build anything, you must tell the build system where to find everything it needs. The build system relies on a handful of environment variables for this purpose:

• OCAPROOT is the most important variable. It points to the top-level directory for the OCAP implementation.
• OCAPTC is the OCAP Target Configuration, which is the device where you want to run the OCAP implementation.
• PLATFORMHOST indicates the type of computer that will perform the build.
• PLATFORMROOT is the base directory of the RI platform.

Fortunately, you already have a script — trunk/setEnv — that sets the environment variables. setEnv is generated by the checkout_dev_env.sh script you ran previously. But setEnv needs a little bit of editing before you're ready to build: you must add definitions for JAVA_HOME and ANT_HOME. The bold lines in Listing 1 are the ones I needed to add:

export PLATFORMROOT=C:/cygwin/OCAPRI/trunk/ri/RI_Platform
export OCAPROOT=C:/cygwin/OCAPRI/trunk/ri/ODLSrc/OCAP-1.0
export RICOMMONROOT=C:/cygwin/OCAPRI/trunk/common
export OCAPHOST=Win32-Cygwin
export OCAPTC=CableLabs/simulator/Win32/debug
export PLATFORMHOST=Win32-Cygwin
export PLATFORMTC=Win32/debug
export TWB_TOOLROOT=C:/cygwin/OCAPRI/trunk/ri/RI_Platform

export JAVA_HOME=C:/jdk1.6.0_18
export ANT_HOME=C:/apache-ant-1.8.0

if [ -z "${PATH_UR}" ]
then
  export PATH_UR=$PATH
fi

export PATH=`cygpath -u ${ANT_HOME}`/bin:`cygpath -u ${JAVA_HOME}`/bin:${PATH_UR}

The paths, of course, could be different for your computer.

Some of what I've added is a bit of nonsense that converts between Windows paths and Cygwin paths. The important point is that you must define JAVA_HOME and ANT_HOME and add them to PATH.

Once you have set up setEnv properly, run it:

$ cd trunk
$ source setEnv

Running the Ant build script

Now you're ready to build. The OCAP RI includes an Ant script that builds everything, both the RI platform and the OCAP implementation. Run it now:

$ cd ri
$ ant build

This takes about 13 minutes on my machine. When it finishes, you can run the OCAP RI:

$ cd $PLATFORMROOT
$ ./runRI.sh -tunetest -setup

You might need to tell your firewall to allow some network connections, but otherwise, within a minute you should be watching simulated television, as shown in Figure 4:

How the build system finds stuff

Here's a closer look at the environment variables the build system uses to help it decide how to perform the build.

PLATFORMHOST is really a path. The build system looks in $OCAPROOT/hostconfig/$PLATFORMHOST to locate settings. Mainly this is used to define tools that are used during the build.

The build system uses OCAPTC both to locate configuration information and to place output files. OCAPTC is also a path. The build system locates configuration files related to the target configuration by looking in $OCAPROOT/target/$OCAPTC. It creates intermediate build files in $OCAPROOT/gen/$OCAPTC, and it places the final results of the build in $OCAPROOT/bin/$OCAPTC.

One of the most important things that's determined by OCAPTC is which implementation of MPEOS to use. For example, in the Windows OCAP RI build, OCAPTC is CableLabs/simulator/Win32/debug. If you look in $OCAPROOT/target/CableLabs/simulator/Win32/debug/buildrules.properties, you'll see this definition:

build.mpeos.BUILDOS=RI_Win32

This tells the build system to build the RI_Win32 implementation of MPEOS, which is implemented using the RI platform. You can find the corresponding source files in $OCAPROOT/mpe/os/RI_Win32.

Back to top

Finding your way around $OCAPROOT

Now you understand some of the locations the build system uses, but what about all those other directories? Here is a brief description of the important directories in $OCAPROOT:

• apps contains sample applications, including a suite of test applications located in apps/qa.
• bin contains the results of builds. The result of one build is placed in bin/$OCAPTC.
• docs is the home for documents and API references related to the OCAP platform.
• gen contains intermediate build files. You will probably never need to go inside this directory.
• hostconfig holds configuration files for build hosts.
• java contains the source code for the OCAP stack's Java language layer.
• jni holds the source code for the OCAP stack's native implementation layer.
• jvm is the place where the JVM source files live. This is a modified version of the phoneME Advanced project.
• mpe contains the source code for the MPE layer. It also contains, in mpe/os, various implementations of the MPEOS layer.
• target is the place for target-specific configuration files.
• thirdparty contains source code for various open source packages that are part of the OCAP implementation or the OCAP RI, like DirectFB, Freetype2, zlib, and more.

The output of the build, as you know, goes in $OCAPROOT/bin/$OCAPTC, in a few crucial files and directories.

The JVM itself, whose source is contained in $OCAPROOT/jvm, is built in place. Its binary libraries, especially libcvm, are copied to $OCAPROOT/bin/$OCAPTC/bin, and the rest of the supporting files are copied to $OCAPROOT/bin/$OCAPTC/env/cvm.

The native code layer of OCAP, the MPE layer, and the MPEOS layer are all built into a single library, libmpe, which is placed in $OCAPROOT/bin/$OCAPTC/bin.

The Java language layer of OCAP is built into $OCAPROOT/bin/$OCAPTC/env/sys/ocap-classes.jar.

Back to top

Conclusion

If you made it this far, you now know the OCAP RI from top to bottom. Part 1 of this series explained the architecture of the OCAP stack and introduced the OCAP RI, and you learned how to run applications using the OCAP RI on Windows. Part 2 explained how you can create your own applications for the OCAP stack, using either command-line tools or a plug-in for Eclipse.

Finally, in this article, you learned how to build the OCAP RI itself. This is the ultimate level of control for anyone interested in working with OCAP. Based on the explanations of the build system and the source directories, you are now in a great position to start making changes in the RI code (subject to the license terms, of course) and see what happens. Happy coding!

Resources

Learn

• Instructions for building the OCAP RI: This page of the CableLabs OCAP-RI Wiki isn't as much fun to read as this article. On the other hand, you can check the Wiki page for the most up-to-date information.
  
  
• Build Environment - Cygwin MinGW: This OCAP-RI Wiki page has detailed instructions on installing Cygwin.
  
  
• phoneME Advanced: This project is the basis of the JVM that the OCAP RI uses.
  
  
• OCAP: The OCAP specification is available online from CableLabs.
  
  
• tru2way: tru2way is the consumer-facing brand for OCAP.
  
  
• "Creating Interactive TV Applications With the Tru2way Platform and OCAP" (Bruce Hopkins, Sun Developer Network, April 2009): This article introduces the interactive TV concept and how to start out with OCAP/tru2way development (sans the RI).
  
  
• "Blu-ray Disc Application Development with Java ME, Part 1: Creating Your First Application" (Bruce Hopkins, Sun Developer Network, September 2008): This article contains information about getting started with Blu-ray application development.
  
  
• "Cable Technology - Why Tru2way Will Explode In The U.S. In 2009" (Jeff Bonin, TMCnet, May 2009): Get a cable TV industry insider's take on the reasons why OCAP is generating demand for new products and services.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• developerWorks Java technology zone: Find hundreds of articles about every aspect of Java programming.
  
  

Get products and technologies

• OCAP RI: The OCAP RI project, hosted on java.net, is the place to go to download the binary installer or the Eclipse plug-in.
  
  

Discuss

• OCAP-RI Users forum: java.net hosts a forum for developers working with the OCAP RI.
  
  
• Get involved in the My developerWorks community.
  
  

About the author

Jonathan Knudsen is the author of several books and more than a hundred articles about Java technology and mobile robots. He is the husband of the most glorious woman to walk the Earth, the father of four amazing children, a decent piano player, and the scourge of many Bonsai trees. When Jonathan grows up, he wants to be a cowboy. For more information, see http://jonathanknudsen.com/.

Rate this article

Comments

Back to top

Table of contents

• The RI architecture
• Tooling up
• Getting the source
• Time to build
• Finding your way around $OCAPROOT
• Conclusion
• Resources
• About the author
• Comments

Dig deeper into Java on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers