UseSWIG¶
此檔案提供 SWIG 的支援。假設 FindSWIG 模組已載入。
CMake 命令¶
定義以下命令以用於 SWIG
- swig_add_library¶
在版本 3.8 中新增。
使用給定的名稱和指定的語言定義 swig 模組
swig_add_library(<name> [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>] LANGUAGE <language> [NO_PROXY] [OUTPUT_DIR <directory>] [OUTFILE_DIR <directory>] SOURCES <file>... )
使用
swig_add_library命令建立的目標具有與使用add_library()命令建立的目標相同的功能，因此這些目標可以與任何期望目標的命令一起使用（例如target_link_libraries()）。在版本 3.13 中變更：當 policy
CMP0078設定為NEW時，此命令會使用指定的<name>建立目標。否則，舊版行為將選擇不同的目標名稱並將其儲存在SWIG_MODULE_<name>_REAL_NAME變數中。在版本 3.15 中變更：替代的函式庫名稱（例如，使用
OUTPUT_NAME屬性設定）將傳遞給Python和CSharp包裝函式庫。在版本 3.21 中變更：當 policy
CMP0122設定為NEW時，產生的函式庫會使用CSharp語言的標準命名慣例。否則，將套用舊版行為。注意
對於多組態產生器，此模組不支援
SWIG產生的組態特定檔案。所有建置組態都必須產生相同的原始碼檔案。注意
對於 Makefile 產生器，如果對於某些來源，
USE_SWIG_DEPENDENCIES屬性為FALSE，則swig_add_library不會追蹤檔案相依性，因此對於需要swig產生的檔案存在的目標，需要依賴<name>_swig_compilation自訂目標。其他產生器可能依賴 SWIG 將產生的來源檔案。TYPESHARED、MODULE和STATIC與add_library()命令具有相同的語意。如果指定USE_BUILD_SHARED_LIBS，則函式庫類型將為STATIC或SHARED，具體取決於BUILD_SHARED_LIBS變數的目前值是否為ON。如果未指定類型，則將使用MODULE。LANGUAGE指定目標語言。
在版本 3.1 中新增：Go 和 Lua 語言支援。
在版本 3.2 中新增：R 語言支援。
在版本 3.18 中新增：Fortran 語言支援。
NO_PROXY在版本 3.12 中新增。
防止產生包裝函式層（swig
-noproxy選項）。OUTPUT_DIR在版本 3.12 中新增。
指定寫入語言特定檔案的位置（swig
-outdir選項）。如果未給定，將使用CMAKE_SWIG_OUTDIR變數。如果兩者都未指定，則預設值取決於UseSWIG_MODULE_VERSION變數的值，如下所示如果
UseSWIG_MODULE_VERSION為 1 或未定義，則輸出會寫入CMAKE_CURRENT_BINARY_DIR目錄。如果
UseSWIG_MODULE_VERSION為 2，則將使用專用目錄。此目錄的路徑可以從SWIG_SUPPORT_FILES_DIRECTORY目標屬性中檢索。
OUTFILE_DIR在版本 3.12 中新增。
指定將放置產生來源檔案的輸出目錄名稱（swig
-o選項）。如果未指定，將使用SWIG_OUTFILE_DIR變數。如果兩者都未指定，則改為使用OUTPUT_DIR或CMAKE_SWIG_OUTDIR。SOURCES函式庫的來源清單。副檔名為
.i的檔案將被識別為SWIG工具的來源。其他檔案將以標準方式處理。在版本 3.14 中新增：此行為可以透過指定變數
SWIG_SOURCE_FILE_EXTENSIONS來覆寫。
注意
如果
UseSWIG_MODULE_VERSION設定為 2，則強烈建議在指定OUTPUT_DIR選項或CMAKE_SWIG_OUTDIR變數時，使用目標唯一的專用目錄。輸出目錄內容會在目標建置過程中清除，因此為了防止目標之間的干擾或遺失其他重要檔案，每個目標都應具有自己的專用輸出目錄。
來源檔案的屬性¶
模組檔案上的來源檔案屬性必須在呼叫 swig_add_library 命令之前設定，以指定 SWIG 的特殊行為，並確保產生的檔案將接收所需的設定。
CPLUSPLUS在 c++ 模式下呼叫 SWIG。例如
set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
SWIG_FLAGS在版本 3.12 中已棄用：已替換為後續的細粒度屬性。
將自訂旗標傳遞給 SWIG 可執行檔。
INCLUDE_DIRECTORIES、COMPILE_DEFINITIONS和COMPILE_OPTIONS在版本 3.12 中新增。
將自訂旗標新增至 SWIG 編譯器，並具有與屬性
INCLUDE_DIRECTORIES、COMPILE_DEFINITIONS和COMPILE_OPTIONS相同的語意。USE_TARGET_INCLUDE_DIRECTORIES在版本 3.13 中新增。
如果設定為
TRUE，則目標屬性INCLUDE_DIRECTORIES的內容將轉發到SWIG編譯器。如果設定為FALSE，則目標屬性INCLUDE_DIRECTORIES將被忽略。如果未設定，將考慮目標屬性SWIG_USE_TARGET_INCLUDE_DIRECTORIES。GENERATED_INCLUDE_DIRECTORIES、GENERATED_COMPILE_DEFINITIONS和GENERATED_COMPILE_OPTIONS在版本 3.12 中新增。
將自訂旗標新增至產生的 C/C++ 原始碼。它們將分別填入屬性
INCLUDE_DIRECTORIES、COMPILE_DEFINITIONS和COMPILE_OPTIONS的產生的 C/C++ 檔案。DEPENDS在版本 3.12 中新增。
指定來源檔案的其他相依性。
USE_SWIG_DEPENDENCIES在版本 3.20 中新增。
如果設定為
TRUE，則隱含相依性由swig工具本身產生。此屬性僅對 Makefile、Ninja、Xcode和 Visual Studio 產生器有意義。預設值為FALSE。在版本 3.21 中新增：新增了
Xcode產生器的支援。在版本 3.22 中新增：新增了 Visual Studio 產生器 的支援。
SWIG_MODULE_NAME指定目標語言中模組的實際匯入名稱。如果無法從來源自動掃描或與模組檔案基本名稱不同，則這是必需的。例如
set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
在版本 3.14 中變更：如果 policy
CMP0086設定為NEW，則-module <module_name>會傳遞到SWIG編譯器。OUTPUT_DIR在版本 3.19 中新增。
指定寫入考量來源檔案的語言特定檔案的位置（swig
-outdir選項）。如果未指定，則適用定義輸出目錄的其他方式（請參閱swig_add_library()命令的OUTPUT_DIR選項）。OUTFILE_DIR在版本 3.19 中新增。
指定放置考量來源檔案的產生來源檔案的輸出目錄（swig
-o選項）。如果未指定，將使用OUTPUT_DIR來源屬性。如果兩者都未指定，則適用定義輸出檔案目錄的其他方式（請參閱swig_add_library()命令的OUTFILE_DIR選項）。
目標的屬性¶
可以設定目標函式庫屬性，以將相同的組態套用於所有 SWIG 輸入檔案。
SWIG_INCLUDE_DIRECTORIES、SWIG_COMPILE_DEFINITIONS和SWIG_COMPILE_OPTIONS在版本 3.12 中新增。
這些屬性將套用於所有 SWIG 輸入檔案，並具有與目標屬性
INCLUDE_DIRECTORIES、COMPILE_DEFINITIONS和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在版本 3.13 中新增。
如果設定為
TRUE，則目標屬性INCLUDE_DIRECTORIES的內容將轉發到SWIG編譯器。如果設定為FALSE或未定義，則目標屬性INCLUDE_DIRECTORIES將被忽略。此行為可以透過指定來源屬性USE_TARGET_INCLUDE_DIRECTORIES來覆寫。SWIG_GENERATED_INCLUDE_DIRECTORIES、SWIG_GENERATED_COMPILE_DEFINITIONS和SWIG_GENERATED_COMPILE_OPTIONS在版本 3.12 中新增。
這些屬性將分別填入所有產生的 C/C++ 檔案的屬性
INCLUDE_DIRECTORIES、COMPILE_DEFINITIONS和COMPILE_FLAGS。SWIG_DEPENDS在版本 3.12 中新增。
將相依性新增至所有 SWIG 輸入檔案。
唯讀目標屬性¶
以下目標屬性是輸出屬性，可用於取得有關 SWIG 介面編譯產生的支援檔案的資訊。
SWIG_SUPPORT_FILES在版本 3.12 中新增。
此輸出屬性列出了 SWIG 編譯期間產生的包裝函式檔案。
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)
注意
僅列出最主要的支援檔案。如果使用
SWIG的某些進階功能（例如%template），則可能未列出相關聯的支援檔案。建議使用SWIG_SUPPORT_FILES_DIRECTORY屬性來處理支援檔案。SWIG_SUPPORT_FILES_DIRECTORY在版本 3.12 中新增。
此輸出屬性指定將產生支援檔案的目錄。
注意
當來源屬性
OUTPUT_DIR定義時，可以將多個目錄指定為SWIG_SUPPORT_FILES_DIRECTORY的一部分。
CMake 變數¶
可以設定某些變數來自訂 swig_add_library 以及 SWIG 的行為
UseSWIG_MODULE_VERSION在版本 3.12 中新增。
指定
UseSWIG模組的不同行為。設定為 1 或未定義：套用舊版行為。
設定為 2：對於支援檔案套用新的策略：支援檔案的輸出目錄在
SWIG介面編譯之前清除。
CMAKE_SWIG_FLAGS將旗標新增至所有 swig 呼叫。
CMAKE_SWIG_OUTDIR指定寫入語言特定檔案的位置（swig
-outdir選項）。SWIG_OUTFILE_DIR在版本 3.8 中新增。
指定將放置產生來源檔案的輸出目錄名稱。如果未指定，則使用
CMAKE_SWIG_OUTDIR。SWIG_MODULE_<name>_EXTRA_DEPS指定為
<name>產生的模組的其他相依性。SWIG_SOURCE_FILE_EXTENSIONS在版本 3.14 中新增。
指定來源檔案副檔名清單，以覆寫僅將
.i檔案視為SWIG工具來源的預設行為。例如set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
SWIG_USE_SWIG_DEPENDENCIES在版本 3.20 中新增。
如果設定為
TRUE，則隱含相依性由swig工具本身產生。此變數僅對 Makefile、Ninja、Xcode和 Visual Studio 產生器有意義。預設值為FALSE。來源檔案屬性
USE_SWIG_DEPENDENCIES（如果未定義）將使用此變數的值初始化。在版本 3.21 中新增：新增了
Xcode產生器的支援。在版本 3.22 中新增：新增了 Visual Studio 產生器 的支援。
已棄用的命令¶
- swig_link_libraries¶
在版本 3.13 中已棄用：將
target_link_libraries()與標準目標名稱一起使用，或將${SWIG_MODULE_<name>_REAL_NAME}用於舊版目標命名。將函式庫連結到 swig 模組
swig_link_libraries(<name> <item>...)
此命令具有與
target_link_libraries()命令相同的功能。注意
當 policy
CMP0078設定為NEW時，swig_add_library()會使用指定的<name>建立標準目標，並且必須使用target_link_libraries()而不是此命令。使用舊版行為（當
CMP0078設定為OLD且UseSWIG_TARGET_NAME_PREFERENCE變數設定為"LEGACY"，或在 3.12 之前的 CMake 版本中），最好使用target_link_libraries(${SWIG_MODULE_<name>_REAL_NAME} ...)而不是此命令。