root/documentation/ossie/user-guide-0.7.0/Installation.tex @ 8306

% ------------------------------------------------------------------
%
%   TITLE: OSSIE 0.7.0 Installation Guide
% AUTHORS: Matt Carrick, Drew Cormier, Christopher Covington,
%          Carl B. Dietrich, Joseph Gaeddert, Benjamin Hilburn,
%          C. Ian Phelps, Shereef Sayed, Jason Snyder, Haris Volos
% CREATED: 
% REVISED: 
%     URL: http://ossie.wireless.vt.edu/
%
% ------------------------------------------------------------------

\newpage
\section{Installation}
\label{section:installation}
For users that do not have access to a Linux system, or are unfamiliar with Linux, we recommend
that you use our pre-built VMWare images.  These images have OSSIE pre-installed on them, and are
ready to use out-of-the-box. Using an OSSIE VMware image is described in
Section~\ref{section:installation:vmware}.

For most users on Fedora systems, installing OSSIE and its dependencies via yum is the best
route.  The only reason not to install via yum is if you plan on doing active
development \emph{on} OSSIE, and need access to the source code.  Note that this
does not include application/waveform developers who are developing \emph{with}
OSSIE, as they do not need access to the OSSIE source code.

Although we do not yet provide and support binary installation packages for more Linux
distributions, compiling OSSIE from source on them should be possible.

To install OSSIE from source, follow the below instructions to install the OSSIE dependencies,
and then compile and install the source code.  The latter process is simplified with a provided convenience
script, build.py, which compiles and installs OSSIE from source for you.

\subsection{Installing OSSIE via Yum}
\label{section:installation:yum}

\subsubsection{Add OSSIE Repository to Yum}
\label{section:installation:yum:ossierepo}
In order to install OSSIE via the YUM repository, you must first edit your `/etc/yum.conf' to 
add the OSSIE repository to the YUM search list. In this example, we use \tt{nano}, but you may use
whatever editor you wish (\tt{vim}, \tt{emacs}, etc). Unless your nanorc has already been configured to not
wrap lines, the `-w' flag is necessary to prevent \tt{nano} from adding line breaks to the file.
\begin{lstlisting}[]
$ su -
# nano -w /etc/yum.conf
\end{lstlisting}
Add the following lines at the bottom of the file:
\begin{lstlisting}[]
[ossie-vt]
name = OSSIE-VT
baseurl=http://ossie.wireless.vt.edu/yum/ossie-vt/
gpgcheck=0
\end{lstlisting}
Now update your system. This will refresh your yum package cache.  It is also always smart to have
a fully updated system before installing new software anyways.
\begin{lstlisting}[]
# yum update
\end{lstlisting}

\subsubsection{Install OSSIE}
\label{section:installation:yum:installviayum}
Now install OSSIE and its dependencies via yum by typing:
\begin{lstlisting}[]
# yum install ossie
# exit
\end{lstlisting}

Congratulations!  You should now have a fully-operable OSSIE installation.

\subsection{Installing OSSIE from Source}
\label{section:installation:source}

