OOF2: The Manual

oof2extutils.Extension
	7.3. `oof2extutils` Reference

Name

oof2extutils.Extension — Describe an OOF2 Python extension module

Synopsis

from oof2extutils import Extension
Extension(name,
          sources,
          include_dirs=None,
          libraries=None,
          library_dirs=None,
          define_macros=None,
          undef_macros=None,
          runtime_library_dirs=None,
          extra_objects=None,
          extra_compile_args=None,
          extra_link_args=None,
          language=None)

Description

The oof2extutils.Extension class stores all of the information required for distutils to build a Python extension module. A Python extension module is a small bit of code that allows Python to call C or C++ functions.

In most cases, it should not be necessary to invoke the Extension class explicitly. Instead, use get_swig_ext to create an Extension object from a swig file. The Extension object returned by get_swig_ext can be passed unmodified to distutils.core.setup.

oof2extutils.Extension is derived from distutils.core.Extension, and all constructor arguments allowed by distutils.core.Extension are also allowed by oof2extutils.Extension. The difference between the two classes is that the OOF2 version automatically includes some compilation and link options required by the current OOF2 installation.

Parameters

Many of these parameters are optional and are only listed here because they're available in the distutils.core.Extension base class. The only parameters absolutely required by the oof2extutils.Extension constructor are name, sources, include_dirs, and libraries.

The value of every parameter is either a Python string ('hello') or a list of strings (['Hello', 'world']).

name: The name of the extension. To be compatible with swig, this should be the name of the swig input file without its suffix, and with a “c” appended. For example, if the swig file was package/oofext.swg, the name of the Extension should be oofextc.
sources: This is a list of all of the C++ files that need to be compiled to build the Extension. Since each Extension is built from one swig file, there is only one name in the list, namely the swig C++ output file. The name of the file depends on the swigfile, destdir, and basedir arguments to run_swig. The name should be given either as an absolute path name or relative to the directory containing setup.py.
include_dirs: This is a list of directory names in which the compiler will search for header files. Directories containing OOF2 header files are included in the list automatically. What isn't included, and needs to be, is the location of the extension source code. That is, for the layout shown in Figure 7.2, include_dirs would be set to ['package']. Other directories may be added if necessary.
libraries: This is a list of the names of the libraries that the extension will link with. The OOF2 libraries are included automatically, but libraries constructed by SharedLibrary calls in this setup.py file are not. They need to be included in the list. Library names should be listed without any lib prefix or .so, .dylib, or .a suffix.
library_dirs: Optional. This is a list of directories in which the linker will search for libraries. It automatically includes the location of the main OOF2 libraries, as well as the location of libraries built by SharedLibrary calls in this setup.py file.
define_macros: Optional. A list of C++ preprocessor macros to define.
undef_macros: Optional. A list of C++ preprocessor macros to undefine.
runtime_library_dirs: Optional. A list of additional directories in which to search for libraries at run time.
extra_objects: Optional. A list of extra files to link with.
extra_compile_args: Optional. This is a list of strings, each one an argument to pass to the C++ compiler. Arguments used to compile OOF2 are included automatically.
extra_link_args: Optional. A list of additional options to pass to the linker. Standard options required for all OOF2 extensions are included automatically.
language: Optional. It's assumed to be 'c++'. Don't change it without changing run_swig as well.


oof2extutils.run_swig		oof2extutils.SharedLibrary