# README #

## Contributing ##

### Before contributing to this repo, please take a moment to review the project's [**contributing guidelines**](https://bitbucket.org/mbari/lrauv-application/src/master/Contributing.md)

## Your brand new local clone ##

This repository uses git submodules :(

To have a freshly created clone with everything:

```bash
git clone git@bitbucket.org:mbari/lrauv-application.git --recursive
```

## Host Dependencies ##

### Third party libraries ###

Several third party libraries must be installed for dev or target environments:

- [Lightweight Communications and Marshalling (LCM)](https://lcm-proj.github.io)  
(quick start: sudo apt-get update; sudo apt-get install liblcm-bin; sudo apt-get install liblcm-dev)
- [NetCDF](https://www.unidata.ucar.edu/software/netcdf/)
- [openssl](https://www.openssl.org)
- [GNU Readline Library](https://tiswww.case.edu/php/chet/readline/rltop.html)
- Lua5.1
- Python2

To build in a 64-bit envioronment, 32-bit libraries are also needed.

On Ubuntu 20.04+:
```shell
# install LCM deps
sudo apt update
sudo apt install build-essential libglib2.0-dev cmake
# install LCM following https://lcm-proj.github.io/build_instructions.html

# LRAUV deps
sudo apt install lib32ncurses-dev lib32z1 libbz2-1.0:i386 libssl-dev libreadline-dev libnetcdf-dev lua5.1 python2
```
The LRAUV application currently requires gcc/g++ version 7.x
```shell
# you can use Ubuntu's update-alternatives to add version 7 (Ubuntu 20.04 default is gcc-9)
sudo apt install gcc-7 g++-7
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 90 --slave /usr/bin/g++ g++ /usr/bin/g++-9
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 70 --slave /usr/bin/g++ g++ /usr/bin/g++-7

# then configure the system default
sudo update-alternatives --config gcc
```

### TethysL Dependency ###

As part of the general build, all TethysL mission sources `*.tl` under `Missions/` are compiled
into corresponding `.tx` files (which are the artifacts eventually executed by the LRAUV application).
This mission translation step is performed by invoking `tethysl`, the TethysL CLI program.
The build makefile will take care of installing `tethysl` if not available.
However, you must have `java` installed, which is a dependency of `tethysl`.
Please visit <https://docs.mbari.org/tethysl/cli/install/> for more details.

**NOTE for users on `tethyshub`**:
The TethysL dependency is kept up-to-date on the `tethyshub` machine and available for `tethysadmin`.
For other `tethyshub` users, just make sure that `/opt/tethysl/bin` is in your `$PATH`.

## Embedded Target Dependencies ##

* /mbari/LRAUV/rootfs/rootfs-lcm-gpio-11jan18-0  (NOTE: rootfs version may change in future releases)
* /mbari/LRAUV/Tools/linuxi64/cross-compile-tools
* /opt/nxp

These dependencies are set up on tethyshub.shore.mbari.org. See the [lrauv-os-build](https://bitbucket.org/mbari/lrauv-os-build) repo from more details on how to obtain these deps for local builds.

## Building ##

For a dev host environment:
```shell
make distclean  # optional
make

# to run the LRAUV app in simulation mode on a host:
cd <your-path-here>/lrauv-application
./bin/SimDaemon  # the simulation deamon will fork to the background and return immediately
./bin/LRAUV
```

To build for the LRAUV LPC3250 embedded target on tethyshub:
```shell
bash  # optional, so current environment preserved
source /mbari/LRAUV/Tools/linuxi64/cross-compile-tools/activate
# build using the cross-compile toolchain
make distclean  # optional
make lpc3250
```

## Tagging ##

Our procedure is to create a new annotated tag when preparing a vehicle for deployment.
The name of the tag is the ISO 8601 date (i.e. yyyy-mm-dd).

The tag message should note the first deployment the tag will be used on.

For example, the command line might look like:

```shell
cd lrauv-application
./Tools/gittag.sh "Tethys 107 MBTS"
```

There should only be one tag for any given day so if you realize you've forgotten something, use a new name or delete the old tag and make a new one.

## Loading ##

To load a tag onto a vehicle:
```shell
pushd path/to/lrauv-application
git submodule update --recursive
git pull
git checkout $(git describe --abbrev=0)
source /mbari/LRAUV/Tools/linuxi64/cross-compile-tools/activate
make distclean lpc3250 copy-to-<vehicle_name>
# If you want to clean up afterward:
make distclean
git checkout master
# and finally, return to wherever you were
popd
```

Once the tag is loaded onboard LRAUV, **ensure that TethysDash reflects the updated tag**.


## More Git stuff! ##

### Re-syncing an existing clone ###

```bash
cd /to/your/lrauv-application
```

Basically, all you need to do to re-sync your clone against current
**master** branch of the remote repo is to run these two commands:

```bash
git pull origin master
git submodule update --recursive
```

Note: the submodule update command above will in particular make sure to
locally reflect the state of the submodules according to the pointers in
the current tip of the master branch in the parent lrauv-application repo.

This of course not only works for master, but for any other branch or tag.
For example, if you want to reflect the whole state of the code and
submodules at the particular tag `2017-02-07` (as captured in the parent
lrauv-application), the commands would be:

```bash
git checkout 2017-02-07
git submodule update --recursive
```

### Bringing in all updates in submodules ###

To bring in any changes done in the master branch of the remote repositories
associated with the submodules **even if the corresponding pointers in
their parent repos have not been updated**:

```bash
git submodule foreach --recursive "(git checkout master;git pull)&"
```

You will typically run this kind of command in preparation to push any
newer updates in submodules, as explained next.

### Pushing submodules updates ###

This is an scenario in which a user with write privilege wants to update
the commit
hashes associated with some submodules.

With `Config` as an example, this typically involves:

```bash
$ cd Config
$ git checkout master
$ git pull origin master
$ cd ..
$ git add Config
$ git commit -m "update Config pointer to reflect such and such change there..."
$ git push origin master
```

A command like `git submodule foreach --recursive "(git checkout master; git pull)&"`
comes in handy as part of the above when multiple submodule pointers are
to be updated (see previous section).