UseSWIG¶
This file provides support for SWIG. It is assumed that FindSWIG
module has already been loaded.
Defines the following command for use with SWIG:
-
swig_add_library¶ 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 theadd_library()command, so those targets can be used with any command expecting a target (e.g.target_link_libraries()).Note
This command creates a target with the specified
<name>when policyCMP0078is set toNEW. Otherwise, the legacy behavior will choose a different target name and store it in theSWIG_MODULE_<name>_REAL_NAMEvariable.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 Make-based generators,
swig_add_librarydoes not track file dependencies, so depending on the<name>_swig_compilationcustom target is required for targets which require theswig-generated files to exist. Other generators may depend on the source files that would be generated by SWIG.TYPESHARED,MODULEandSTATIChave the same semantic as for theadd_library()command. IfUSE_BUILD_SHARED_LIBSis specified, the library type will beSTATICorSHAREDbased on whether the current value of theBUILD_SHARED_LIBSvariable isON. If no type is specified,MODULEwill be used.LANGUAGESpecify the target language.
NO_PROXYPrevent the generation of the wrapper layer (swig
-noproxyoption).OUTPUT_DIRSpecify where to write the language specific files (swig
-outdiroption). If not given, theCMAKE_SWIG_OUTDIRvariable will be used. If neither is specified, the default depends on the value of theUseSWIG_MODULE_VERSIONvariable as follows:If
UseSWIG_MODULE_VERSIONis 1 or is undefined, output is written to theCMAKE_CURRENT_BINARY_DIRdirectory.If
UseSWIG_MODULE_VERSIONis 2, a dedicated directory will be used. The path of this directory can be retrieved from theSWIG_SUPPORT_FILES_DIRECTORYtarget property.
OUTFILE_DIRSpecify an output directory name where the generated source file will be placed (swig
-ooption). If not specified, theSWIG_OUTFILE_DIRvariable will be used. If neither is specified,OUTPUT_DIRorCMAKE_SWIG_OUTDIRis used instead.SOURCESList of sources for the library. Files with extension
.iwill be identified as sources for theSWIGtool. Other files will be handled in the standard way. This behavior can be overridden by specifying the variableSWIG_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 theOUTPUT_DIRoption or theCMAKE_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.
-
swig_link_libraries¶ Link libraries to swig module:
swig_link_libraries(<name> <item>...)
This command has same capabilities as
target_link_libraries()command.Note
If variable
UseSWIG_TARGET_NAME_PREFERENCEis set toSTANDARD, this command is deprecated andtarget_link_libraries()command must be used instead.
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.
CPLUSPLUSCall SWIG in c++ mode. For example:
set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
INCLUDE_DIRECTORIES,COMPILE_DEFINITIONSandCOMPILE_OPTIONSAdd custom flags to SWIG compiler and have same semantic as properties
INCLUDE_DIRECTORIES,COMPILE_DEFINITIONSandCOMPILE_OPTIONS.USE_TARGET_INCLUDE_DIRECTORIESIf set to
TRUE, contents of target propertyINCLUDE_DIRECTORIESwill be forwarded toSWIGcompiler. If set toFALSEtarget propertyINCLUDE_DIRECTORIESwill be ignored. If not set, target propertySWIG_USE_TARGET_INCLUDE_DIRECTORIESwill be considered.GENERATED_INCLUDE_DIRECTORIES,GENERATED_COMPILE_DEFINITIONSandGENERATED_COMPILE_OPTIONSAdd custom flags to the C/C++ generated source. They will fill, respectively, properties
INCLUDE_DIRECTORIES,COMPILE_DEFINITIONSandCOMPILE_OPTIONSof generated C/C++ file.DEPENDSSpecify additional dependencies to the source file.
SWIG_MODULE_NAMESpecify 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)
Note
If policy
CMP0086is set toNEW,-module <module_name>is passed toSWIGcompiler.OUTPUT_DIRSpecify 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 (seeOUTPUT_DIRoption ofswig_add_library()command).OUTFILE_DIRSpecify 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 (seeOUTFILE_DIRoption ofswig_add_library()command).
Target library properties can be set to apply same configuration to all SWIG input files.
SWIG_INCLUDE_DIRECTORIES,SWIG_COMPILE_DEFINITIONSandSWIG_COMPILE_OPTIONSThese properties will be applied to all SWIG input files and have same semantic as target properties
INCLUDE_DIRECTORIES,COMPILE_DEFINITIONSandCOMPILE_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_DIRECTORIESIf set to
TRUE, contents of target propertyINCLUDE_DIRECTORIESwill be forwarded toSWIGcompiler. If set toFALSEor not defined, target propertyINCLUDE_DIRECTORIESwill be ignored. This behavior can be overridden by specifying source propertyUSE_TARGET_INCLUDE_DIRECTORIES.SWIG_GENERATED_INCLUDE_DIRECTORIES,SWIG_GENERATED_COMPILE_DEFINITIONSandSWIG_GENERATED_COMPILE_OPTIONSThese properties will populate, respectively, properties
INCLUDE_DIRECTORIES,COMPILE_DEFINITIONSandCOMPILE_FLAGSof all generated C/C++ files.SWIG_DEPENDSAdd dependencies to all SWIG input files.
The following target properties are output properties and can be used to get
information about support files generated by SWIG interface compilation.
SWIG_SUPPORT_FILESThis 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 theSWIG_SUPPORT_FILES_DIRECTORYproperty to handle support files.SWIG_SUPPORT_FILES_DIRECTORYThis 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 ofSWIG_SUPPORT_FILES_DIRECTORY.
Some variables can be set to customize the behavior of swig_add_library
as well as SWIG:
UseSWIG_MODULE_VERSIONSpecify 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_FLAGSAdd flags to all swig calls.
CMAKE_SWIG_OUTDIRSpecify where to write the language specific files (swig
-outdiroption).SWIG_OUTFILE_DIRSpecify an output directory name where the generated source file will be placed. If not specified,
CMAKE_SWIG_OUTDIRis used.SWIG_MODULE_<name>_EXTRA_DEPSSpecify extra dependencies for the generated module for
<name>.SWIG_SOURCE_FILE_EXTENSIONSSpecify a list of source file extensions to override the default behavior of considering only
.ifiles as sources for theSWIGtool. For example:set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")