RSTT v3.1.0 User Manual
===========================


Compiling RSTT from source
------------------------------

In RSTT v3.1.0, no paths should need to be specified in any environment
variables to compile and run. During the compilation process, the Makefiles will
point to the correct library paths within the default directory structure. If
you are having difficulty with strange errors related to paths during
compilation, try and temporarily remove any remnants of past RSTT verisons in
environment variables such as `$PATH`, `$LD_LIBRARY_PATH`, `$DYLD_LIBRARY_PATH`,
or `$SLBM_ROOT`.


### Dependencies


#### MacOS

Below is a list of packages and software required to build RSTT from source. The
version numbers listed are not necessarily required to compile without error;
they are simply those that were used and tested in development.

Software  | Version        | Purpose
:---------|:---------------|:------------------------------
make      | 3.81           | Running compile scripts
gcc       | 4.2.1 (XCode)  | Build C library and tests
g++       | 4.2.1 (XCode)  | Build GeoTess and core RSTT libraries and tests
gfortran  | 9.3.0          | Build Fortran library and tests
java      | openjdk 13.0.2 | Build Java JNI library and tests
javac     | openjdk 13.0.2 | Build Java JNI library and tests
jar       | openjdk 13.0.2 | Build Java JNI library and tests 
javadoc   | openjdk 13.0.2 | Build documentation for Java code
doxygen   | 1.8.17         | Build documentation for C++, C, and Fortran code

The easiest way to satisfy these dependencies on a Mac is to install the
[Homebrew][brew] package manager. Following that, you can install the necessary
dependencies by running these commands in a terminal window:

```bash
$ brew update
$ brew install gcc gfortran openjdk doxygen
```

[brew]: https://brew.sh/


#### Linux

Below is a list of packages and software required to build RSTT from source. The
version numbers listed are not necessarily required to compile without error;
they are simply those that were used and tested in development.

Software  | Version           | Purpose
:---------|:------------------|:------------------------------
make      | 4.2.1             | Running compile scripts
gcc       | 9.3.1             | Build C library and tests
g++       | 9.3.1             | Build GeoTess and core RSTT libraries and tests
gfortran  | 9.3.1             | Build Fortran library and tests
java      | openjdk 1.8.0_242 | Build Java JNI library and tests
javac     | openjdk 1.8.0_242 | Build Java JNI library and tests
jar       | openjdk 1.8.0_242 | Build Java JNI library and tests 
javadoc   | openjdk 1.8.0_242 | Build documentation for Java code
doxygen   | 1.8.15            | Build documentation for C++, C, and Fortran code

The easiest way to satisfy these dependencies on Linux is, depending
on your distro and package manager, by running one of these sets of commands
in a termal window:

```bash
$ sudo apt update
$ sudo apt install build-essentials gfortran default-jdk doxygen
```

```bash
$ yum check-update
$ sudo yum install kernel-devel gcc gcc-c++ gcc-gfortran java-devel doxygen
```


### Build instructions

RSTT is developed in C++, but it also has interfaces in C, Fortran, and Java.
RSTT is distributed in various precompiled forms on [sandia.gov/rstt][rstt], but
if you want or need to compile it from source, yourself, the Makefiles have been
designed so that you need only compile the minimum amount of code necessary to
use RSTT with your language of choice. Do note, however, that because RSTT is
developed in in C++, the core C++ libraries will have to be compiled regardless
of whether or not you intend to use only the C, Fortran, or Java interfaces.

[rstt]: https://www.sandia.gov/rstt

To generally compile RSTT in any of its languages, use the commands, below:

Command              | Description
:--------------------|:--------------------
`make all`           | Make all libraries, documentation, and tests, and run tests (C++, C, Fortran, Java)
`make cpp`           | Make just the components required for the C++ library and documentation (`geotess`, `slbm`, `slbm_docs`, and `slbm_test`)
`make c`             | Make just the components required for the C library and documentation (`geotess`, `slbm`, `slmbc`, `slbmc_docs`, and `slbmc_test`)
`make fortran`       | Make just the components required for the Fortran library and documentation (`geotess`, `slbm`, `slbmfort`, `slbmfort_docs`, and `slbmfort_test`)
`make java`          | Make just the components required for the Java library and documentation (`geotess`, `slbm`, `slbmjni`, `slbmjni_docs`, and `slbmjni_test`)

For more granular-level control of the make process, you may use the following
commands:

Command              | Description
:--------------------|:--------------------
`make geotess`       | Make the GeoTess library (required for RSTT)
`make slbm`          | Make the C++ library (main RSTT code)
`make slbmc`         | Make the C library
`make slbmfort`      | Make the Fortran library
`make slbmjni`       | Make the Java library
`make geotess_docs`  | Make the documentation for the GeoTess library
`make slbm_docs`     | Make the documentation for the C++ library
`make slbmc_docs`    | Make the documentation for the C library
`make slbmfort_docs` | Make the documentation for the Fortran library
`make slbmjni_docs`  | Make the documentation for the Java library
`make slbm_test`     | Make and run a test of the C++ library
`make slbmc_test`    | Make and run a test of the C library
`make slbmfort_test` | Make and run a test of the Fortran library
`make slbmjni_test`  | Make and run a test of the Java library


Usage examples
------------------

In the `usage_examples` directory, there is one example program for each of the
languages supported by RSTT.

Language | File
:--------|:--------------------
C++      | `cc_example.cc`
C        | `c_example.c`
Fortran  | `fortran_example.f90`
Java     | `java_example.java`

Each example program performs the same set of tasks and is written to be as
simple as possible with extensive commenting. These programs are meant to be a
starting point from which users may explore the documentation and write their
own code.

To build and run each example, `cd` to `usage_examples` and run `make.sh` with
any combination of arguments:

* `cc`
* `c`
* `fortran`
* `java`
* `all`

To see an example of how to build and run your own progam, open `make.sh` and
view with your favorite text or source code editor. This shell script is
extensively commented, with each language sorted into *compile* and *run*
segments.


Contact Information
-----------------------

For questions/issues/comments about the software, please contact:

* [Brian Young](mailto:byoung@sandia.gov) (Sandia National Laboratories)

For questions/issues/comments about the results returned by RSTT, please
contact:

* [Steve Myers](mailto:smyers@llnl.gov) (Lawrence Livermore National Laboratory)

* [Mike Begnaud](mailto:mbegnaud@lanl.gov) (Los Alamos National Laboratory)
