Building and Testing the Under Sea Modeling Library (USML)

The Under Sea Modeling Library (USML) is a collection of C++ software development modules for sonar modeling and simulation. The Wavefront Queue 3D (WaveQ3D) model is the component of USML that computes acoustic transmission loss in the ocean using Hybrid Gaussian Beams in Spherical/Time Coordinates. At this time, most of the other modules provide support to WaveQ3D.

Before you get started

USML depends on the NetCDF package, for access to test data, and the Boost package, for fast computations (uBLAS) and unit test utilities. Correctly configuring these packages is the #1 problem reported by USML users.

The USML build process assumes that the software will be installed into a directory called usml and it won't build properly if that is not the case. These instructions refer to usml as the home directory. The directory that contains usml is refered to as the parent directory. The header files, *.cc source, and tests for each module are found in the subdirectories of usml. The #include statements in the code explicitly rely on this directory structure. For example, if sreilly decides to install USML under ~/Projects on a Linux machine, the home directory would be /home/sreilly/Projects/usml and the parent directory would be /home/sreilly/Projects. Confusion over this scheme is the #2 problem reported by USML users.

Before you attempt to build and test USML, please read these instructions carefully. Good luck.

Linux using GNU C++ and Unix Makefiles

We've tested this process with:

64-bit CentOS 6.6 with gcc 4.4.7

