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

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

\newpage
\section{Installation}
\label{section:installation}
Installing OSSIE on Fedora 9 via the supplied build script is the recommend
method of installing and running OSSIE on your native Linux system. Running OSSIE on Ubuntu 8.04 as well as Linux
in a virtual VMware image as described in the Quick Start Guide
(Section~\ref{section:quickstartguide}) is also officially supported. Although we
do not yet provide and support installation packages for more Linux
distributions, compiling OSSIE from source on them should be possible. Compiling
from source in general has some advantages over using the VMware image, such as
saving disk space and download time and not needing the resources necessary to
run two operating systems concurrently. Additionally, you may install OSSIE via Fedora's 
'yum' package manager. The use of 'yum' is preferred if you are an OSSIE application developer. 
If you would like to commit changes to the OSSIE framework or tool suite, then you should 
install from source as described below.

\subsection{Installing OSSIE via YUM}
\label{section:installation:yum}
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.
\begin{lstlisting}[]
# su -
# vim /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 install OSSIE via yum by typing:
\begin{lstlisting}[]
# yum install ossie
# exit
\end{lstlisting}

\subsection{Notes on Linux Installation}
\label{section:installation:notesonlinux}
This section on installation 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 \$}.
Additionally this guide assumes that the target system has basic development
tools necessary for compiling source code. If you did not install Fedora Core 9
with the software development option checked, please refer
to Appendix~\ref{appendix:develpackages} for the list of packages you will need
to install. Due to the differences between the Fedora and Ubuntu platforms, the dependency installation methods will be different. The Fedora instructions are listed first and use {\tt yum}, while Ubuntu is listed second and uses {\tt aptitude}.

\subsection{Fedora 9 Dependencies}
\label{section:installation:fedorainstallation}

\subsubsection{Notes on Dependencies}
\label{section:installation:dependencies}
The first step in installing OSSIE is to install the dependencies.
Under Fedora Core 9, the dependencies can be installed via {\tt yum}. 

\subsubsection{Xerces}
\label{section:installation:dependencies:xerces}
Xerces is a C++ XML parser.  The OSSIE framework uses this package to interpret
the XML files that define resources and waveforms, among other things.
\begin{lstlisting}[]
# yum install xerces-c-devel
\end{lstlisting}
You will be prompted to answer some questions.  Answer {\tt yes (y)} to proceed.

\subsubsection{omniORB}
\label{section:installation:dependencies:omniorb}
omniORB handles most of the CORBA implementation for your system.  See alternative instructions below if the following does not work.

%TODO: describe CORBA
\begin{lstlisting}[]
 # rpmbuild --rebuild \
    http://www.fourpalms.org/pub/omniORB/SRPMS/omniORB-4.1.0-1.src.rpm
 # cd /usr/src/redhat/RPMS/i386
 # rpm -Uhv omniORB-4.1.0-1.i386.rpm
 # rpm -Uhv omniORB-devel-4.1.0-1.i386.rpm
 # rpm -Uhv omniORB-utils-4.1.0-1.i386.rpm
 # rpm -Uhv omniORB-servers-4.1.0-1.i386.rpm
 # rpm -Uhv omniORB-bootscripts-4.1.0-1.i386.rpm
\end{lstlisting}

If you are unable to download the file from fourpalms.org, try using:

\begin{lstlisting}[]
 # rpmbuild --rebuild \
    http://opensource.nederland.net/omniORB/downloads/4.1.0/SRPMS/omniORB-4.1.0-1.src.rpm
\end{lstlisting}

and then continue as above.

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}}

\subsubsection{omniORBpy}
\label{section:installation:dependencies:omniorbpy}
The omniORBpy package provides a Python interface for omniORB.  It is used for
both the Python tools (OWD, ALF, wavLoader.py) and Python components.
\begin{lstlisting}[]
 # rpmbuild --rebuild \
     http://www.fourpalms.org/pub/omniORB/SRPMS/omniORBpy-3.0-1.src.rpm
 # cd /usr/src/redhat/RPMS/i386
 # rpm -Uhv omniORBpy-3.0-1.i386.rpm
 # rpm -Uhv --force omniORBpy-standard-3.0-1.i386.rpm
 # rpm -Uhv omniORBpy-devel-3.0-1.i386.rpm
\end{lstlisting}

\subsubsection{wxPython}
\label{section:installation:dependencies:wxpython}
wxPython is a Python interface for the wxWidgets graphical user interface
library. The graphical Python tools, as well as many graphical Python
components, utilize the wxPython package to create their graphical user interfaces.
\begin{lstlisting}[]
 # yum install wxPython-devel
