Installation

Compiling errors on latest MacOS Changes to GCC on the latest versions of MacOS have resulted in compiling errors on RSTT v3.2.0. This will be addressed in the next release, but in the meantime these errors may be temporarily resolved by adding “-std=c++11” to the CXXFLAGS in each Makefile where it is present.

Compiling RSTT from source

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, $DYLD_FALLBACK_LIBRARY_PATH, and $SLBM_ROOT or $SLBM_HOME.

After compiling, when writing your own codes that utilize the latest RSTT libraries, you may find it useful to set one of the following environmental variables to the root directory of RSTT:

  1. $RSTT_ROOT
  2. $RSTT_HOME
  3. $SLBM_ROOT
  4. $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, if set, in order.

Dependencies

MacOS

Below is a list of packages and software required to build RSTT from source. The version numbers listed are those used and tested in development.

SoftwareVersionPurpose
make3.81Running compile scripts
gcc4.2.1 (XCode)Build C library and tests
g++4.2.1 (XCode)Build GeoTess and core RSTT libraries and tests
gfortran9.3.0Build Fortran library and tests
javaopenjdk 13.0.2Build Java JNI library and tests
javacopenjdk 13.0.2Build Java JNI library and tests
jaropenjdk 13.0.2Build Java JNI library and tests
javadocopenjdk 13.0.2Build documentation for Java code
doxygen1.8.17Build documentation for C++, C, and Fortran code
python3.6.12Run Python library and tests
pip20.1.1Build Python module
sphinx3.3.1Build 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.

Click to expand
$ python3 -m pip install pybind11 sphinx sphinx-autodoc-typehints

Or, 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 for the local user.

$ python3 -m pip install --user pybind11 sphinx sphinx-autodoc-typehints
Xcode

In the latest versions of MacOS, you will also need to have installed the latest Xcode and Xcode Command Line Tools available for your OS version.

You can install the Xcode app either through the App Store or Apple Developer. Make sure to fully open the app to finish installation of dependencies after you install the main program.

Once you have the Xcode app installed, you can install the Xcode Command Line Tools by opening a Terminal window and typing:

$ xcode-select --install

Linux

Below is a list of packages and software required to build RSTT from source. The version numbers listed are those used and tested in development.

SoftwareVersionPurpose
make4.2.1Running compile scripts
gcc9.3.1Build C library and tests
g++9.3.1Build GeoTess and core RSTT libraries and tests
gfortran9.3.1Build Fortran library and tests
javaopenjdk 1.8.0_242Build Java JNI library and tests
javacopenjdk 1.8.0_242Build Java JNI library and tests
jaropenjdk 1.8.0_242Build Java JNI library and tests
javadocopenjdk 1.8.0_242Build documentation for Java code
doxygen1.8.15Build documentation for C++, C, and Fortran code
python3.6.8Run Python library and tests
pip8.1.1Build Python module
sphinx3.3.1Build 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:

apt
# C++, C
$ sudo apt install build-essential

# Fortran
$ sudo apt install gfortran

# Java
$ sudo apt install default-jdk

# Python
$ sudo apt install python3-pip python3-dev python3-pybind11

# Documentation
$ sudo apt install doxygen python3-sphinx python3-sphinx-autodoc-typehints
dnf
# 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 install config-manager --set-enabled powertools
$ sudo dnf install doxygen python3-sphinx
$ python3 -m pip install sphinx-autodoc-typehints
yum
# 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 install 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.

Click to expand
$ python3 -m pip install pybind11 sphinx sphinx-autodoc-typehints

Or, 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 for the local user.

$ python3 -m pip install --user pybind11 sphinx sphinx-autodoc-typehints

Build instructions

RSTT is developed in C++, but it also has interfaces in C, Fortran, Java, and Python. RSTT’s Python interface is distributed in a precompiled module (see Downloads), 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, Java, or Python interfaces.

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

CommandDescription
makeMake all libraries, tests, and run tests (C++, C, Fortran, Java, Python)
make allMake all libraries, documentation, tests, and run tests (C++, C, Fortran, Java, Python)
make cppMake the components required for the C++ library and run tests
(geotess,slbm, andslbm_test)
make cMake the components required for the C library and run tests
(geotess,slbm,slmbc, andslbmc_test)
make fortranMake the components required for the Fortran library and run tests
(geotess,slbm,slbmfort, andslbmfort_test)
make javaMake the components required for the Java library and run tests
(geotess,slbm,slbmjni, andslbmjni_test)
make pythonMake the components required for the Python library and run tests
(geotess,slbm,slbmpy, andslbmpy_test)
make docsMake the documentation for all the libraries (C++, C, Fortran, Java, Python)
make cpp_docsMake the documentation for the C++ library (slbm_docs)
make c_docsMake the documentation for the C library (slbmc_docs)
make fortran_docsMake the documentation for the Fortran library (slbmfort_docs)
make java_docsMake the documentation for the Java library (slbmjni_docs)
make python_docsMake the documentation for the Python library (slbmpy_docs)

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

CommandDescription
make geotessMake the GeoTess library (required for RSTT)
make slbmMake the C++ library (main RSTT code)
make slbmcMake the C library
make slbmfortMake the Fortran library
make slbmjniMake the Java library
make slbmpyMake the Python library
make geotess_docsMake the documentation for the GeoTess library
make slbm_docsMake the documentation for the C++ library
make slbmc_docsMake the documentation for the C library
make slbmfort_docsMake the documentation for the Fortran library
make slbmjni_docsMake the documentation for the Java library
make slbmpy_docsMake the documentation for the Python library
make slbm_testMake and run a test of the C++ library
make slbmc_testMake and run a test of the C library
make slbmfort_testMake and run a test of the Fortran library
make slbmjni_testMake and run a test of the Java library
make slbmpy_testMake and run a test of the Python library

Usage examples

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

LanguageFile
C++cpp_example.cc
Cc_example.c
Fortranfortran_example.f90
Javajava_example.java
Pythonpython_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 program, 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.

Path troubleshooting

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 .:$RSTT_ROOT/lib/slbmjni.jar -Djava.library.path=$RSTT_ROOT/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
>>> sys.path.append('/path/to/rstt/lib')

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,

  1. $RSTT_ROOT
  2. $RSTT_HOME
  3. $SLBM_ROOT
  4. $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.