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_librarycommand 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- CMP0078is set to- NEW. Otherwise, the legacy behavior will choose a different target name and store it in the- SWIG_MODULE_<name>_REAL_NAMEvariable.- Changed in version 3.15: Alternate library name (set with the - OUTPUT_NAMEproperty, for example) will be passed on to- Pythonand- CSharpwrapper libraries.- Changed in version 3.21: Generated library use standard naming conventions for - CSharplanguage when policy- CMP0122is 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_DEPENDENCIESproperty is- FALSE,- swig_add_librarydoes not track file dependencies, so depending on the- <name>_swig_compilationcustom 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,- MODULEand- STATIChave the same semantic as for the- add_library()command. If- USE_BUILD_SHARED_LIBSis specified, the library type will be- STATICor- SHAREDbased on whether the current value of the- BUILD_SHARED_LIBSvariable is- ON. If no type is specified,- MODULEwill 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 - -noproxyoption).
- OUTPUT_DIR
- New in version 3.12. - Specify where to write the language specific files (swig - -outdiroption). If not given, the- CMAKE_SWIG_OUTDIRvariable will be used. If neither is specified, the default depends on the value of the- UseSWIG_MODULE_VERSIONvariable as follows:- If - UseSWIG_MODULE_VERSIONis 1 or is undefined, output is written to the- CMAKE_CURRENT_BINARY_DIRdirectory.
- If - UseSWIG_MODULE_VERSIONis 2, a dedicated directory will be used. The path of this directory can be retrieved from the- SWIG_SUPPORT_FILES_DIRECTORYtarget property.
 
- OUTFILE_DIR
- New in version 3.12. - Specify an output directory name where the generated source file will be placed (swig - -ooption). If not specified, the- SWIG_OUTFILE_DIRvariable will be used. If neither is specified,- OUTPUT_DIRor- CMAKE_SWIG_OUTDIRis used instead.
- SOURCES
- List of sources for the library. Files with extension - .iwill be identified as sources for the- SWIGtool. 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_VERSIONis set to 2, it is strongly recommended to use a dedicated directory unique to the target when either the- OUTPUT_DIRoption or the- CMAKE_SWIG_OUTDIRvariable 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_DEFINITIONSand- COMPILE_OPTIONS
- New in version 3.12. - Add custom flags to SWIG compiler and have same semantic as properties - INCLUDE_DIRECTORIES,- COMPILE_DEFINITIONSand- COMPILE_OPTIONS.
- USE_TARGET_INCLUDE_DIRECTORIES
- New in version 3.13. - If set to - TRUE, contents of target property- INCLUDE_DIRECTORIESwill be forwarded to- SWIGcompiler. If set to- FALSEtarget property- INCLUDE_DIRECTORIESwill be ignored. If not set, target property- SWIG_USE_TARGET_INCLUDE_DIRECTORIESwill be considered.
- GENERATED_INCLUDE_DIRECTORIES,- GENERATED_COMPILE_DEFINITIONSand- 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_DEFINITIONSand- COMPILE_OPTIONSof 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- swigtool itself. This property is only meaningful for Makefile, Ninja,- Xcode, and Visual Studio (- Visual Studio 12 2013and above) generators. Default value is- FALSE.- New in version 3.21: Added the support of - Xcodegenerator.- 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 - CMP0086is set to- NEW,- -module <module_name>is passed to- SWIGcompiler.
- OUTPUT_DIR
- New in version 3.19. - Specify where to write the language specific files (swig - -outdiroption) for the considered source file. If not specified, the other ways to define the output directory applies (see- OUTPUT_DIRoption 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 - -ooption) for the considered source file. If not specified,- OUTPUT_DIRsource property will be used. If neither are specified, the other ways to define output file directory applies (see- OUTFILE_DIRoption 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_DEFINITIONSand- 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_DEFINITIONSand- 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_DIRECTORIESwill be forwarded to- SWIGcompiler. If set to- FALSEor not defined, target property- INCLUDE_DIRECTORIESwill be ignored. This behavior can be overridden by specifying source property- USE_TARGET_INCLUDE_DIRECTORIES.
- SWIG_GENERATED_INCLUDE_DIRECTORIES,- SWIG_GENERATED_COMPILE_DEFINITIONSand- SWIG_GENERATED_COMPILE_OPTIONS
- New in version 3.12. - These properties will populate, respectively, properties - INCLUDE_DIRECTORIES,- COMPILE_DEFINITIONSand- COMPILE_FLAGSof 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 - SWIGare used (for example- %template), associated support files may not be listed. Prefer to use the- SWIG_SUPPORT_FILES_DIRECTORYproperty 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_DIRis 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 - UseSWIGmodule.- 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 - SWIGinterface compilation.
 
- CMAKE_SWIG_FLAGS
- Add flags to all swig calls. 
- CMAKE_SWIG_OUTDIR
- Specify where to write the language specific files (swig - -outdiroption).
- 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_OUTDIRis 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 - .ifiles as sources for the- SWIGtool. 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- swigtool itself. This variable is only meaningful for Makefile, Ninja,- Xcode, and Visual Studio (- Visual Studio 12 2013and 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 - Xcodegenerator.- New in version 3.22: Added the support of Visual Studio Generators. 
Deprecated Commands¶
- swig_link_libraries¶
- 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 - CMP0078is 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 - CMP0078is set to- OLDand the- UseSWIG_TARGET_NAME_PREFERENCEvariable 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.
