Download 5 Building the RI - CableLabs Community

CableLabs OpenCable Reference Implementation
Build Environment
v0.3
This document describes the steps required to setup the build environment for compiling
and running the CableLabs RI stack on Win32 and Linux hosts.
1 Cygwin
On Windows, the RI build requires a Cygwin installation for proper execution. All build
commands must be executed from a Cygwin shell. You may choose any shell (tcsh,
bash, ksh, etc.) that you are comfortable with, but be aware that you will probably have to
download your particular shell using the Cygwin installer.
You can download the Cygwin installer from www.cygwin.org. Make sure to select
Default Text File Type as Unix/binary.
1.1 Required Cygwin Packages
In addition to the packages which are selected by a default Cygwin installation, you must
install the following packages:
Package Name
Description
Known
Working
Version
Devel  gcc-core
Devel  gcc-g++
Devel  gcc-mingw-core
Devel  gcc-mingw-g++
Devel  gdb
Devel  binutils
Archive  zip
Archive  unzip
C Compiler
C++ Compiler
MinGW Support for GCC C
MinGW Support for GCC C++
GNU Debugger
GNU Utilities
File Compression Utility
File Decompression Utility
3.4.4-3
3.4.4-3
20050522-1
20050522-1
20041228-3
20080624-2
2.32-2
5.52-2
Note that some of these packages will be selected for you automatically due to the fact
that they are a dependency of a previously selected package.
1.2 Modified Make
The current version of the GNU Make utility as provided by the Cygwin installer
contains a rarely noticed bug that is exhibited by the MPE dependency generation
process. Someone in the community has created a patched version of the Make
executable for Cygwin that seems to fix the problem in our build. You can find the
patched executable inline in this document (or you can download it yourself from
http://www.cmake.org/files/cygwin/make.exe):
In order to prevent confusion with any previously installed version of make, it is wise to
place this new make into separate directory (such as ~/bin) and put that path before your
other PATH entries in your login script. You can also copy this executable directly to the
“bin” subdirectory of your main Cygwin installation directory if you are brave.
If you see a failure in your build that looks like the one below, you are not using the
patched version of make:
[exec]../gen/Vidiom/simulator/Win32/debug/mpe/mgr/ccmgr/cc_mgr.d:1:
*** multiple target patterns. Stop.
1.3 Additional Optional Cygwin Packages
For compiling, building and debugging any of the media libraries (GLib, GStreamer,
etc.), an additional set of Cygwin tools needs to be installed:
Package Name
Description
Known
Working
Version
Devel  bison
Devel  flex
Devel  pkg-config
Mingw  mingw-zlib
Utils  diffutils
Utils  patch
Parser Generator
Lexical Analyzer Generator
Installed Library Querying
MinGW Version of ZLib Library
GNU Collection of Diff Utilities
Apply a Diff File to an Original
2.3-1
2.5.35-1
0.23a-2
1.2.3-2
2.8.7-1
2.5.8-9
2 Linux
Due to the variety of existing Linux distributions, we have limited the scope of this
section to be based on a minimal installation of the Fedora Core 6 Linux distribution. It is
very likely, that the following steps can be easily adapted to any other similar distribution
available.
PLEASE NOTE THAT AT THIS TIME BUILDING OF STACK SOURCES IS
NOT SUPPORTED ON LINUX DUE TO THE LACK OF AN MPEOS PORTING
LAYER IMPLEMENTATION FOR THAT OS. ONLY COMPILATION OF
GSTREAMER AND RELATED PACKAGES IS FUNCTIONAL BY USING
STANDARD MAKE FILES (NO ANT).
2.1 Required Linux Packages
Compilation of the RI environment requires the following packages to be installed:
Package Name
Description
Known
Working
Version
gcc
gcc-c++
gdb
C Compiler
C++ Compiler
GNU Debugger
4.1.1-30
4.1.1-30
6.5-8
It is recommended to use the package management tools supplied by the distribution,
such as “yum” for Fedora, to automatically satisfy any dependencies that the listed
packages may require.
2.2 Additional Optional Linux Packages
For compiling, building and debugging any of the media libraries (GLib, GStreamer,
etc.), an additional set of Cygwin tools needs to be installed:
Package Name
Description
Known
Working
Version
bison
flex
pkgconfig
zlib-devel
Parser Generator
Lexical Analyzer Generator
Installed Library Querying
ZLib Library for Development
2.3-2
2.5.35-2
0.21-1
1.2.3-3
3 External Build Tools
The CableLabs RI requires two build tools to be installed on the host machine.
3.1 Java Development Kit
A JDK installation at least v1.5 Update 16 or greater is required to build the RI stack.
You can download Win32 and Linux installers for the v.1.5 JDKs from
http://java.sun.com/javase/downloads/index_jdk5.jsp.
It is recommended that you do not install the JDK to a path that contains spaces (such as
“Program Files”) due to the problems that UNIX terminals can have interpreting spaces
as argument separations. See the section regarding setting up your PATH environment
variable if you are running into problems.
3.2 Ant Build Tool
A good portion of the RI build is controlled by Ant build scripts. To execute these scripts
you will need a version (at least 1.6) of the Ant build tool installed on your host. The Ant
tool is written in Java and requires the presence of an installed JDK or JRE on the host
machine. Ant also requires the proper setup of the JAVA_HOME and ANT_HOME
environment variables as described in the next section. You can download Ant from
http://ant.apache.org.
4 Host Environment Variables
The host system will be required to establish a set of mandated environment variables to
facilitate RI stack builds. Ensure that these variables are set by your shell’s login script.
Environment Variable
Description
OCAPROOT
OCAPTC
OCAPHOST
Root directory of the stack
Target configuration directory
Host environment identifier. You will find
host-specific build settings in
$OCAPROOT/hostconfig/$OCAPHOST.
Location of a Java 1.4 or higher Java
Development Kit (JDK) installation.
Location of an Ant 1.6 or higher
installation.
$(JAVA_HOME)/bin
$(ANT_HOME)/bin
JAVA_HOME
ANT_HOME
PATH
4.1 Sample Login Script for Cygwin
Shown below is an example login script for bash.
##############################################################
# Env variables required for building the OCAP Stack and JVM
#
# Notice the use of "forward slashes" in all paths. This is
# required for the Cygwin build system.
##############################################################
# The root of the stack source tree
export OCAPROOT=c:/CableLabsRI/Subversion/ODLSrc_SunJVM
# Identifies the host development platform.
export OCAPHOST=Win32-Cygwin
export OCAPTC=Vidiom/simulator/Win32/debug
See $OCAPROOT/hostconfig
# Required for building the JVM
export JAVA_HOME=c:/Java/jdk1.5.0_16
###############################################################
# Client Sim env variables. Required for executing clientsim
###############################################################
export VIDIOM_TOOLROOT=${OCAPROOT}/bin/Vidiom/simulator/Win32/debug
export CLIENTSIM_TOOLROOT=${VIDIOM_TOOLROOT}/bin
export CLIENTSIM_ENV=${VIDIOM_TOOLROOT}/env
# Add Java and Ant bin directories to the path.
# Cygwin drive designations instead of Windows
export PATH=$PATH:/cygdrive/c/apache-ant1.7.1/bin:/cygdrive/c/Java/jdk1.5.0_16/bin
Notice the use of
Notice the use of forward slashes in all pathnames (even when using the MS-DOS “C:”
drive designation). Also, note the use of the Cygwin drive designation when adding Ant
and Java bin directories to the PATH.
If you have installed Ant or Java into a path location that contains spaces, you may be
able to replace the pathname in your PATH env variable with the MS-DOS “tilde”
form for long pathnames. For example, the directory name “Program Files” is
replaced by “Progra~1”.
4.2 Sample Login Script for Linux
Shown below is an example login script for bash.
##############################################################
# Env variables required for building the OCAP Stack and JVM
#
# Notice the use of "forward slashes" in all paths. This is
# required for the Cygwin build system.
##############################################################
# The root of the stack source tree
export OCAPROOT=$HOME/svn/ocap_ri/trunk/ri/ODLSrc/OCAP-1.0
# Identifies the host development platform.
export OCAPHOST=Linux
export OCAPTC=Vidiom/simulator/Linux/debug
See $OCAPROOT/hostconfig
# Required for building the JVM
export JAVA_HOME=/usr/java/jdk1.5.0_16
# Add Java and Ant bin directories to the path. Notice that the
# additional paths are added before the original PATH to avoid using
# system installed Java and Ant programs.
export PATH=/usr/java/apache-ant1.7.1/bin:/usr/java/Java/jdk1.5.0_16/bin:$PATH
5 Building the RI
This section discusses how to build the RI stack C and Java source along with
descriptions of the available build targets.
5.1 Ant Build
At the highest level, the stack is built completely by Ant build scripts. The top-level Ant
build file is always located in the platform-specific “target” directory (e.g.
$OCAPROOT/target/Vidiom/simulator/Win32/debug). If you have correctly installed
Ant and updated your PATH appropriately, you should be able to just execute “ant” to
build the default build target. To build specific target(s), simply execute:
ant <build_target> [<build_target> …]
Some commonly used build targets are listed below:
Build Target
Description
build
The default build target. Builds all RI targets (JVM
excluded).
Builds all JVM java and native sources. Installs final
binaries into their target-specific directories
Builds all native C source code including MPE, MPEOS,
JNI, CUnit, and third-party libs (FreeType, Zlib, etc.).
Installs final binaries into their target-specific directories.
Builds all Java sources, JUnit test sources, and generates
JNI headers. Installs final binaries into their targetspecific directories.
Builds all QA test xlet sources. Installs xlets and support
libs to their target-specific directories
Copies simulator binaries to their target specific
directories.
The default clean target. Cleans all generated and
compiled output binaries.
Cleans all JVM generated and compiled binaries.
NOTE: This target is currently broken. It is a known
problem with the Sun JVM build under Cygwin and
MSYS with no currently known solution.
Cleans all MPE generated and compiled binaries
Cleans all Java generated and compiled binaries
Cleans all QA test xlet generated and compiled binaries
The default purge target. Deletes all final binaries from
their target-specific installation directories.
Deletes final JVM binaries from their target-specific
directories
Deletes final MPE binaries from their target-specific
installation directories
Deletes final Java binaries from their target-specific
installation directories
Deletes final QA test xlet binaries from their targetspecific installation directories
build.jvm
build.mpe
build.java
build.qa
build.assets
clean
clean.jvm
clean.mpe
clean.java
clean.qa
purge
purge.jvm
purge.mpe
purge.java
purge.qa
5.2 JVM Build
By default, the JVM is not built by the standard build targets. The pre-built JVM binaries
are checked into the source repository in their final locations. The buildrules.properties
file located in $OCAPROOT/target/$OCAPTC contains a flag called
“build.jvm.exclude”. You can enable the building of the JVM by the default build targets
by commenting out this line.
5.3 Media Libraries Build
By default, the media libraries (GLib, GStreamer, etc.) are not built by the default target.
Their pre-built libraries are checked into the source repository in their final locations. It is
possible to enable building of those libraries by editing the file
$OCAPROOT/target/CableLabs/simulator/buildrules.mak and uncommenting the line
“CONFIG_BUILD_GSTREAMER=1”.