# 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_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()`).

  Note

  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.

  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_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.

  `NO_PROXY`

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

  `OUTPUT_DIR`

    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`

    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. 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.

`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_PREFERENCE` is set to `STANDARD`, this command is deprecated and `target_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.

`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)

`INCLUDE_DIRECTORIES`, `COMPILE_DEFINITIONS` and `COMPILE_OPTIONS`

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

`USE_TARGET_INCLUDE_DIRECTORIES`

  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`

  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`

  Specify additional dependencies to the source file.

`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)

  Note

  If policy `CMP0086` is set to `NEW`, `-module <module_name>` is passed to `SWIG` compiler.

`OUTPUT_DIR`

  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`

  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).

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`

  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`

  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`

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

`SWIG_DEPENDS`

  Add 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_FILES`

  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`

  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`.

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

`UseSWIG_MODULE_VERSION`

  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`

  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`

  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")