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