OOF2: The Manual

swig_sources
	Tools for Building Extensions

Name

swig_sources — CMake function for running swig and building Python extension modules.

Synopsis

swig_sources(SWIGFILES <files> SWIGDEST <dest> [other arguments])

Required Arguments

SWIGFILES: A list of swig files to process from the current directory. The files must have the suffix “.swg”, which should not be included. For each name swigfile in the list, swigfile.swg will be swigged, generating a python file called swigfile.py and a C++ file, which will be compiled and linked into a shared library called _swigfile.so.^[64]
SWIGDEST: The name of the destination directory where the files will be installed. It should be a location in Python's path, so that the extension module can be imported.

Optional Arguments

SOURCES

A list of C++ files that will be compiled and linked into the shared library.

Only use this option if just one file is given in SWIGFILES, because the code will be duplicated in each shared library. If there are multiple swig files and some of them need to use SOURCES, call swig_sources separately for each. If multiple swig files need to link to the same source files, put the source files in one call to swig_sources, and in the other calls use LIBRARIES to link to the compiled the sources.

SCRIPTS

A list of Python files to copy directly to the installation directory.

CFLAGS

C++ flags to use when compiling the swig-generated wrapper code and any files listed in SOURCES.

INCLUDE_DIRECTORIES

Directories to search for C++ header files.

LIBRARIES

A list of libraries to link to. They can be library names to be searched for, full path names, or cmake targets.

TARGET_SFX

CMake requires that all targets in a project have unique names, even though the name is used only internally. If CMake complains that a target name is already in use,^[65] set TARGET_SFX to a short string, which will be appended to the target name to make it unique.

Description

swig_sources is a CMake function that is called from the CMakeLists.txt file in a source directory or subdirectory. It groups together a number of CMake operations required to build and install Python extension modules from the swig and C++ source code in the directory.

See Chapter 7 for information on how to build CMake files that use swig_sources.

swig_sources is defined in the file oofbuildtools.cmake in the OOF2 source directory. To make it easier to build OOF2 extensions, when OOF2 is installed with OOF2_DEV_INSTALL set to ON, oofbuildtools.cmake is copied to PREFIX/share/oof2/tools, where PREFIX is the value of CMAKE_INSTALL_PREFIX that was used to build OOF2. The CMakeLists.txt file in an extension's source directory should include oofbuildtools.cmake like this:

include("PREFIX/share/oof2/tools/oofbuildtools.cmake")

If the extension source occupies multiple directories, the file needs to be included only in the CMakeLists.txt file in the topmost parent directory.

Arguments to CMake functions are of the form

KEYWORD value1 value2 ...

with zero or more values for each keyword. The line breaks are optional, so

KEYWORD value1 value2

is the same as

KEYWORD value1 value2

${VARIABLE} is the value of a variable called VARIABLE.

For more information on using CMake and writing CMake files, see https://cmake.org/cmake/help/latest/.

Example

swig_sources(
  SWIGFILES
  extension1 
  LIBRARIES
  ${OOF2COMMON} ${OOF2ENGINE} 
  INCLUDE_DIRECTORIES
  /Users/oofuser/include/oof2 
  SOURCES
  extension1.C function.C 
  SWIGDEST
  ${CMAKE_INSTALL_PREFIX}/modules 
  )

	Process the file `extension1.swg` and create `extension1.py` and `_extension1.so` from it.
	When creating `_extension1.so` link it to the libraries named by the CMake variables `OOF2COMMON` and `OOF2ENGINE`.
	Search these directories for C++ header files. The current source directory, the build directory, and the Python include directory are included automatically.
	These C++ files from the current source directory will be compiled, along with the C++ file generated by swig. All of them will be combined to create `_extension1.so`.
	The outputs, `extension1.py` and `_extension1.so` will be installed in the `modules` subdirectory inside the project's installation directory.

^[64]The library name might vary depending on your operating system.

^[65]This can happen if the project has mulitple subdirectories and there are swig files with the same name in different directories.


Tools for Building Extensions		oof2-extension-setup