Tested on:
In RSTT v3.2.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 versions in environment variables such as $PATH
, $LD_LIBRARY_PATH
, $DYLD_LIBRARY_PATH
, and $SLBM_ROOT
or $SLBM_HOME
.
When writing your own codes that utilize the RSTT libraries, you may find it useful to set one of the following environmental variables to the root directory of RSTT:
$RSTT_ROOT
$RSTT_HOME
$SLBM_ROOT
$SLBM_HOME
In both the Java and Python interfaces, RSTT will first attempt to load the appropriate libraries through the system paths. If that fails, they will fall back to searching the path provided in the above variables, in order.
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 |
python | 3.8.3 | Run Python library and tests |
pip | 20.1.1 | Build Python module |
sphinx | 3.3.1 | Build documentation for Python code |
The easiest way to satisfy these dependencies on a Mac is to install the Homebrew package manager. Following that, you can install the necessary dependencies by running these commands in a terminal window:
brew update
$ brew install gcc gfortran openjdk doxygen python3 pybind11 sphinx-doc
$ python3 -m pip install sphinx-autodoc-typehints $
NOTE: You can also install pybind11, Sphinx, and related modules directly through pip
.
python3 -m pip install pybind11 sphinx sphinx-autodoc-typehints $
If you are having trouble with installing things with pip
due to disk/folder permissions, try adding --user
to the pip
flags in order to install modules to a local directory.
python3 -m pip install --user pybind11 sphinx sphinx-autodoc-typehints $
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 |
python | 3.6.8 | Run Python library and tests |
pip | 8.1.1 | Build Python module |
sphinx | 3.3.1 | Build documentation for Python 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:
# C++, C
sudo apt install build-essentials
$
# Fortran
sudo apt install gfortran
$
# Java
sudo apt install default-jdk
$
# Python
sudo apt install python3-pip python3-devel python3-pybind11
$
# documentation
sudo apt install doxygen python3-sphinx python3-sphinx-autodoc-typehints $
# C++, C
sudo dnf install kernel-devel gcc gcc-c++
$
# Fortran
sudo dnf install gcc-gfortran
$
# Java
sudo dnf install java-devel
$
# Python
sudo dnf install python3-devel
$ python3 -m pip install pybind11
$
# documentation
sudo dnf config-manager --set-enabled powertools
$ sudo dnf install doxygen python3-sphinx
$ python3 -m pip install sphinx-autodoc-typehints $
# C++, C
sudo yum install kernel-devel gcc gcc-c++
$
# Fortran
sudo yum install gcc-gfortran
$
# Java
sudo yum install java-devel
$
# Python
sudo yum install python3-devel
$ python3 -m pip install pybind11
$
# documentation
sudo yum config-manager --set-enabled PowerTools
$ sudo yum install doxygen python3-sphinx
$ python3 -m pip install sphinx-autodoc-typehints $
NOTE: On any distro, you can install pybind11, Sphinx, and related modules directly through pip
.
python3 -m pip install pybind11 sphinx sphinx-autodoc-typehints $
If you are having trouble with installing things with pip
due to disk/folder permissions, try adding --user
to the pip
flags in order to install modules to a local directory.
python3 -m pip install --user pybind11 sphinx sphinx-autodoc-typehints $
RSTT is developed in C++, but it also has interfaces in C, Fortran, Java, and Python. RSTT is distributed in various precompiled forms on sandia.gov/rstt, but if you prefer, 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 C++, the core C++ libraries will have to be compiled regardless of whether or not you intend to use only the C, Fortran, Java, or Python interfaces.
To generally compile RSTT in any of its languages, use the commands, below:
Command | Description |
---|---|
make |
Make all libraries, tests, and run tests (C++, C, Fortran, Java, Python) |
make all |
Make all libraries, documentation, tests, and run tests (C++, C, Fortran, Java, Python) |
make cpp |
Make the components required for the C++ library and run tests (geotess , slbm , and slbm_test ) |
make c |
Make the components required for the C library and run tests (geotess , slbm , slmbc , and slbmc_test ) |
make fortran |
Make the components required for the Fortran library and run tests (geotess , slbm , slbmfort , and slbmfort_test ) |
make java |
Make the components required for the Java library and run tests (geotess , slbm , slbmjni , and slbmjni_test ) |
make python |
Make the components required for the Python library and run tests (geotess , slbm , slbmpy , and slbmpy_test ) |
make docs |
Make the documentation for all the libraries (C++, C, Fortran, Java, Python) |
make cpp_docs |
Make the documentation for the C++ library (slbm_docs ) |
make c_docs |
Make the documentation for the C library (slbmc_docs ) |
make fortran_docs |
Make the documentation for the Fortran library (slbmfort_docs ) |
make java_docs |
Make the documentation for the Java library (slbmjni_docs ) |
make python_docs |
Make the documentation for the Python library (slbmpy_docs ) |
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 slbmpy |
Make the Python 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 slbmpy_docs |
Make the documentation for the Python 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 |
make slbmpy_test |
Make and run a test of the Python library |
In the usage_examples
directory, there is one example program for each of the languages supported by RSTT.
Language | File |
---|---|
C++ | cpp_example.cc |
C | c_example.c |
Fortran | fortran_example.f90 |
Java | java_example.java |
Python | python_example.py |
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:
cpp
c
fortran
java
python
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, and each language is sorted into compile and run segments.
Care was taken to make linking to the RSTT libraries as painless as possible. For any of the languages, you can run usage_examples/make.sh
, and it will print the compiling and run commands as they are executed so that you can see how the base libraries are included and linked during compilation. For example, these are the commands used to link and compile the Fortran usage example on MacOS,
# NOTE: $RSTT_ROOT = /path/to/rstt
gfortran -march=native -Ddarwin -m64 -O1 -fno-underscoring -cpp -ffree-line-length-none -I$RSTT_ROOT/GeoTessCPP/include -I$RSTT_ROOT/SLBM/include -I$RSTT_ROOT/SLBM_Fort_shell/include -o fortran_example.o -c fortran_example.f90
$ gfortran -march=native -Ddarwin -m64 -O1 -fno-underscoring -cpp -ffree-line-length-none -Wl,-rpath,$RSTT_ROOT/lib -o fortran_example fortran_example.o -lm -lstdc++ -L$RSTT_ROOT/lib -lgeotesscpp -lslbm -lslbmFshell $
For Java programs, you have to ensure that libslbmjni
is in your java.library.path
, and that slbmjni.jar
is in your classpath. When invoking your java
command, this can be accomplished by
java -classpath .:/path/to/rstt/lib/slbmjni.jar -Djava.library.path=/path/to/rstt/lib example_java $
For Python programs, you should either ensure that your Python module search path contains the RSTT lib
folder, e.g.,
import sys
'/path/to/rstt/lib') sys.path.append(
or you should install the compiled RSTT Python module,
python3 -m pip install --no-index --find-links=/path/to/rstt/SLBM_Py_shell/wheel rstt $
The rstt
Python module contains copies of libgeotesscpp
and libslbm
within the module structure, itself, and unless something goes wrong, it should load those internal copies by default.
Both the Python and Java usage examples also contain blocks of code to attempt to read the appropriate libraries using paths from environment variables if they fail to find them any other way. These code blocks are well-commented and are located in the static {}
block in java_example.java
and before the if __name__ == "__main__"
in python_example.py
. Both bits of code work the same way, which is to first attempt to load the correct libraries using a simple loadLibrary
or import
command, and if that fails they will search the paths delineated in the following environment variables, in order,
$RSTT_ROOT
$RSTT_HOME
$SLBM_ROOT
$SLBM_HOME
If you set one of these environment variables in your terminal ($ export RSTT_ROOT=/path/to/rstt
) and simply copy and paste the described code blocks in the usage_examples/java_example.java
and python_example.py
into your own programs, you will not have to provide -Djava.library.path
when invoking your java
command, nor will you have to pip install
the rstt
module in Python—instead the rstt
module will be imported from the rstt
folder inside of /path/to/rstt/lib
.
For questions/issues/comments about the software, please contact:
For questions/issues/comments about the results returned by RSTT, please contact:
Steve Myers (Lawrence Livermore National Laboratory)
Mike Begnaud (Los Alamos National Laboratory)