Installing

The easiest way to install Shroud is via pip which will fetch a file from pypi

pip install llnl-shroud

This will install Shroud into the same directory as pip. A virtual environment can be created if another destination directory is desired. For details see the python docs

The source is available from github.com/LLNL/shroud A shiv packaged executable is also available at github releases. This is an executable file which contains Shroud and PyYAML and uses the Python3 in the user’s path.

Shroud is written in Python and has been tested with version 2.7 and 3.4+. It requires the module:

After downloading the source:

python setup.py install

This will create the script shroud in the same directory as Python.

Since shroud installs into Python’s bin directory, it may be desirable to setup a virtual environment to try it out:

$ cd my_project_folder
$ virtualenv my_project
$ source my_project/bin/activate
$ cd path/to/shroud/source
$ python setup.py install

This will create an executable at my_project/bin/shroud. This version requires the virtual environment to run and may be difficult to share with others.

It’s possible to create a standalone executable with shiv:

$ cd path/to/shroud/source
$shiv --python '/usr/bin/env python3' -c shroud -o dist/shroud.pyz .

A file shroud.pyz is created which bundles all of shroud and pyYAML into a single file. It uses the python on your path to run.

Building wrappers with CMake

Shroud can produce a CMake macro file with the option -cmake. This option can be incorporated into a CMakefile as:

if(EXISTS ${SHROUD_EXECUTABLE})
    execute_process(COMMAND ${SHROUD_EXECUTABLE}
                    --cmake ${CMAKE_CURRENT_BINARY_DIR}/SetupShroud.cmake
                    ERROR_VARIABLE SHROUD_cmake_error
                    OUTPUT_STRIP_TRAILING_WHITESPACE )
    if(${SHROUD_cmake_error})
       message(FATAL_ERROR "Error from Shroud: ${SHROUD_cmake_error}")
    endif()
    include(${CMAKE_CURRENT_BINARY_DIR}/SetupShroud.cmake)
endif()

The path to Shroud must be defined to CMake. It can be defined on the command line as:

cmake -DSHROUD_EXECUTABLE=/full/path/bin/shroud

The add_shroud macro can then be used in other CMakeLists.txt files as:

add_shroud(
    YAML_INPUT_FILE      ${YAML_INPUT_FILE}
    C_FORTRAN_OUTPUT_DIR c_fortran
)

CMake will treat all Fortran files as free format with the command:

set(CMAKE_Fortran_FORMAT FREE)

Building Python extensions

setup.py can be used to build the extension module from the files created by shroud. This example is drawn from the run/tutorial example. You must provide the paths to the input YAML file and the C++ library source files:

import os
from distutils.core import setup, Extension
import shroud
import numpy

outdir = 'build/source'
if not os.path.exists(outdir):
    os.makedirs(outdir)
config = shroud.create_wrapper('../../../tutorial.yaml',
                               path=['../../..'],
                               outdir=outdir)

tutorial = Extension(
    'tutorial',
    sources = config.pyfiles + ['../tutorial.cpp'],
    include_dirs=[numpy.get_include(), '..']
)

setup(
    name='tutorial',
    version="0.0",
    description='shroud tutorial',
    author='xxx',
    author_email='yyy@zz',
    ext_modules=[tutorial],
)

The directory structure is layed out as:

tutorial.yaml
run
  tutorial
    tutorial.cpp   # C++ library to wrap
    tutorial.hpp
    python
      setup.py     # setup file shown above
      build
         source
           # create by shroud
           pyClass1type.cpp
           pySingletontype.cpp
           pyTutorialmodule.cpp
           pyTutorialmodule.hpp
           pyTutorialhelper.cpp
         lib
            tutorial.so   # generated module