\documentclass[a4paper,10pt]{article} \usepackage{listings,color,epsfig,amsmath,url} \definecolor{codecolor}{rgb}{0.99,0.97,0.94} % color values Red, Green, Blue \definecolor{commentcolor}{rgb}{0.1,0.5,0.1} % color values Red, Green, Blue \definecolor{stringcolor}{rgb}{0.3,0.1,0.1} % color values Red, Green, Blue \newcommand{\Code}[1]{\texttt{#1} } \newcommand{\code}[1]{\Code{#1} } \newcommand{\DB} {\code{{MOOSDB}}} \newcommand{\MA} {\code{{MOOSApp}}} \newcommand{\Ignore}[1] {} \lstset{ frame = shadowbox, %language=[Visual]{c++}, rulesepcolor=\color{black}, basicstyle=\small } \lstset{ backgroundcolor=\color{codecolor}, keywordstyle=\color{blue}\bfseries, commentstyle=\color{commentcolor}, stringstyle=\color{stringcolor}\ttfamily, linewidth = 1.2\linewidth, breaklines=true} % \lstset{language=C++} % Title Page \title{Building and Linking Against MOOS} \author{Paul Newman} \begin{document} \maketitle \begin{center} \epsfig{file=images/moose6.eps,width = 0.2\linewidth} \end{center} \begin{abstract} This document will tell you how to build the MOOS project and how to link your own applications against the MOOS libraries. \end{abstract} \section{Introduction}\label{Sec:CompilingAndLinking} In this document, we'll cover how to compile and link your MOOS Applications. The simplest way to do this is by using CMake and adding your own source tree as a sibling of the ``Core'' directory under the MOOS -- this is described in detail in Section \ref{Sec:UsingCMake}. However you may not want to do this, preferring to handcraft your own Make files for each platform your application will be running on -- the information you will require to do this is described in Section \ref{Sec:RollYourOwn}. \subsection{Downloading the Source Tree} The \code{MOOS} can be downloaded from \url{http://www.robots.ox.ac.uk/~pnewman/TheMOOS} and also via \code{svn}\footnote{Directions on how to use svn to grab releases can be found on \url{http://www.robots.ox.ac.uk/~pnewman/TheMOOS}.}. All of the latest MOOS code is cross-platform. Built into the source tree is a cross-platform build system that relies on \code{CMake} -- a third-party executable available from {\it{www.cmake.org}} or the MOOS website. \section{The Source Tree Shape} \begin{figure}[ht!]\label{Fig:MOOSTree} \centering \epsfig{file = ./images/BuildTree.eps , width = 0.9\linewidth} \caption{The MOOS source tree (as downloaded)} \end{figure} Figure \ref{Fig:MOOSTree} shows the shape of the MOOS tree in release packages.\footnote{You obviously don't have to stick with this but it has some positives.} In this section we'll survey the contents of each directory. We shall not however describe in any detail what the contents of a directory does when built or how it may be used --- such details can be found elsewhere. \subsection{Core} The ``core'' directory contains code that has nothing per-se to do with robots. It is basically only concerned with the communications API. See the documentation on Programming with MOOS and the MOOSComms architecture for more detail. The minimal conceivable build would be these three projects: the two base MOOS libraries and the MOOSDB server that binds processes together. \subsection{Essentials} This directory also contains domain-neutral applications (i.e.not necessarily only useful for robotics projects) but they are things that tend to be used all the time by folk who have adopted MOOS. It is recommended that you invest time in learning how the processes work -- they'll save you a lot of time. \subsection{Tools} The tools subdirectory is again largely domain-independent, but contains, especially in the Graphical subdirectory, some decidedly useful applications. \subsubsection{Graphical} Projects in this directory have a dependency on the FLTK cross-platform toolkit. \code{uPlayback} is a lightweight tool which can playback into a MOOS community file created by \code{pLogger}.\code{uMS} is a fantastically useful tool for spying on a multitude of processes talking to each other using the MOOS Communications API. \subsubsection{Simulation} This directory contains simulations for ocean- and land-based vehicles. \subsection{Matlab} This directory builds a very useful project. It builds a mexglx or dll file (depending on your OS) which allows Matlab scripts to behave as if they were fully fledged MOOS-enabled processes. It's pretty useful if you want a quick visualisation of data or to prototype some code. To build this project you do need to have Matlab installed. \subsection{NavigationAndControl} The \code{NavigationAndControl} directory contains projects that are common in mobile robotics apps --- \code{pNav} \code{pHelm} and \code{iRemote}. The former two of these have a dependency on the \code{Newmat} numerical library which can be found in the \code{Thirdparty} directory. There is a case to put \code{iRemote} in the instruments subfolder as it interfaces to a ``human instrument'' -- but it seemed more robot-centric rather than sensor-based --- {\it{sub-judice}}. \subsection{Instruments} The instruments subtree is pretty obvious -- note that it includes \code{iMatlab} which is a peculiar instrument as it provides an interface to Matlab not a device or human. \subsection{Thirdparty} The Thirdparty directory contains code that for the most part is written by third-party authors. Newmat is a linear algebra package and FLTKVW is an extension to the FLTK functionality with a few MOOS-Graphics additions. \section{Cross-Platform Building using CMake}\label{Sec:UsingCMake} The use of \code{CMake} allows a code-author to describe in a high-level way what should be built in a project. The important point from this is that it allows (via ``meta-make'' files called \code{CMakeLists.txt} found in every directory) Make files to be written for Unix and Microsoft developer studio development alike. This is a massive win in terms of cross-platform development / project management. \footnote{Of course if one only develops for one OS it is hard to see the benefit.} By toggling the relevant fields in the ccmake curses-GUI you can turn on/off Makefile generation for different parts of the project. Pressing ``c'' to configure then parses the newly included CMakeLists.txt files and may present some new options for you to select. A basic build should work out-of-the-box simply by accepting the default values. But to be sure we'll now walk through the process step by step. \begin{enumerate} \item Download and install \code{CMake} for your platform (from \url{www.cmake.org or} the MOOS website). % \item ``cd'' into the MOOS root directory. % \item Type \code{ccmake ./} -- you should see something like Figure \ref{Fig:CMake1}. \begin{figure}[ht]\label{Fig:CMake1} \centering \epsfig{file = ./images/CMakeSteps/CMake1.eps , width = \linewidth} \caption{The initial CMake Screen - Win32 platforms have a gui-dialog rather than an ncurses interface} \end{figure} % \item Press ``c'' to configure -- the screen should look like something like Figure \ref{Fig:CMake2}. \begin{figure}[ht]\label{Fig:CMake2} \centering \epsfig{file = ./images/CMakeSteps/CMake2.eps , width = \linewidth} \caption{The initial CMake Screen after an initial configure -- note no option to generate Make files is present as yet. Build directories and build options (i.e. what to build and what not) can be selected at this stage. } \end{figure} * \item Press ``c'' to configure once more. The screen should now look something like Figure \ref{Fig:CMake3}. \begin{figure}[ht]\label{Fig:CMake3} \centering \epsfig{file = ./images/CMakeSteps/CMake3.eps , width = \linewidth} \caption{The final CMake Screen before generating the build files (``.dsp'' or Makefile --- depending on platform). Please note ``Configure'' may have been selected several times before this final option is presented. } \end{figure} % \item Notice an option ``g'' has appeared saying we are good to go....Press ``g'' to generate the MOOS make files. If you have followed the above steps CMake will exit and you'll see (along with one or two other CMake generated files) a master Makefile (or dsp/dsw/sln file for DevStudio builds) in the root directory. \item You are now ready to build the project. If you have selected an IDE build, (like Devstudio or KDevelop) load the relevant newly created project file into your idea and perform whatever steps are needed to build. In Figure \ref{Fig:CMake4} I've just typed ``make'' in a linux terminal. I went with all the default options and now just ``Core'' and ``Essential'' projects are being built. I have a warm fuzzy about this. \begin{figure}[ht]\label{Fig:CMake4} \centering \epsfig{file = ./images/CMakeSteps/CMake4.eps , width = \linewidth} \caption{CMake has made the project files (which for me today in this example is a Linux ``Makefile'') and exited. Having typed ``make'' the build proceeds. The executables will be placed in the \code{MOOSBin} directory. } \end{figure} \end{enumerate} Note that the Utils directory includes massively useful GUI applications which link against FLTK. You are expected to have the library and include files in your system path (this should have been done for you using the {\it{configure, make, make install}} paradigm when building the FLTK library) \subsection{Incorporating Private Subtrees}\label{Sec:PrivatCode} Entering a suitable directory or symbolic link in the \code{ALSO\_BUILD} field causes CMake to recurse into that directory when creating Make files. This way developers can include their own projects in the build paradigm. For example, the Oxford Mobile Robotics group has a directory called OXMOOS which lives in a directory in MOOS (just like Core or Utils does). Typing OXMOOS in the \code{ALSO\_BUILD} field causes CMake to recurse into the OXMOOS directory and follow the instructions in the CMakeLists.txt file therein (which causes it to recurse further down into each of our individual application projects). The advantage of this is that it inherits all the build flags and library settings of the parent MOOS project, and so things like the library paths (MOOSBin in the example above) are automatically passed to the compiler.\\ \subsection{Where are the Binaries?} By default binaries and libraries are placed in \code{\textit{root}/MOOSBin}. This of course can be changed simply by typing in your preferred destination during the build system set up using CMake.\footnote{Devstudio users will find the binaries in debug/release/releasewithdebug directories within MOOSBin depending on the active project configuration selected in the IDE.} See Figure \ref{Fig:CMake2}. \section{Living Without CMake}\label{Sec:RollYourOwn} Some MOOS users may not wish to use the CMake infrastructure (a CMakeLists.txt file in each directory) or tree provided in the releases -- preferring instead to use old trusted Make files they have written themselves for whatever platform they wish to develop/deploy on. This of course will work --- the source in no way depends upon the build system. If this is your preferred method, then you will need to know which include paths are required and what libraries must be linked against. \subsection{Include Paths} To compile an application that uses the MOOS Comms API you need to add the following include paths. \begin{center} \begin{description} \item \code{\textit{root}/Core/} \end{description} \end{center} Please note, header files are included relative to the \code{\textit{root}/Core} directory for example by using \verb!#include! \subsection{Library Paths} To link an application that uses the MOOS Comms API you need to add the following library paths \begin{description} \item \code{\textit{root}/MOOSBin} \footnote{Windows users -- note Devstudio further qualifies this path with ``Debug'' or ``Release'' etc subdirectories} \end{description} For historical reasons all binaries including libraries are placed in the \code{\textbf{MOOSBin}} directory \footnote{This is something that needs looking at with separate \code{lib} and \code{bin} directories being preferable and planned.}. You will also need to link against the libraries stated in Section \ref{Sec:Libs}. \subsection{Libraries to Link Against}\label{Sec:Libs} To build an application that uses the core MOOS libraries, you will need to link against the following libraries (listed by OS). \begin{center} % use packages: array \begin{tabular}{lll} \textbf{Windows} & \textbf{Linux} & \textbf{Solaris} \\ wsock32.lib & libm.a & libm.a \\ comctl32.lib & libpthread.a & libpthread.a \\ MOOS.lib & libMOOS.a & libsocket.a \\ MOOSGen.lib & libMOOSGen.a & libnsl.a \\ \textit{(console libs)} & × & libMOOS.a \\ × & × & libMOOSGen.a \end{tabular} \end{center} If you want to roll your own Make files for the graphical applications inside the MOOS tree, look at the \code{CMakeLists.txt} files in the top root directory and the individual application directories to see what additional libraries are required. \end{document}