UseSWIG

This file provides support for SWIG. It is assumed that FindSWIG module has already been loaded.

CMake Commands

The following command is defined for use with SWIG:

swig_add_library

New in version 3.8.

Define swig module with given name and specified language:

swig_add_library(<name>
                 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
                 LANGUAGE <language>
                 [NO_PROXY]
                 [OUTPUT_DIR <directory>]
                 [OUTFILE_DIR <directory>]
                 SOURCES <file>...
                )

Targets created with the swig_add_library command have the same capabilities as targets created with the add_library() command, so those targets can be used with any command expecting a target (e.g. target_link_libraries()).

Changed in version 3.13: This command creates a target with the specified <name> when policy CMP0078 is set to NEW. Otherwise, the legacy behavior will choose a different target name and store it in the SWIG_MODULE_<name>_REAL_NAME variable.

Changed in version 3.15: Alternate library name (set with the OUTPUT_NAME property, for example) will be passed on to Python and CSharp wrapper libraries.

Changed in version 3.21: Generated library use standard naming conventions for CSharp language when policy CMP0122 is set to NEW. Otherwise, the legacy behavior is applied.

Note

For multi-config generators, this module does not support configuration-specific files generated by SWIG. All build configurations must result in the same generated source file.

Note

For Makefile Generators, if, for some sources, the USE_SWIG_DEPENDENCIES property is FALSE, swig_add_library does not track file dependencies, so depending on the <name>_swig_compilation custom target is required for targets which require the swig-generated files to exist. Other generators may depend on the source files that would be generated by SWIG.

TYPE

SHARED, MODULE and STATIC have the same semantic as for the add_library() command. If USE_BUILD_SHARED_LIBS is specified, the library type will be STATIC or SHARED based on whether the current value of the BUILD_SHARED_LIBS variable is ON. If no type is specified, MODULE will be used.

LANGUAGE

Specify the target language.

New in version 3.1: Go and Lua language support.

New in version 3.2: R language support.

New in version 3.18: Fortran language support.

NO_PROXY

New in version 3.12.

Prevent the generation of the wrapper layer (swig -noproxy option).

OUTPUT_DIR

New in version 3.12.

Specify where to write the language specific files (swig -outdir option). If not given, the CMAKE_SWIG_OUTDIR variable will be used. If neither is specified, the default depends on the value of the UseSWIG_MODULE_VERSION variable as follows:

  • If UseSWIG_MODULE_VERSION is 1 or is undefined, output is written to the CMAKE_CURRENT_BINARY_DIR directory.

  • If UseSWIG_MODULE_VERSION is 2, a dedicated directory will be used. The path of this directory can be retrieved from the SWIG_SUPPORT_FILES_DIRECTORY target property.

OUTFILE_DIR

New in version 3.12.

Specify an output directory name where the generated source file will be placed (swig -o option). If not specified, the SWIG_OUTFILE_DIR variable will be used. If neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is used instead.

SOURCES

List of sources for the library. Files with extension .i will be identified as sources for the SWIG tool. Other files will be handled in the standard way.

New in version 3.14: This behavior can be overridden by specifying the variable SWIG_SOURCE_FILE_EXTENSIONS.

Note

If UseSWIG_MODULE_VERSION is set to 2, it is strongly recommended to use a dedicated directory unique to the target when either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR variable are specified. The output directory contents are erased as part of the target build, so to prevent interference between targets or losing other important files, each target should have its own dedicated output directory.

Properties on Source Files

Source file properties on module files must be set before the invocation of the swig_add_library command to specify special behavior of SWIG and ensure generated files will receive the required settings.

CPLUSPLUS

Call SWIG in c++ mode. For example:

set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
SWIG_FLAGS

Deprecated since version 3.12: Replaced with the fine-grained properties that follow.

Pass custom flags to the SWIG executable.

INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS

New in version 3.12.

Add custom flags to SWIG compiler and have same semantic as properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS.

USE_TARGET_INCLUDE_DIRECTORIES

New in version 3.13.

If set to TRUE, contents of target property INCLUDE_DIRECTORIES will be forwarded to SWIG compiler. If set to FALSE target property INCLUDE_DIRECTORIES will be ignored. If not set, target property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.

GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENERATED_COMPILE_OPTIONS

New in version 3.12.

Add custom flags to the C/C++ generated source. They will fill, respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS of generated C/C++ file.

DEPENDS

New in version 3.12.

Specify additional dependencies to the source file.

USE_SWIG_DEPENDENCIES

New in version 3.20.

If set to TRUE, implicit dependencies are generated by the swig tool itself. This property is only meaningful for Makefile, Ninja, Xcode, and Visual Studio (Visual Studio 12 2013 and above) generators. Default value is FALSE.

