\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
% Include common packages, environments, counters etc
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_lab_format}
\input{common_latex/common_latex_definitions}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

\begin{document}
\wikidoc{file=MCP.MOOSIvPExtend}
\wikidoc{auth=mikerb@mit.edu}
\helplevelsubsec


%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Extending MOOS-IvP with MOOS-IvP-Extend}
\vspace{0.1in}
\labdate{November, 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{footnotesize}
\end{labcover}

%===================================================================
% Add a blank page so first body page is on the right when doubleside
\blankpage


%===================================================================
\section{Overview and Objectives}
%===================================================================

In this lab we lay the groundwork for building our own MOOS
applications or helm behaviors. You have thus far worked with the
MOOS-IvP tree using the \var{moos-ivp} codebase from GitHub. In this
lab you will obtain a second tree, \var{moos-ivp-extend}, to be
downloaded alongside the first tree. You will make this second tree
your own. After the initial download you can detach the tree from
GitHub and later create your own repo starting with this tree as a
template. The tree contains working examples of a MOOS app and helm
behavior that you can replicate when making your own
modules. Eventually, if you continue working with MOOS-IvP, this tree,
in your GitHub repo, can be the home of your software development.

%===================================================================
\subsection{Extending MOOS-IvP}

Both MOOS and IvP are architectures with plugin modules. MOOS apps in
the case of MOOS, and behaviors in the case of the IvP Helm. MOOS-IvP
contains dozens of apps and behaviors, but eventually users will want to
extend the capabilities by writing new modules of their own (apps or
behaviors). This is sometimes referred to as a "layered software
stack", on the left in the figure below. It is sometimes referred to
as "nested" autonomy, as depicted on the right below.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.5\textwidth]{figures/mie.png}
  \caption{{\bf MOOS-IvP-Extend}: Layered or nested, two ways of regarding
  how MOOS-IvP is extended with third party software.}
  \label{fig_mie}
\end{figure}
\vspace{0.1in}

%===================================================================
\subsection{Get the moos-ivp-extend Tree}

The tree can be obtained on the command line using the \cmd{git}
command.  This should be on all MacOS and Linux systems with a basic
OS install.  In the terminal, cd into the same folder where
\var{moos-ivp} resides (not {\em in} the \var{moos-ivp} folder). Run
the command:

\vspace{0.1in}
\begin{consoleverb}
$ git clone https://github.com/moos-ivp/moos-ivp-extend.git
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
Confirm with an \cmd{ls} that both folders are present.

\vspace{0.1in}
\noindent
If the \cmd{git} command is not found, double-check your shell path.
In MacOS it is likely in \var{/usr/bin}. In Linux it is likely in
\var{/bin}.

\vspace{0.1in}
\noindent
Take a quick look at the contents:

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp-extend
  $ ls
  bin/            clean.sh*       missions/       scripts/
  build/          CMakeLists.txt  README          src/
  build.sh*       lib/            README.md
\end{consoleverb}
\vspace{0.1in}

%===================================================================
\subsection{Make It Your Own}

If you run the \cmd{ls} command with the \var{-a} flag, you will see there
are two hidden directories:

\vspace{0.1in}
\begin{consoleverb}
  .git   .gitignore
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
By removing the \var{.git} directory, you detach it from GitHub. You
can leave the other directory.

\vspace{0.1in}
\begin{consoleverb}
  $ rm -rf .git
\end{consoleverb}
\vspace{0.1in}

\noindent
You can then rename your \var{moos-ivp-extend} tree to something
else. If your username is say \pvar{marcus}, then consider renaming it
to \pvar{moos-ivp-marcus}. At a later step you can create a new
repo on your GitHub account (or other hosting service) and upload
this tree to be under your version control.

%===================================================================
\subsection{Build the Tree}

You should be able to now build this tree. This presumes that \var{moos-ivp}
has also already been built, and the two trees are in the same parent directory.

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp-marcus
  $ ./build.sh
\end{consoleverb}
\vspace{0.1in}

\noindent
Assuming you don't see any build errors, you should see a new MOOS app in the
\var{bin/} subdirectory:

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp-marcus
  $ cd bin
  $ ls
  pExampleApp  pXRelayTest
\end{consoleverb}
\vspace{0.1in}

\noindent
These apps are ready to be run in any other MOOS community, in any of the
example missions we have been using thus far. However, they first must
been added to your shell path. 

%===================================================================
\subsection{Augment Your Shell Path}

In your shell configuration file, you likely augmented your shell path as
part of the steps in obtaining the \var{moos-ivp} tree. You need to replicate
that step for your \var{moos-ivp-extend} tree.

\vspace{0.1in}
\noindent
For \cmd{bash} users, this is the \var{.bashrc} file in your home directory.
There is probably a section that looks something like:

\vspace{0.1in}
\begin{consoleverb}

  PATH=/usr/bin
  PATH=$PATH:/sbin
  PATH=$PATH:/usr/sbin
  PATH=$PATH:/opt/homebrew/brew
  ...
  PATH=$PATH:~/moos-ivp/bin
  PATH=$PATH:~/moos-ivp/scripts
  PATH=$PATH:~/moos-ivp-extend/bin     <-- add this line
  ...
  export PATH
\end{consoleverb}
\vspace{0.1in}

\noindent
Add the above line, save the file, and run:

\vspace{0.1in}
\begin{consoleverb}
  $ source ~/.bashrc
\end{consoleverb}
\vspace{0.1in}

\noindent
Confirm that one of the apps in your \var{moos-ivp-extend} tree can now be
found in your shell path:

\vspace{0.1in}
\begin{consoleverb}
  $ which pXRelayTest
  $ /home/you/moos-ivp-you/bin/pXRelayTest
\end{consoleverb}
\vspace{0.1in}

\noindent
If the \cmd{which} function returns no value, then either the binary
\app{pXRelayTest} was not built or you haven't successfully augmented
your shell path. Re-check the above steps.


%===================================================================
\subsection{Next Steps:}

With this \var{moos-ivp-extend} tree you are now prepared to:

\begin{packed_enumerate}
\item Put this tree under version control. If you have a GitHub account, we recommend you
  upload your new tree to a repo under your account. At least so you can back up your
  work so the only copy isn't on your laptop. But you might also want to collaborator
  with colleagues. If you ever want help debugging from a friend or TA, it's also a
  convenient way to get the code in front of their eyes.
\item Add your own apps or behaviors. See the other labs for getting started with this. 
\end{packed_enumerate}

\end{document}