\subsubsection{Notes on OSSIE Installation from Source}
\label{section:installation:source:notesonsource}
This section assumes that the user is familiar with basic
Linux commands such as {\tt cd} and {\tt ls}.
Commands run with root permissions are prefixed with {\tt \#}, while others
are prefixed with {\tt \$}.

OSSIE depends on the following software packages:
\begin{itemize}
\item Xerces - a C++ XML parser
\item omniORB - a CORBA implementation
\item omniORBpy - a Python interface for omniORB, necessary for the OSSIE tools and components
\item wxPython - a Python interface for the wxWidgets graphical library, used by the OSSIE tools
\item numpy - a Python numerical library used by the OSSIE tools
\end{itemize}

OSSIE 0.7.0 is packaged with a convenient Python script called {\tt build.py} to automatically
configure and build the packages necessary for the framework, tools, and other
libraries. Use of this script is not mandatory, and you can manually compile and install all/part of
OSSIE as you wish.

\subsubsection{Installing Dependencies on Fedora}
\label{section:installation:source:dependencies:fedora}
On Fedora systems, the dependencies can be installed via {\tt yum}. 

First, add the OSSIE yum repository to your yum.conf.  This is described in
Section~\ref{section:installation:yum:ossierepo}

Now, install the dependencies.  This is the entire dependency list, so some of these packages may already be installed.
\begin{lstlisting}[]
# yum -y install xerces-c xerces-c-devel omniORB omniORBpy \
wxPython wxPython-devel numpy rpm-build cabextract glibc-devel \
python-devel openssl-devel gcc gcc-c++ libtool \
boost-1.33.1 boost-devel-1.33.1
\end{lstlisting}

Now move onto Section~\ref{section:installation:source:dependencies:configomni}

\subsubsection{Installing Dependencies on Ubuntu}
\label{section:installation:dependencies:ubuntu}
Edit the sources.list file through the GUI or by manually editing the file. 

To edit the file through the GUI, on the toolbar select 
System : Administration : Software Sources and enter the administrator password. 
Under the "Ubuntu Software" tab, make sure all of the boxes are selected which 
have the following tags at the end: (main), (universe), (restricted), and (multiverse). 
Then close the window and select ``Reload'' to update the package list.

To update the list manually, open the source.list file:
\begin{lstlisting}[]
$ sudo vim /etc/apt/sources.list
\end{lstlisting}
Make sure the following lines are uncommented:
\begin{lstlisting}[]
deb http://us.archive.ubuntu.com/ubuntu/ hardy universe
deb-src http://us.archive.ubuntu.com/ubuntu hardy universe
...
deb http://us.archive.ubuntu.com/ubuntu/ hardy main restricted
deb-src http://us.archive.ubuntu.com/ubuntu/ hardy main restricted
...
deb http://security.ubuntu.com/ubuntu hardy-security main restricted
deb-src http://security.ubuntu.com/ubuntu hardy-security main restricted
\end{lstlisting}

Now, update the local dpkg cache and upgrade:
\begin{lstlisting}[]
$ sudo aptitude update
$ sudo aptitude upgrade
\end{lstlisting}

This is the entire dependency list, so some of these packages may already be installed. 
Install all of the following packages:
\begin{lstlisting}[]
$ sudo aptitude install gcc build-essential
$ sudo aptitude -y install omniorb4 libomniorb4-dev omniidl4-python \
omniorb4-nameserver python-omniorb2 libgtk2.0-dev freeglut3-dev \
libxerces27-dev libxerces27 python-wxgtk2.8 python-wxversion \
python-wxtools python-numpy python-numpy-ext python-numpy-dev g++ \
automake libtool subversion python-dev fftw3-dev libcppunit-dev \
libboost-dev sdcc libusb-dev libasound2-dev libsdl1.2-dev guile-1.8 \
libqt3-mt-dev swig libboost-filesystem-dev python-profiler
\end{lstlisting}

\subsubsection{Configure omniORB}
\label{section:installation:source:dependencies:configomni}
Configure omniORB by editing {\tt /etc/omniORB.cfg} as root.
Around line 313 you should see:
\begin{lstlisting}[]
 InitRef = NameService=corbaname::my.host.name
\end{lstlisting}
Uncomment the line by deleting the pound or hash character `\#' and change
it to:
\begin{lstlisting}[]
 InitRef = NameService=corbaname::127.0.0.1
\end{lstlisting}
Before running the framework you will need to start the naming service.
{\tt omniNames} will automatically start when you restart your machine. Refer
to Appendix~\ref{appendix:services} for instructions on how to start the
omniNames service without restarting your machine or set whether the service
starts automatically at boot.
\footnote{You may also manually start a source-compiled tarball package of
omniNames {\tt omniNames} with the script described in
Appendix~\ref{appendix:omninamessh}}

At this time it is a good idea to restart your machine.

\subsubsection{Installing Portions of GNU Radio}
\label{section:installation:source:dependencies:gnuradio}
OSSIE uses a small subset of GNU Radio to communicate with and configure the USRP. The
following steps will walk through installing portions of GNU Radio.

First, GNU Radio's dependencies must be installed. If you are using Ubuntu and followed
the instructions for installing the dependencies, skip down to checking out the source
code from the GNU Radio Subversion repository. If you are installing on Fedora 9,
proceed with the following directions.

Install the Engineering and Scientific packages as well as the Software Development 
packages as root entering the command:

\begin{lstlisting}[]
 # yum groupinstall "Engineering and Scientific" "Development Tools"
\end{lstlisting}

Additional utilities such as the FFT library and the CPP Test Framework must also be 
installed. As root, enter the following command

\begin{lstlisting}[]
 # yum install fftw-devel cppunit-devel wxPython-devel libusb-devel  \
   guile boost-devel alsa-lib-devel numpy
\end{lstlisting}

The Small Device C Compiler, SDCC, must be installed:

\begin{lstlisting}[]
 # yum install sdcc
\end{lstlisting}

The path for the SDCC must be set. Open the .bashrc file and add the path to the end 
of the file. To open the file, enter the command:

\begin{lstlisting}[]
 $ vim ~/.bashrc
\end{lstlisting}

Add the following path to the end of the file:
\begin{lstlisting}[]
 export PATH=/usr/libexec/sdcc:$PATH
\end{lstlisting}

At this point, all of the GNU Radio dependencies have been installed. Now, the GNU Radio
software must be installed.

Download the GNU Radio source code by entering the command:
\begin{lstlisting}[]
 $ svn co http://gnuradio.org/svn/gnuradio/branches/releases/3.1 gnuradio
\end{lstlisting}

Move into the {\tt gnuradio} directory and start building the source code by entering the
following commands:

\begin{lstlisting}[]
 $ cd gnuradio/
 $ ./bootstrap
 $ ./configure --disable-all-components --enable-gnuradio-core \
   --enable-usrp --enable-gr-usrp --enable-omnithread
\end{lstlisting}

This sets up the install to only build resources for the USRP which OSSIE requires.
Compile the source code by entering the command:

\begin{lstlisting}[]
 $ make
\end{lstlisting}

Verify that the compile worked by running a check:

\begin{lstlisting}[]
 $ make check
\end{lstlisting}

Install the portions of GNU Radio by running the following command as root:

\begin{lstlisting}[]
 # make install
\end{lstlisting}  

The libraries installed by GNU Radio need to be linked:

\begin{lstlisting}[]
 # /sbin/ldconfig
\end{lstlisting}

At this point, GNU Radio and its dependencies have been installed. Now setup the
proper permissions for the USRP. As root, create a group which will have access
to the USRP:

\begin{lstlisting}[]
 # /usr/sbin/groupadd usrp
\end{lstlisting}

Add users to the group which need access to the USRP:

\begin{lstlisting}[]
 # /usr/sbin/usermod -G usrp -a USERNAME
\end{lstlisting}

Now that users will have access to the USRP, read and write access to the device
must be created. As root, open the file {\tt /etc/udev/rules.d/10-usrp.rules} in
a text editor:

\begin{lstlisting}[]
 # vim /etc/udev/rules.d/10-usrp.rules
\end{lstlisting}

Add the following text to the file:

\begin{lstlisting}[]
 ACTION=="add", BUS=="usb", SYSFS{idVendor}=="fffe", \
 SYSFS{idProduct}=="0002", GROUP:="usrp", MODE:="0660"
\end{lstlisting}

The text above is displayed on two lines due to the contraints on page size, however
the text must appear on a single line, without the backslash, in the file for the
access to the USRP to work properly. You may also add the following comment lines to
the file for future reference:

\begin{lstlisting}[]
 # rule to grant read/write access on USRP to group named usrp.
 # to use, install this file in /etc/udev/rules.d/ as
 # 10-usrp.rules
\end{lstlisting}

The USRP interface has now been created. As an optional test, connect the USRP
to the computer and run the following command:

\begin{lstlisting}[]
 $ ls -lR /dev/bus/usb
\end{lstlisting}

The users root and usrp should now be listed under the user groups.

\subsubsection{Install OSSIE}
\label{section:installation:source:ossiecf}
You are now ready to build and install OSSIE.  At this point, you can either compile and install
everything by hand using the included Makefiles, or use the {\tt build.py} convenience script to
do it for you.  Note that installing by hand requires some knowledge of OSSIE, Linux, and software development.

Download the latest tarball from
\href{http://ossie.wireless.vt.edu/download/tarballs/0.7.0/}{http://ossie.wireless.vt.edu/download/tarballs/0.7.0/}
\\ and unpack {\tt ossie-0.7.0.tar.bz2}.
\begin{lstlisting}[]
 $ wget http://ossie.wireless.vt.edu/download/tarballs/0.7.0/ \ 
   ossie-0.7.0.tar.bz2
 $ tar -xvjf ossie-0.7.0.tar.bz2
\end{lstlisting}

If you want to install everything by hand, do so, and then move on to Section~\ref{section:installation:source:ossiecf:ldconfig}.

If you would rather use the script, follow the steps below.

\subsubsection{Using Installation Scripts}
\label{section:installation:source:ossiecf:buildpy}

The included {\tt build.py} and {\tt setup.py} scripts automate the building and installation of
the OSSIE packages. Because OSSIE is built as a set of dependent libraries it is
necessary to build and install each one separately so that
they can link properly. These scripts take care of that for you.

In order for the script to run uninterrupted, the {\tt sudo} command must be
able to execute {\tt make install}.
As root, edit the {\tt sudoers} file\footnote{By default the sudoers file must
be edited with the {\tt visudo} command}
\begin{lstlisting}[]
 # /usr/sbin/visudo
\end{lstlisting}

At the end of the file, add the following line:
\begin{lstlisting}[]
 ALL ALL = NOPASSWD: /usr/bin/make install
\end{lstlisting}

Save and quit ({\tt :wq}).  If you made an error, visudo will tell you. We
recommend that you comment this line out by putting a pound character (`\#') in
front of it once you have finished installing OSSIE.
%TODO: Have a more secure (wheel group only?) method

By default, the installation directory of the OSSIE platform is {\tt /sdr}.  In
order to install new source code and binaries into this directory
without root permissions, you need to create and change the ownership of {\tt
/sdr}.
\begin{lstlisting}[]
 # mkdir /sdr
 # chown -R username.username /sdr
\end{lstlisting}
where {\tt username} is your user name.

The {\tt setup.py} script installs the tools used for component and waveform development. To install the tools, move into the {\tt tools} directory and run the {\tt setup.py} script as root:

\begin{lstlisting}[]
 $ cd tools
 # python setup.py install
\end{lstlisting}

The {\tt build.py} script installs the core framework, components, devices and a few demonstration waveforms. This script should not be run as root. 
To install, first exit out of root, then move into the directory where the OSSIE 0.7.0 tarball has been unpacked and run the script:

\begin{lstlisting}[]
 # exit
 $ cd /home/username/path_to_ossie/
 $ python build.py
\end{lstlisting}

Depending on the speed of your system this might take several minutes. You may
be asked for a password during the first {\tt make install} command. Because we
are using {\tt sudo}, this prompt is asking for your user password, not the
root password. If successful, the prompt should say:
\begin{lstlisting}[]
*********************************************************

  Complete installation of OSSIE 0.7.0 finished!

*********************************************************
\end{lstlisting}

\subsubsection{Updating System Libraries}
\label{section:installation:source:ossiecf:ldconfig}
Once the OSSIE libraries are installed, they need to be linked.
As root edit the file {\tt /etc/ld.so.conf}, adding the line
\begin{lstlisting}[]
 /usr/local/lib
\end{lstlisting}
Now run:
\begin{lstlisting}[]
 # /sbin/ldconfig
\end{lstlisting}

OSSIE should now be successfully installed on your system. You can skip to
Section~\ref{section:runningwaveforms} to learn how to run waveforms.

\subsection{Installation of OSSIE Eclipse Feature}
\label{section:installation:oefinstall}
Installation of the OSSIE Eclipse Feature (OEF) requires the installation of OSSIE, Java, and Eclipse.

\subsubsection{Installing Java}
\label{section:installation:javainstall}
Eclipse is written in Java, so you must have it installed to run Eclipse and OEF. 
We recommend using Sun's Java Development Kit. As of this writing, the GNU Compiler for Java (GCJ) will not work. 

Fedora Core 9 comes with the Sun JDK pre-installed but older versions require manual installation. On other distributions it is advisable to use the 
package manager to manage the installation, if possible.

\subsubsection{Installing Java on Older Versions of Fedora}
\label{section:installation:javafedora}
Go to \href{http://java.sun.com/javase/downloads/index.jsp}{http://java.sun.com/javase/downloads/index.jsp} 
and click Download next to JDK 6 Update 6. Choose Linux in the platform drop down menu, click the check-box 
agreeing to the license agreement, and click continue. Download the Linux rpm in self extracting file, 
{\tt jdk-6u6-linux-i586-rpm.bin}.

Open a terminal and navigate to the file. As root, execute the following command:
\begin{lstlisting}[]
 # sh jdk-u6-linux-i586-rpm.bin
\end{lstlisting}

Create {\tt java.sh} in {\tt /etc/profile.d/} with the following contents:
\begin{lstlisting}[]
 export JAVA_HOME="/usr/java/latest"
 export JAVA_PATH="$JAVA_HOME"
 export PATH="$PATH:$JAVA_HOME/bin"
\end{lstlisting}

Log out and back in to allow the changes to update. 

\subsubsection{Installing Java on Ubuntu}
\label{section:installation:javaubuntu}
In a terminal, enter the following lines:
\begin{lstlisting}[]
 $ sudo apt-get update
 $ sudo apt-get install sun-java5-jdk 
\end{lstlisting}

\subsubsection{Installing Eclipse}
\label{section:installation:eclipseinstall}
Install the Eclipse IDE for Java Developers. Go to the \href{http://www.eclipse.org/downloads/}{Eclipse Download Center} and download an Eclipse distribution for your platform.

Eclipse is distributed as a tarball archive that you can unpack to location of your choice. Pick a location that is appropriate for your platform and 
simply unpack the contents. There is no self-installer, just unpack the distribution. Do not install Eclipse in a directory that has spaces anywhere 
in its full path name.

\subsubsection{Installing OEF}
\label{section:installation:oefinstall}
Now that the dependencies have been installed, OEF can be installed.

Move into the unpacked eclipse directory, and start eclipse:
\begin{lstlisting}[]
$ cd /path/to/eclipse
$ ./eclipse
\end{lstlisting}

After Eclipse starts, on the toolbar select {\tt Help}, {\tt Software Updates}.
In the new window, select the ``Available Software" tab and click the ``Add Site"
button the right hand side. Enter the URL: {\tt http://ossie.wireless.vt.edu/eclipse/}
and select OK. The window will then add the URL, OSSIE, OSSIE Waveform Developer
Feature to the list of software to update. Place a check in the box next to OSSIE
Waveform Developer Feature and click Install. Eclipse will bring up a window which will
resolve any dependencies and then start the install guide.

When the install window opens, make sure OSSIE Waveform Developer Feature is selected
and click Next. Accept the GNU license agreement and select Next. Eclipse will then
begin to download the necessary files, which may take a few minutes. Allow Eclipse to
restart when it prompts to do so. After it restarts, the OSSIE Eclipse Feature will be
installed.

Select the OSSIE perspective within Eclipse. On the toolbar, select {\tt Window}, 
{\tt Open Perspective}, {\tt Other}. In the new window, select OSSIE which will then
open the OSSIE perspective. On the toolbar, select {\tt File}, {\tt New}, {\tt OSSIE Waveform},
or {\tt OSSIE Component} to start developing.

These same instructions used for installing OEF can be used later to update it to newer versions. 

\subsection{Using a VMware Image on Any Platform}
\label{section:installation:vmware}
A VMware image of a complete Fedora Core 9-based Linux system with all necessary
dependencies and a complete install of OSSIE 0.7.0 is available at \\
\href{http://ossie.wireless.vt.edu/trac/wiki/Downloads}{http://ossie.wireless.vt.edu/trac/wiki/Downloads}. 
All that is needed to run the virtual image is the VM­Ware Player, available
for no fee from \\
\href{http://www.vmware.com/download/player/}{http://www.vmware.com/download/player/}.
Versions of the player are available for both Windows and Linux.

Install VMware Player on your system, unzip the virtual image and open it.
For full instructions on installing and using VMware player, please
consult the VMWare Player User Guide~\cite{vmware:web}.

It is recommended that you keep a copy of the zipped virtual image so that you do
not need to download the image a second time to start with a fresh copy. Changes
that you make from within the image will alter it, and in the event of drastic
unwanted changes, starting afresh is easy if you have an extra copy of the image
on your hard drive.

% \subsection{Via Ebuild on Gentoo Linux}
% Support for installation via Gentoo's Portage package management system has not
% yet been thoroughly tested but ebuilds do exist.
% 
% To access the ebuilds, install and configure layman if you haven't already:
% \begin{figure}
% \begin{lstlisting}[]
% # emerge layman
% # echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf
% \end{lstlisting}
% \end{figure}
% 
% Then, add ossie-overlay to your locally-stored overlays:
% \begin{figure}
% \begin{lstlisting}[]
% # layman -a -o https://ossie.wireless.vt.edu/repos/ossie/experimental/scripts/gentoo/ossie-overlay.xml
% \end{lstlisting}
% \end{figure}
% 
% You can then proceed with installing OSSIE:
% \begin{figure}
% \begin{lstlisting}[]
% # emerge -av ossie
% \end{lstlisting}
% \end{figure}
% 
% After sucessful compiliation of the OSSIE framework and its dependencies, skip
% to section X.

%\subsection{Embedded Platforms}
%While installation on embedded platforms is not officially supported in the
%0.6.2 release, work has been done (MENTION WORK) on porting OSSIE to embedded
%platforms and we are interested in promoting more work in this area.