\end{lstlisting}

\subsubsection{numpy}
\label{section:installation:dependencies:numpy}
numpy is a Python numerical library that the tools use.  It is only
necessary for running the tools.
\begin{lstlisting}[]
 # yum install numpy
\end{lstlisting}

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

\subsection{Ubuntu 8.04 Dependencies}
\label{section:installation:ubuntuinstallation}

\subsubsection{Dependencies Setup}
\label{section:installation:ubuntudependencies}
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 adminstrator 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}

\subsubsection{Install Dependencies}
\label{section:installation:installubuntudependencies}

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

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 subversion \
guile-1.8 libqt3-mt-dev swig libboost-filesystem-dev
\end{lstlisting}
This is the entire dependency list, so some of these packages may already be installed by default.

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

\subsection{OSSIE Core Framework}
\label{section:installation:ossiecf}
OSSIE 0.7.0 is packaged with a convenient Python script to automatically
configure and build the packages necessary for the framework, tools, and other
libraries.
Before running the script, however, it is necessary to perform a few
preliminary steps.

\subsubsection{Allowing Root Access for {\tt make install} with {\tt sudo}}
\label{section:installation:ossiecf:sudoers}
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

\subsubsection{Creating {\tt /sdr}}
\label{section:installation:ossiecf:sdr}
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.

\subsubsection{Running {\tt build.py}}
\label{section:installation:ossiecf:buildpy}
The included {\tt build.py} script automates 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. This script takes care of that for you.

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}
%
To run the installation script, navigate to the {\tt ossie-0.7.0} directory and
run {\tt build.py}:
\begin{lstlisting}[]
 $ cd ossie-0.7.0/
 $ 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{Linking the Libraries with {\tt /sbin/ldconfig}}
\label{section:installation: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 intallation of OSSIE, Java, and Eclipse.

\subsubsection{Installing Java}
\label{section:installation:javainstall}
If installing OEF on Fedora 9, this step can be skipped as Java is already installed. However on other platforms this step may need to be performed.

Eclipse is written in Java, so you must have it installed to run Eclipse and OEF. Install the full Java Software Development Kit (SDK) for best results. The GNU gcc implementation of Java, gcj, will not work and therefore Sun's JDK must be used instead. To install, go to the \href{http://java.sun.com/javase/downloads/index.jsp}{Java SE download page} and download the latest JDK update that is available. Do not download the NetBeans IDE bundle or the JRE distribution.

On the next page, check the radio button to agree to the license terms and choose either the RPM or the standard self-extracting executable. Execute the installer file you downloaded to install the Java SE JDK. If you downloaded the RPM version, the file will expand into several RPM files. Use your package manager to install them next.

Confirm that the installation is in place. From the command line, enter:
\begin{lstlisting}[]
$ java -version
\end{lstlisting}
If java is not found, the version number is different than the one that was downloaded, or if the response indicates that gcj is being used, then the {\tt .bashrc} file needs to be updated. Locate the where the Sun Java distribution has been installed:
\begin{lstlisting}[]
$ ls /usr/lib | grep java
\end{lstlisting}
Open the {\tt .bashrc} file and add the path to it. 
\begin{lstlisting}[]
$ vim /home/username/.bashrc 
\end{lstlisting}
For example, add {\tt /usr/lib/java-1.7.0/} to the end of the file:
\begin{lstlisting}[]
export PATH=$PATH:/usr/lib/java-1.7.0/
\end{lstlisting}

Within the same terminal, update the PATH variable:
\begin{lstlisting}[]
$ . ~/.bashrc
\end{lstlisting}

Java is now installed.

\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 tar file that you install in a location of your choice. Pick a location that is appropriate for your platform and simply unpack the contents. There is no self-installer, just untar 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 Help : Software Updates : Find and Install. Choose "Search for new features to install" and click Next. Add a new entry by selecting "New Remote Site". Enter "OSSIE" as the name and {\tt http://ossie.wireless.vt.edu/eclipse/} as the URL, and select OK. Make sure there is a check next to OSSIE in the window, and select Finish.

Eclipse will then display the OSSIE feature. Select the check mark next to the name and select Next. Accept the GNU license agreement and select Next. Then select Finish to install the feature. Select Install All when prompted to install the unsigned feature. Allow eclipse to restart so the changes take effect.

Now that OEF has been installed, select the OSSIE perspective within Eclipse. On the toolbar, select Window : Open Perspective : Other. In the new window, select OSSIE which will then open the OSSIE perspective. On the toolbar, select File : New : OSSIE Waveform, or 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}
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.