The steps that follow are the process we used to setup USML for a 64-bit CentOS 6 development environment. We expect your environment to be a little different, but this should get you started. Since CentOS is derived from Red Hat Enterprise Linux, (see http://community.redhat.com/centos-faq) we expect this process to work identically in RHEL6.

Download the source code distribution for USML
- Extract USML from the distribution media. On Linux, these consist of
```
        tar -xzf usml-src-#.#.#.tar.gz
        tar -xzf usml-doc-#.#.#.tar.gz
        tar -xzf usml-data-#.#.#.tar.gz
	
```
  where #.#.# is the version number to be installed. In this example, we'll extract them to ~/Projects, and this creates a home directory called ~/Projects/usml
- The USML build process absolutely requires the home directory to be named usml. If you are extracting the code from another source, such as GitHub, make sure to rename the home directory usml.
Install CMake GUI 2.8 and NetCDF Development 4.1 RPMs from the CentOS yum servers
```
	sudo yum install cmake-gui netcdf-devel
	
```
If you do not have access to the CentOS yum servers, you can find the needed RPMs from the following sites:
- cmake-2.8.8-4.el6.x86_64.rpm and cmake-gui-2.8.8-4-el6.x86_64.rpm from http://packages.atrpms.net/dist/el6/cmake
- netcdf-4.1.2-1.el6.rf.i686.rpm and netcdf-devel-4.1.2-1.el6.rf.i686.rpm from http://pkgs.repoforge.org/netcdf
- libssh2-1.4.2-1.el6.i686.rpm, libidn-1.18-2.el6.i686.rpm, and libcurl-7.19.7-37.el6_5.3.i686.rpm from http://mirror.centos.org/centos-6/6.6/os/i386/Packages
Download and install the source code distribution for NCO 3.9.9
- This library provides the NCKS utility that we use in many of our NetCDF regression tests.
- We used the source code distribution called nco-3.9.9.tar.gz from http://nco.sourceforge.net/src/
- To install this software in /usr/local
```
	cd path/to/nco-3.9.9
	./configure
	make
	sudo make install
	
```
Install Boost library from RPM or source.
- You can install Boost 1.41 RPMs from the CentOS yum servers, if it is not installed already.
```
	sudo yum install boost-devel boost-static
	
```
- Or, you can download newer Boost versions as source code. We tested this with the distribution called boost_1_57_0.tar.gz from http://sourceforge.net/projects/boost/files/boost/1.57.0 and the install instructions from http://www.boost.org/doc/libs/1_57_0/more/getting_started/unix-variants.html. To install this software in /usr/local, these instructions boil down to
```
	cd path/to/boost_1_57_0
	./bootstrap.sh
	b2
	sudo b2 install
	
```
- There is a bug in the Boost uBLAS library that vector and matrix scaling using operator/().
  - To see the corrected version of this code, please search for the symbol BOOST_UBLAS_CHECK_DIVISION_TYPE in the vector_expression.hpp and matrix_expression.hpp files in the usml/config directory.
  - In each case, the operator/() should be using the enable_if<> macros just like the operator*() just above it.
  - Those using Boost 1.41 through 1.56 can just replace the original files with the ones from the usml/config directory.
  - Boost 1.57 fixed the problem in vector_expression.hpp, but requires replacing matrix_expression.hpp with the file usml/config/matrix_expression_1_57.hpp.
- The pedantic option does not work with Boost 1.52. There are several cases where this specific version of Boost uses C++0x features, like long long value, that are not supported by c++98. Turning off the pedantic option works around this issue.
- Some versions of Boost, using gcc at -O0 optimization levels, fail to properly chain multiple boost::ublas operations into a single evaluation. When this happens, the result is equal to the first operation. For this reason, we recommend using -O1 as the minimum optimization level.
Use cmake-gui to generate Unix Makefiles project
- In the cmake-gui tool (example below), set the source directory to the home directory where you installed the USML source code. As suggested above source code could go in ~/Projects/usml.
- Setup for an "out of source" build by setting the binaries directory to something like the ~/Projects/usml-build directory. Using a binary directory that is not outside of the source tree is strictly optional.
- Use the Configure button to process the CMakeList file. Select the Unix Makefile generator from the pop-up menu.
- Change options to match your development requirements. The default options should be correct for most installations.
- Hit the Configure button a second time, even if you have not changed any options. Hit the Generate button to create makefiles for your system. At this point, you can close the cmake-gui tool.
Run the make utility from ~/Projects/usml-build directory to compile both
The usml_test regression test in this directory should run without errors.
- Prints *** No errors detected if fully successful.
If this test is successful, install the USML libraries
- Run sudo make install to deploy into the directory defined by the CMAKE_INSTALL_PREFIX, which defaults to /usr/local.
- USML header files are written to <prefix>/include/usml
- USML libraries are written to <prefix>/lib
- CMake configuration files are written to <prefix>/lib/cmake/USML
- Run sudo make uninstall will remove these files.
The install process can be re-run with different selections for Release/Debug and Static/Dynamic libraries to populate libraries with these variants.
- But, note that if both Static and Dynamic libraries are present in the same directory, the USMLConfig.cmake process will only find the dynamic ones.

cmake-gui example

Linux using Eclipse CDT4

This is almost identical to the setup for Unix Makefiles with some small exceptions.

Setting up for an "out of source" build is not optional.
Select Eclipse CDT4 - Unix Makefiles when configuring CMake.
Turn on Advanced options to see all of the CMake variables for Eclipse.
- Check the CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT option.
To import this project into Eclipse:
- Select Import... from the File menu.
- Select Existing Projects into Workspace under General folder.
- Select the parent of the usml, such as ~/Projects
- Check the usml-Release and usml-Source projects and select Finish.
Select Build All from the Build menu to compile.

Windows using Microsoft Visual C++

We've tested this process using Windows 7 with:

32-bit Visual Studio 2010 Express
32-bit and 64-bit Visual Studio 2013 Professional and Community versions (msvc 12.0)

The steps that follow are the process we used to setup USML for a 32-bit Visual Studio 2010 development environment. We expect your environment to be a little different, but this should get you started.

Download the source code distribution for USML
- Extract USML from the distribution media. On Windows, these consist of
```
        tar -xzf usml-src-#.#.#.zip
        tar -xzf usml-doc-#.#.#.zip
        tar -xzf usml-data-#.#.#.zip
	
```
  where #.#.# is the version number to be installed. In this example, we extracted them to C:\Projects, and this created a directory called C:\Projects\usml
- The USML build process absolutely requires the home directory to be named usml. If you are extracting the code from another source, such as GitHub, make sure to rename the home directory to usml.
Download the binary distribution for CMake 3.1.0
- We used the Win32 installer called cmake-3.1.0-win32-x86.exe, from http://www.cmake.org/download.
- Running this installer deposits the software in the C:\Program Files (x86)\CMake directory by default.
Download the pre-built Windows binaries for Boost 1.57
- We used the Win32 installer called boost_1_57_0-msvc-10.0-32.exe from http://sourceforge.net/projects/boost/files/boost-binaries.
  - Note the ’10.0’ refers to Visual Studio 10, select appropriately.
- Running this installer deposits the software in the C:\local\boost_1_57_0 directory by default.
- There is a bug in the Boost uBLAS library that vector and matrix scaling using operator/().
  - To see the corrected version of this code, please search for the symbol BOOST_UBLAS_CHECK_DIVISION_TYPE in the vector_expression.hpp and matrix_expression.hpp files in the usml/config directory.
  - In each case, the operator/() should be using the enable_if<> macros just like the operator*() just above it.
  - Those using Boost 1.41 through 1.56 can just replace the original files with the ones from the usml/config directory.
  - Boost 1.57 fixed the problem in vector_expression.hpp, but requires replacing matrix_expression.hpp with the file usml/config/matrix_expression_1_57.hpp.
Download the pre-built Windows binaries for NetCDF-C 4.3.2,
- We used the Win32 installer called netCDF4.3.2-NC4-32.exe from http://www.unidata.ucar.edu/software/netcdf/docs/winbin.html
- Running this installer deposits the software in the C:\Program Files (x86)\netCDF 4.3.2 directory by default.
Add Boost, NetCDF, and USML environment variables
- Right click on Computer, select Properties -> Advanced system settings -> Environment Variables.
- Create new user variable BOOST_ROOT = C:\local\boost_1_57_0.
- Create new user variable BOOST_LIBRARY_DIR = %BOOST_ROOT%\lib32-msvc-10.0.
- Create new user variable NETCDF_DIR = C:\Program Files (x86)\netCDF 4.3.2.
- Create new user variable NETCDF_PATH = %NETCDF_DIR%\bin;%NETCDF_DIR%\deps\w32\bin.
- Create new user variable USML_DIR for the USML installation directory. We used C:\local\usml to avoid permission problems installing libraries into Program Files,
- Finally, add %BOOST_LIBRARY_DIR%;%NETCDF_PATH%;%USML_DIR%\lib to the Path variable.
Use cmake-gui to generate Visual Studio project
- We set Where is the source code: to C:\Projects\usml.
- We set Where to build the binaries: to C:\Projects\usml-build to create an out-of-source build.
- Hit Configure button, select your version of Visual Studio.
- If status shows Configuring done, hit Configure again, then Generate.
Use Visual Studio to build project
- Open the file usml.sln, in the build directory, using Visual Studio
- Select Rebuild Solution from Build menu.
Test the ability to run USML applications
- Right click on the usml_test target and select Set as StartUp Project.
- Select Start Without Debugging under the Debug menu.
- Test fully successful if *** No errors detected printed to screen.
If this test is successful, install the USML libraries
- Select Batch Build... under the Build menu.
- Check the Build checkbox next to the Debug and Release versions of the INSTALL targets.
- Click on the Build button to compile and deploy these releases into the directory defined by the USML_DIR prefix.
  - USML header files are written to <prefix>/include/usml
  - USML libraries are written to <prefix>/lib
  - CMake configuration files are written to <prefix>/CMake
- Building the uninstall target will remove these files.
- Note that if both Static and Dynamic libraries are created in the same directory, the *.lib files will overwrite each other.

Using USML with CMake

USML does not require your project to use CMake. However, CMake configuration files are provided to automate the integration of USML, Boost, and NetCDF into your CMake build process, if you so choose. The example below shows a CMakeLists.txt script that creates an USML enabled executable called example from a notional file called example.cc.

    cmake_minimum_required( VERSION 2.6 )
    project( usml_example CXX )

    find_package( USML 1.0 REQUIRED )
    include_directories( ${USML_INCLUDES} )
    add_executable( example example.cc )
    target_link_libraries( example ${USML_LIBRARIES} )

In this example, the find_package command uses files called USMLConfig.cmake and USMLUse.cmake to configure the include and library files for USML, Boost, and NetCDF. A file called USMLConfigVersion.cmake is used to check the desired USML version against the installed version.