root/ossiedev/branches/mcarrick/user-guide-0.8.3/Installation.tex @ 11003

Revision 11003, 15.7 KB (checked in by mcarrick, 2 years ago)

adding additional dependency

Line 
1% ------------------------------------------------------------------
2%
3%   TITLE: OSSIE 0.8.3 Installation Guide
4% AUTHORS: Mike Ekoniak, Matt Carrick, Drew Cormier, Christopher Covington,
5%          Carl B. Dietrich, Joseph Gaeddert, Benjamin Hilburn,
6%          C. Ian Phelps, Shereef Sayed, Jason Snyder, Haris Volos
7% CREATED:
8% REVISED:
9% 23Mar11 IB Minor typo fixes.
10%     URL: http://ossie.wireless.vt.edu/
11%
12% ------------------------------------------------------------------
13
14\newpage
15\section{Installation}
16\label{section:installation}
17For users that do not have access to a Linux system, or are unfamiliar with Linux, we recommend
18that you use our pre-built VMWare images.  These images have OSSIE pre-installed on them, and are
19ready to use out-of-the-box. Using an OSSIE VMware image is described in
20Section~\ref{section:installation:vmware}.
21
22Although we do not yet provide and support binary installation packages for more Linux
23distributions, compiling OSSIE from source on them should be possible.
24
25To install OSSIE from source, follow the below instructions to install the OSSIE dependencies,
26and then compile and install the source code.
27
28\subsection{Installing OSSIE from Source}
29\label{section:installation:source}
30
31This section assumes that the user is familiar with basic
32Linux commands such as {\tt cd} and {\tt ls} and has sudo
33access or root access.
34
35If you have an older version of OSSIE installed, then you will need to delete the contents of {\tt /sdr/}.
36\begin{lstlisting}[]
37 $ rm -rf /sdr/*
38\end{lstlisting}
39
40Ubuntu is the main supported operating system for OSSIE, and Ubuntu 11.04, 10.10 and 10.04 all
41have a different list of dependencies that must be installed. After following the instructions
42for your respective operating system, jump to
43Section~\ref{section:installation:source:dependencies:configomni} to continue the install.
44
45\subsubsection{Installing Dependencies on Ubuntu 11.04}
46Install all of the following packages:
47
48\begin{lstlisting}[]
49$ sudo aptitude install -y autoconf subversion omniorb4 python-omniorb \
50libomniorb4-dev omniidl-python omniorb-nameserver libboost-all-dev \
51python-wxtools omniorb-idl python-profiler python-numpy
52\end{lstlisting}
53
54\subsubsection{Installing Dependencies on Ubuntu 10.10}
55A few of the dependencies changed with Ubuntu 10.10, specifically omniidl4-python is now omniid-python, and python-omniorb2 is now python-omniorb. The updated dependency list is below.
56\begin{lstlisting}[]
57$ sudo aptitude install gcc build-essential
58$ sudo aptitude -y install omniorb4 libomniorb4-dev omniidl-python \
59omniorb4-nameserver python-omniorb libgtk2.0-dev freeglut3-dev \
60python-wxgtk2.8 python-wxversion python-wxtools python-numpy \
61python-numpy-ext python-numpy-dev python-profiler g++ automake \
62libtool subversion python-dev fftw3-dev libcppunit-dev libboost-dev \
63sdcc libusb-dev libasound2-dev libsdl1.2-dev guile-1.8 libqt3-mt-dev \
64swig python-profiler automake1.9 python2.6-dev sdcc-libraries \
65guile-1.8-dev libqt4-dev ccache python-opengl libgsl0-dev python-lxml \
66doxygen qt4-dev-tools libqwt5-qt4-dev libqwtplot3d-qt4-dev \
67libboost-filesystem-dev libboost-system-dev libboost-thread-dev \
68libboost-program-options-dev
69\end{lstlisting}
70
71\subsubsection{Installing Dependencies on Ubuntu 10.04}
72\label{section:installation:dependencies:ubuntu}
73
74This is the entire dependency list, so some of these packages may already be installed.
75Install all of the following packages:
76\begin{lstlisting}[]
77$ sudo aptitude install gcc build-essential
78$ sudo aptitude -y install omniorb4 libomniorb4-dev omniidl4-python \
79omniorb4-nameserver python-omniorb2 libgtk2.0-dev freeglut3-dev \
80python-wxgtk2.8 python-wxversion python-wxtools python-numpy \
81python-numpy-ext python-numpy-dev python-profiler g++ automake \
82libtool subversion python-dev fftw3-dev libcppunit-dev libboost-dev \
83sdcc libusb-dev libasound2-dev libsdl1.2-dev guile-1.8 libqt3-mt-dev \
84swig python-profiler automake1.9 python2.6-dev sdcc-libraries \
85guile-1.8-dev libqt4-dev ccache python-opengl libgsl0-dev python-lxml \
86doxygen qt4-dev-tools libqwt5-qt4-dev libqwtplot3d-qt4-dev \
87libboost-filesystem-dev libboost-system-dev libboost-thread-dev \
88libboost-program-options-dev
89\end{lstlisting}
90
91
92\subsubsection{Configure omniORB}
93\label{section:installation:source:dependencies:configomni}
94All of the dependencies have been installed and one of the dependencies,
95omniORB, needs to be configured. This configuration is done through the
96modification of a file, either {\tt /etc/omniORB.cfg} or
97{\tt /etc/omniORB4.cfg}, depending on the version of the omniORB dependency.
98
99Open the file as root, and search for the following line:
100\begin{lstlisting}[]
101 InitRef = NameService=corbaname::my.host.name
102\end{lstlisting}
103Uncomment the line by deleting the pound or hash character `\#' and change
104it to:
105\begin{lstlisting}[]
106 InitRef = NameService=corbaname::127.0.0.1
107\end{lstlisting}
108Before running the framework you will need to start the naming service. If you
109installed omniORB from source, you have to follow the instructions in
110Appendix~\ref{appendix:omninamessh}. When installing from yum
111{\tt omniNames} will automatically start when you restart your machine. Refer
112to Appendix~\ref{appendix:services} for instructions on how to start the
113omniNames service without restarting your machine or set whether the service
114starts automatically at boot.
115\footnote{You may also manually start a source-compiled tarball package of
116omniNames {\tt omniNames} with the script described in
117Appendix~\ref{appendix:omninamessh}}
118
119At this time it is a good idea to restart your machine.
120
121\subsubsection{Installing Portions of GNU Radio}
122\label{section:installation:source:dependencies:gnuradio}
123OSSIE uses a small subset of GNU Radio to communicate with and configure the USRP. The
124following steps will walk through installing portions of GNU Radio 3.3.0.
125
126Install GNURadio's dependencies:
127\begin{lstlisting}[]
128 $ sudo apt-get install -y swig sdcc libusb-dev libfftw3-dev \
129libcppunit-dev libbz2-dev guile-1.8-dev
130\end{lstlisting}
131
132To install GNURadio 3.3.0 from source:
133\begin{lstlisting}[]
134 $ wget ftp://ftp.gnu.org/gnu/gnuradio/gnuradio-3.3.0.tar.gz
135 $ tar -xvf gnuradio-3.3.0.tar.gz
136 $ cd gnuradio-3.3.0/
137 $ ./configure
138 $ make
139 $ sudo make install
140\end{lstlisting}
141
142At this point, GNU Radio and its dependencies have been installed. Now setup the
143proper permissions for the USRP. As root, create a group which will have access
144to the USRP:
145
146\begin{lstlisting}[]
147 $ sudo /usr/sbin/groupadd usrp
148\end{lstlisting}
149
150Add users to the group which need access to the USRP:
151
152\begin{lstlisting}[]
153 $ sudo /usr/sbin/usermod -G usrp -a USERNAME
154\end{lstlisting}
155
156Now that users will have access to the USRP, read and write access to the device
157must be created. As root, create the file {\tt /etc/udev/rules.d/10-usrp.rules} in
158a text editor:
159
160\begin{lstlisting}[]
161 $ sudo gedit /etc/udev/rules.d/10-usrp.rules
162\end{lstlisting}
163
164Add the following text to the file:
165
166\begin{lstlisting}[]
167 ACTION=="add", BUS=="usb", SYSFS{idVendor}=="fffe", \
168 SYSFS{idProduct}=="0002", GROUP:="usrp", MODE:="0660"
169\end{lstlisting}
170
171The text above is displayed on two lines due to the contraints on page size, however
172the text must appear on a single line, without the backslash, in the file for the
173access to the USRP to work properly. You may also add the following comment lines to
174the file for future reference:
175
176\begin{lstlisting}[]
177 # rule to grant read/write access on USRP to group named usrp.
178 # to use, install this file in /etc/udev/rules.d/ as
179 # 10-usrp.rules
180\end{lstlisting}
181
182The USRP interface has now been created. As an optional test, connect the USRP
183to the computer and run the following command:
184
185\begin{lstlisting}[]
186 $ ls -lR /dev/bus/usb
187\end{lstlisting}
188
189The users root and usrp should now be listed under the user groups.
190
191If you are using the USRP2, it is necessary to have a gigabit ethernet interface and
192intruct the kernel to allow raw socket access to the ethernet port:
193\begin{lstlisting}[]
194 $ sudo chmod u+s /usr/local/bin/usrp2_socket_opener
195\end{lstlisting}
196
197This step is necessary every time you reinstall GNU Radio.
198
199
200\subsubsection{Install OSSIE}
201\label{section:installation:source:ossiecf}
202You are now ready to build and install OSSIE. 
203Note that installing by hand requires some knowledge of OSSIE, Linux, and software development.
204
205Download the latest tarball from
206\href{http://ossie.wireless.vt.edu/download/tarballs/\ossieversion/}{http://ossie.wireless.vt.edu/download/tarballs/\ossieversion/}
207\\ and unpack {\tt ossie-\ossieversion.tar.gz}.
208\begin{lstlisting}[]
209 $ wget http://ossie.wireless.vt.edu/download/tarballs/0.8.3/ \
210   ossie-0.8.3.tar.gz
211 $ tar -xvf ossie-0.8.3.tar.gz
212\end{lstlisting}
213
214By default, the installation directory of the OSSIE platform is {\tt /sdr}. In order to install new
215source code and binaries into this directory without root permissions, you need to create and change
216the ownership of {\tt /sdr}.
217\begin{lstlisting}[]
218 $ sudo mkdir /sdr
219 $ sudo chown -R username.username /sdr
220\end{lstlisting}
221where {\tt username} is your user name.
222
223\subsubsection{Using Autoconf}
224\label{section:installation:source:ossiecf:autoconf}
225
226\begin{lstlisting}[]
227 $ cd ossie-0.8.3
228 $ ./configure --prefix=/sdr --libdir=/usr/local/lib/ \
229   --includedir=/usr/local/include/ --with-boost --with-boost-filesystem
230 $ make
231 $ sudo make install
232\end{lstlisting}
233
234If successful, the prompt should say:
235\begin{lstlisting}[]
236*********************************************************
237
238  Complete installation of OSSIE 0.8.3 finished!
239
240*********************************************************
241\end{lstlisting}
242
243If you prefer, or require, a different root directory, then change the '--prefix' flag to your appropriate absolute path.
244If you require the OSSIE libraries to be installed to a different location, then change the '--libdir' flag to your appropriate absolute path.
245For further 'configure' options, use {\tt configure --help}.
246
247If configure fails, use {\tt aptitude search <dependency name>} to find any missing packages.
248
249\subsubsection{Updating System Libraries}
250\label{section:installation:source:ossiecf:ldconfig}
251Once the OSSIE libraries are installed, they need to be linked.
252As root edit the file {\tt /etc/ld.so.conf}, adding the line
253\begin{lstlisting}[]
254 /usr/local/lib
255\end{lstlisting}
256Now run:
257\begin{lstlisting}[]
258 $ sudo /sbin/ldconfig
259\end{lstlisting}
260
261OSSIE should now be successfully installed on your system. You can skip to
262Section~\ref{section:runningwaveforms} to learn how to run waveforms.
263
264\subsection{Installation of OSSIE Eclipse Feature}
265\label{section:installation:alloefinstall}
266Installation of the OSSIE Eclipse Feature (OEF) requires the installation of OSSIE, Java, and Eclipse.
267
268\subsubsection{Installing Java}
269\label{section:installation:javainstall}
270Eclipse is written in Java, so you must have it installed to run Eclipse and OEF.
271We recommend using Sun's Java Development Kit. As of this writing, the GNU Compiler for Java (GCJ) will not work.
272
273\subsubsection{Installing Java on Ubuntu}
274\label{section:installation:javaubuntu}
275
276Open /etc/apt/sources.list in an editor and add the following lines to the end of the file:
277\begin{lstlisting}[]
278 deb http://archive.canonical.com/ubuntu lucid partner
279 deb-src http://archive.canonical.com/ubuntu lucid partner
280\end{lstlisting}
281
282In a terminal, enter the following lines:
283\begin{lstlisting}[]
284 $ sudo apt-get update
285 $ sudo apt-get install sun-java6-jdk
286\end{lstlisting}
287
288\subsubsection{Installing Eclipse}
289\label{section:installation:eclipseinstall}
290Install 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.
291
292Eclipse 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
293simply unpack the contents. There is no self-installer, just unpack the distribution. Do not install Eclipse in a directory that has spaces anywhere
294in its full path name.
295
296\subsubsection{Installing OEF}
297\label{section:installation:oefinstall}
298Now that the dependencies have been installed, OEF can be installed.
299
300Move into the unpacked eclipse directory, and start eclipse:
301\begin{lstlisting}[]
302$ cd /path/to/eclipse
303$ ./eclipse
304\end{lstlisting}
305
306After Eclipse starts, on the toolbar select {\tt Help}, {\tt Install New Software}.
307In the new window, select the ``Work with'' textbox and enter the URL: {\tt http://ossie.wireless.vt.edu/eclipse/}
308and select Add. Give a name, e.g., ``OEF''.
309
310The window will then add the URL, OSSIE, OSSIE Waveform Developer
311Feature to the list of available software. Place a check in the box next to OSSIE
312Waveform Developer Feature and click Next. Eclipse will show a window with more details, select Finish to complete the installation process.
313
314%Eclipse will bring up a window which will
315%resolve any dependencies and then start the install guide.
316
317%When the install window opens, make sure OSSIE Waveform Developer Feature is selected and click Next.
318
319%Accept the GNU license agreement and select Next. Eclipse will then begin to download the necessary files, which may take a few minutes.
320Allow Eclipse to restart when it prompts to do so. After it restarts, the OSSIE Eclipse Feature will be installed.
321
322Select the OSSIE perspective within Eclipse. On the toolbar, select {\tt Window},
323{\tt Open Perspective}, {\tt Other}. In the new window, select OSSIE which will then
324open the OSSIE perspective. On the toolbar, select {\tt File}, {\tt New}, {\tt OSSIE Waveform},
325or {\tt OSSIE Component} to start developing.
326
327These same instructions used for installing OEF can be used later to update it to newer versions.
328
329\subsection{Using a VMware Image on Any Platform}
330\label{section:installation:vmware}
331A VMware image of OSSIE \ossieversion\ pre-installed on a Linux operating system is available at \\
332\href{http://ossie.wireless.vt.edu/trac/wiki/Downloads}{http://ossie.wireless.vt.edu/trac/wiki/Downloads}.
333All that is needed to run the virtual image is the VM­Ware Player, available
334for free from \href{http://www.vmware.com/download/player/}{http://www.vmware.com/download/player/}.
335Versions of the player are available for both Windows and Linux.
336
337Install VMware Player on your system, unzip the virtual image and open it.
338For full instructions on installing and using VMware player, please
339consult the VMWare Player User Guide~\cite{vmware:web}.
340
341It is recommended that you keep a copy of the zipped virtual image so that you do
342not need to download the image a second time to start with a fresh copy. Changes
343that you make from within the image will alter it, and in the event of drastic
344unwanted changes, starting afresh is easy if you have an extra copy of the image
345on your hard drive.
346
347% \subsection{Via Ebuild on Gentoo Linux}
348% Support for installation via Gentoo's Portage package management system has not
349% yet been thoroughly tested but ebuilds do exist.
350%
351% To access the ebuilds, install and configure layman if you haven't already:
352% \begin{figure}
353% \begin{lstlisting}[]
354% # emerge layman
355% # echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf
356% \end{lstlisting}
357% \end{figure}
358%
359% Then, add ossie-overlay to your locally-stored overlays:
360% \begin{figure}
361% \begin{lstlisting}[]
362% # layman -a -o https://ossie.wireless.vt.edu/repos/ossie/experimental/scripts/gentoo/ossie-overlay.xml
363% \end{lstlisting}
364% \end{figure}
365%
366% You can then proceed with installing OSSIE:
367% \begin{figure}
368% \begin{lstlisting}[]
369% # emerge -av ossie
370% \end{lstlisting}
371% \end{figure}
372%
373% After sucessful compiliation of the OSSIE framework and its dependencies, skip
374% to section X.
375
376%\subsection{Embedded Platforms}
377%While installation on embedded platforms is not officially supported in the
378%0.6.2 release, work has been done (MENTION WORK) on porting OSSIE to embedded
379%platforms and we are interested in promoting more work in this area.
380
381
Note: See TracBrowser for help on using the browser.