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 版本中變更：當原則
CMP0078設定為NEW時，此指令會建立一個具有指定<name>的目標。否則，舊版行為將選擇不同的目標名稱並將其儲存在SWIG_MODULE_<name>_REAL_NAME變數中。在 3.15 版本中變更：替代程式庫名稱（例如，使用
OUTPUT_NAME屬性設定）將傳遞給Python和CSharp包裝器程式庫。在 3.21 版本中變更：當原則
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++ 原始碼新增自訂旗標。它們將會分別填入產生的 C/C++ 檔案的屬性
INCLUDE_DIRECTORIES、COMPILE_DEFINITIONS和COMPILE_OPTIONS。DEPENDS在 3.12 版本中新增。
指定原始碼檔案的其他相依性。
USE_SWIG_DEPENDENCIES在 3.20 版本中新增。
若設定為
TRUE，隱含的相依性將由swig工具本身產生。這個屬性僅對於 Makefile、 Ninja、Xcode和 Visual Studio 產生器有意義。預設值為FALSE。在 3.21 版本中新增： 新增了對
Xcode產生器的支援。在 3.22 版本中新增： 新增了對 Visual Studio Generators 的支援。
SWIG_MODULE_NAME指定目標語言中模組的實際匯入名稱。如果無法從原始碼自動掃描或與模組檔案基本名稱不同，則這是必要的。例如
set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
在 3.14 版本中變更：如果政策
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 Generators 的支援。
已淘汰的命令¶
- swig_link_libraries¶
自 3.13 版本起已淘汰： 使用
target_link_libraries()和標準目標名稱，或是使用${SWIG_MODULE_<name>_REAL_NAME}進行舊版目標命名。將程式庫連結至 swig 模組
swig_link_libraries(<name> <item>...)
此命令的功能與
target_link_libraries()命令相同。注意
當政策
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} ...)來取代此命令。