New in version 3.21: Added the support of Xcode generator.

New in version 3.22: Added the support of Visual Studio Generators.

SWIG_MODULE_NAME

Specify the actual import name of the module in the target language. This is required if it cannot be scanned automatically from source or different from the module file basename. For example:

set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)

Changed in version 3.14: If policy CMP0086 is set to NEW, -module <module_name> is passed to SWIG compiler.

OUTPUT_DIR

New in version 3.19.

Specify where to write the language specific files (swig -outdir option) for the considered source file. If not specified, the other ways to define the output directory applies (see OUTPUT_DIR option of swig_add_library() command).

OUTFILE_DIR

New in version 3.19.

Specify an output directory where the generated source file will be placed (swig -o option) for the considered source file. If not specified, OUTPUT_DIR source property will be used. If neither are specified, the other ways to define output file directory applies (see OUTFILE_DIR option of swig_add_library() command).

Properties on Targets

Target library properties can be set to apply same configuration to all SWIG input files.

SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COMPILE_OPTIONS

New in version 3.12.

These properties will be applied to all SWIG input files and have same semantic as target properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS.

set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
SWIG_USE_TARGET_INCLUDE_DIRECTORIES

New in version 3.13.

If set to TRUE, contents of target property INCLUDE_DIRECTORIES will be forwarded to SWIG compiler. If set to FALSE or not defined, target property INCLUDE_DIRECTORIES will be ignored. This behavior can be overridden by specifying source property USE_TARGET_INCLUDE_DIRECTORIES.

SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS and SWIG_GENERATED_COMPILE_OPTIONS

New in version 3.12.

These properties will populate, respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of all generated C/C++ files.

SWIG_DEPENDS

New in version 3.12.

Add dependencies to all SWIG input files.

Read-only Target Properties

The following target properties are output properties and can be used to get information about support files generated by SWIG interface compilation.

SWIG_SUPPORT_FILES

New in version 3.12.

This output property list of wrapper files generated during SWIG compilation.

set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)

Note

Only most principal support files are listed. In case some advanced features of SWIG are used (for example %template), associated support files may not be listed. Prefer to use the SWIG_SUPPORT_FILES_DIRECTORY property to handle support files.

SWIG_SUPPORT_FILES_DIRECTORY

New in version 3.12.

This output property specifies the directory where support files will be generated.

Note

When source property OUTPUT_DIR is defined, multiple directories can be specified as part of SWIG_SUPPORT_FILES_DIRECTORY.

CMake Variables

Some variables can be set to customize the behavior of swig_add_library as well as SWIG:

UseSWIG_MODULE_VERSION

New in version 3.12.

Specify different behaviors for UseSWIG module.

  • Set to 1 or undefined: Legacy behavior is applied.

  • Set to 2: A new strategy is applied regarding support files: the output directory of support files is erased before SWIG interface compilation.

CMAKE_SWIG_FLAGS

Add flags to all swig calls.

CMAKE_SWIG_OUTDIR

Specify where to write the language specific files (swig -outdir option).

SWIG_OUTFILE_DIR

New in version 3.8.

Specify an output directory name where the generated source file will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.

SWIG_MODULE_<name>_EXTRA_DEPS

Specify extra dependencies for the generated module for <name>.

SWIG_SOURCE_FILE_EXTENSIONS

New in version 3.14.

Specify a list of source file extensions to override the default behavior of considering only .i files as sources for the SWIG tool. For example:

set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
SWIG_USE_SWIG_DEPENDENCIES

New in version 3.20.

If set to TRUE, implicit dependencies are generated by the swig tool itself. This variable is only meaningful for Makefile, Ninja, Xcode, and Visual Studio (Visual Studio 12 2013 and above) generators. Default value is FALSE.

Source file property USE_SWIG_DEPENDENCIES, if not defined, will be initialized with the value of this variable.

New in version 3.21: Added the support of Xcode generator.

New in version 3.22: Added the support of Visual Studio Generators.

Deprecated Commands

Deprecated since version 3.13: Use target_link_libraries() with the standard target name, or with ${SWIG_MODULE_<name>_REAL_NAME} for legacy target naming.

Link libraries to swig module:

swig_link_libraries(<name> <item>...)

This command has same capabilities as target_link_libraries() command.

Note

When policy CMP0078 is set to NEW, swig_add_library() creates a standard target with the specified <name> and target_link_libraries() must be used instead of this command.

With the legacy behavior (when CMP0078 is set to OLD and the UseSWIG_TARGET_NAME_PREFERENCE variable is set to "LEGACY", or in CMake versions prior to 3.12), it is preferable to use target_link_libraries(${SWIG_MODULE_<name>_REAL_NAME} ...) instead of this command.