Helpers¶

Helper functions are used to encapsulate functionality that may be needed by many wrappers. This keeps the individual wrappers simpler while sharing code among wrappers. Helpers may be in C or Fortran. They can also provide a Fortran interface to a C function.

Helper code can be inserted in several files and several locations.

// file C_header_util

// scope=cwrap_include:include


#ifdef SHROUD_SHARE_H
// api=c scope=cwrap_share:source
#endif

#ifdef __cplusplus
extern "C" {
#endif

// api=c scope=cwrap_include:source

// api=c proto

#ifdef __cplusplus
}
#endif

// api=c++ proto_include
// api=c++ proto

// file C_impl_util

#ifdef __cplusplus
extern "C" {
#endif

// api=c scope=cwrap_impl:source

#ifdef __cplusplus
}
#endif

// api=c++ scope=cwrap_impl source

// wrapper implementation file

// scope=cwrap_include include

// api=cxx scope=file:source

extern "C" {
// api=c scope=file:source

module name

! modules
use module, only : symbol

! derived_type

! interface

contains

! f_source

end module name

Listed in the statements.helper field. The C helpers are written after creating the Fortran wrappers by clibrary.write_impl_utility function.

The helpers will be preprocessed using format to expand some fields. All helpers use the same dictionary. This allows a helper to add a field using fmtdict which can be used by later helpers. The format dictionary’s parent is the library’s format dictionary. This give the helpers access to global names such as C_array_type and F_array_type.

Fields which are formatted will need to follow the formatting rules. The most common is that {{ is required to insert a literal {. Otherwise, it is assumed to be a format field.

Fields¶

name¶

The name must start with h_helper_. The remainder of the string is used as the helper name in the helper fields of statement groups.

c_fmtname / f_fmtname¶

Name of function or type created by the helper. This allows the function name to be independent of the helper name so that it may include a prefix to help control namespace/scope. Useful when two helpers create the same function. Added to the wrapper’s format dictionary to allow it to be used in statements.

This field is formatted.

fmtdict¶

A dictionary which will be formatted and added to the common format dictionary used to preprocess the helpers.

api¶

c or cxx. Defaults to c. Must be set to c for helper functions which will be called from Fortran. Helpers which use types such as std::string or std::vector can only be compiled with C++. Setting api to c will add the prototype in an extern "C" block. Effects the fields source, proto, and proto_include are inserted.

scope¶

Scope of helper.

file - (default) added as file static and may be in several files. source may set source, c_source, or cxx_source. functions must be static since they may be included in multiple files.
cwrap_include - Will add to C_header_utility and shared among files. These names need to be unique since they are shared across wrapped libraries. Used with structure and enums.
cwrap_impl - Helpers which are written in C and called by C or Fortran.
cwrap_share - Code that will be identical across wrapped libraries. It is protected by the SHROUD_SHARE_H define to only be included once. This allows one library to use wrappers from another library. Most sharing is done by mangling names. This section will be identical across libraries. It must be C language only if C wrappers are being created.

c_include¶

List of files to #include in implementation file when wrapping a C library.

cxx_include¶

List of files to #include in implementation file when wrapping a C++ library.

source¶

List of lines of code inserted before any wrappers. The functions should be file static. Used if c_source or cxx_source is not defined. This field is formatted.

c_source¶

Lines of C code used when language=c. This field is formatted.

cxx_source¶

Lines of C++ code used when language=c++. This field is formatted.

dependent_helpers¶

List of helpers names needed by this helper. They will be added to the output before current helper.

proto¶

Prototype for helper function. Must be in the language of api. This field is formatted.

proto_include¶

List of files to #include before the prototype.

Include in the utility file defined by format field C_header_utility.

include¶

List of files to #include. Used when c_header and cxx_header are not defined.

derived_type¶

List of lines of Fortran code for a derived type. Inserted before interfaces. This field is formatted.

interface¶

List of lines of Fortran code for INTERFACE. This field is formatted.

f_source¶

List of lines of Fortran code for CONTAINS. This field is formatted.