CPack WIX 產生器¶

使用 WiX Toolset 來產生 Windows Installer .msi 資料庫。

在 3.7 版本中新增: 現在支援 CPACK_COMPONENT_<compName>_DISABLED 變數。

WiX Toolsets¶

CPack 根據 CPACK_WIX_VERSION 變數，選擇以下其中一個 WiX Toolset 變體

WiX .NET 工具
WiX Toolset v3

WiX .NET 工具¶

使用以下工具執行封裝

wix build

將 WiX 原始程式檔直接建置成 Windows Installer .msi 資料庫。

可以使用工具特定的變數自訂調用

CPACK_WIX_BUILD_EXTENSIONS
CPACK_WIX_BUILD_EXTRA_FLAGS

WiX 擴充功能必須以 WixToolset.<Name>.wixext 的形式命名。

CPack 預期 wix .NET 工具可供命令列使用，並已安裝任何所需的 WiX 擴充功能。請確保 wix 版本與 CPACK_WIX_VERSION 相容，且 WiX 擴充功能版本與 wix 工具版本相符。例如

使用 dotnet 安裝 wix 命令列工具。

要為目前使用者全域安裝 wix
dotnet tool install --global wix --version 4.0.4
這會將 wix.exe 放置在 %USERPROFILE%\.dotnet\tools 中，並將該目錄新增至目前使用者的 PATH 環境變數。

或者，要在特定路徑中安裝 wix，例如在 c:\WiX 中
dotnet tool install --tool-path c:\WiX wix --version 4.0.4
這會將 wix.exe 放置在 c:\WiX 中，但 _不會_ 將其新增至目前使用者的 PATH 環境變數。WIX 環境變數可以設定來告知 CPack 在哪裡找到工具，例如 set WIX=c:\WiX。

新增 CPack 預設 WiX 範本所需的 WiX UI 擴充功能

wix extension add --global WixToolset.UI.wixext/4.0.4
全域新增的擴充功能會儲存在 %USERPROFILE%\.wix 中，或者，如果設定 WIX_EXTENSIONS 環境變數，則會儲存在 %WIX_EXTENSIONS%\.wix 中。

WiX Toolset v3¶

使用以下工具執行封裝

candle

將 WiX 原始程式檔編譯成 .wixobj 檔案。

可以使用工具特定的變數自訂調用

CPACK_WIX_CANDLE_EXTENSIONS
CPACK_WIX_CANDLE_EXTRA_FLAGS

light

將 .wixobj 檔案連結到 Windows Installer .msi 資料庫。

可以使用工具特定的變數自訂調用

CPACK_WIX_LIGHT_EXTENSIONS
CPACK_WIX_LIGHT_EXTRA_FLAGS

CPack 會根據需要調用這兩個工具。中繼 .wixobj 檔案會被視為實作細節。

WiX 擴充功能必須以 Wix<Name>Extension 的形式命名。

CPack 預期上述工具可透過 PATH 供命令列使用。或者，如果設定 WIX 環境變數，CPack 會在 %WIX% 和 %WIX%\bin 中尋找工具。

CPack WIX 產生器特定的變數¶

以下變數是 Windows 上使用 WiX 建置的安裝程式所特有的。

CPACK_WIX_VERSION¶

在 3.30 版本中新增。

指定寫入組態的 WiX Toolset 版本。該值必須是其中一個

4: 使用 WiX .NET 工具封裝。
3: 使用 WiX Toolset v3 封裝。這是預設值。

CPACK_WIX_UPGRADE_GUID¶

升級 GUID (Product/@UpgradeCode)

除非明確提供，否則會自動產生。

應該明確設定為常數產生的全域唯一識別碼 (GUID)，以允許您的安裝程式取代使用相同 GUID 的現有安裝。

例如，您可以在 CMakeLists.txt 中明確將此變數設定為預設產生的值。您不應使用您自己未產生的 GUID 或可能屬於其他專案的 GUID。

GUID 應具有以下固定長度語法

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

(每個 X 代表大寫的十六進位數字)

CPACK_WIX_PRODUCT_GUID¶

產品 GUID (Product/@Id)

除非明確提供，否則會自動產生。

如果明確提供，這會設定您安裝程式的產品 ID。

如果安裝程式偵測到使用相同 GUID 的先前存在安裝，則會中止。

GUID 應使用 CPACK_WIX_UPGRADE_GUID 所述的語法。

CPACK_WIX_LICENSE_RTF¶

RTF 授權檔案

如果 CPACK_RESOURCE_FILE_LICENSE 具有 .rtf 擴充功能，則會依原樣使用。

如果 CPACK_RESOURCE_FILE_LICENSE 具有 .txt 擴充功能，則 WIX 產生器會將其隱式轉換為 RTF。.txt 檔案的預期編碼為 UTF-8。

使用 CPACK_WIX_LICENSE_RTF，您可以在 CPACK_RESOURCE_FILE_LICENSE 使用不支援的格式或 .txt -> .rtf 轉換未如預期運作時，覆寫 WIX 產生器使用的授權檔案。

CPACK_WIX_PRODUCT_ICON¶

在「新增/移除程式」中程式名稱旁邊顯示的圖示。

如果已設定，則會使用此圖示來取代預設圖示。

CPACK_WIX_UI_REF¶

指定 WiX UI 擴充功能的對話方塊集

使用 WiX .NET 工具，這是預設 WiX 範本中 <ui:WixUI> 元素的 ID。
使用 WiX Toolset v3，這是預設 WiX 範本中 <UIRef> 元素的 ID。

如果未定義任何 CPack 元件，則預設值為 WixUI_InstallDir，否則為 WixUI_FeatureTree。

CPACK_WIX_UI_BANNER¶

點陣圖將顯示在歡迎和完成對話方塊以外的所有安裝程式頁面頂端。

如果已設定，此映像將取代預設橫幅映像。

此映像必須為 493 x 58 像素。

CPACK_WIX_UI_DIALOG¶

歡迎和完成對話方塊上使用的背景點陣圖。

如果設定此變數，安裝程式將取代預設對話方塊映像。

此映像必須為 493 x 312 像素。

CPACK_WIX_PROGRAM_MENU_FOLDER¶

啟動器的「開始」功能表資料夾名稱。

如果未設定此變數，則會使用 CPACK_PACKAGE_NAME 初始化。

在 3.16 版本中新增: 如果此變數設定為 .，則應用程式捷徑會直接在「開始」功能表中建立，並且會省略解除安裝程式捷徑。

CPACK_WIX_CULTURES¶

安裝程式的語言

語言會編譯到 Wix UI 擴充功能程式庫中。若要使用它們，只需提供文化名稱即可。如果您在以逗號或分號分隔的清單中指定多個文化識別碼，則會使用找到的第一個。您可以在以下網址找到支援的語言清單：https://wixtoolset.org/docs/v3/wixui/wixui_localization/

CPACK_WIX_TEMPLATE¶

WiX 產生的範本檔案

如果設定此變數，將會使用指定的範本來產生 WiX wxs 檔案。如果需要進一步自訂輸出，則應使用此選項。範本內容將會覆蓋大多數 CPACK_WIX_ 變數的效果。

如果未設定此變數，則會使用 CMake 內建的預設 MSI 範本。

CPACK_WIX_PATCH_FILE¶

可選的 XML 檔案清單，其中包含要插入到產生的 WiX 原始碼中的片段。

在 3.5 版本中新增: 支援列出多個修補檔案。

這個可選的變數可用來指定一個 XML 檔案，WIX 產生器將使用該檔案將片段注入到其產生的原始碼檔案中。

CPack WIX 產生器理解的修補檔案大致遵循此 RELAX NG 精簡結構描述

start = CPackWiXPatch

CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* }

CPackWiXFragment = element CPackWiXFragment
{
    attribute Id { string },
    fragmentContent*
}

fragmentContent = element * - CPackWiXFragment
{
    (attribute * { text } | text | fragmentContent)*
}

目前，片段可以注入到大多數 Component、File、Directory 和 Feature 元素中。

在 3.3 版本中新增: 可以使用以下額外的特殊 ID

#PRODUCT 用於 <Product> 元素。
#PRODUCTFEATURE 用於根 <Feature> 元素。

在 3.7 版本中新增: 支援修補任意 <Feature> 元素。

在 3.9 版本中新增: 允許設定額外的屬性。

以下範例說明其運作方式。

假設 WIX 產生器建立以下 XML 元素

<Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>

可以使用以下 XML 修補檔案將 Environment 元素注入其中

<CPackWiXPatch>
  <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe">
    <Environment Id="MyEnvironment" Action="set"
      Name="MyVariableName" Value="MyVariableValue"/>
  </CPackWiXFragment>
</CPackWiXPatch>

CPACK_WIX_EXTRA_SOURCES¶

額外的 WiX 原始碼檔案

此變數提供一個可選的額外 WiX 原始碼檔案清單 (.wxs)，這些檔案應該被編譯和連結。路徑必須是絕對路徑。

CPACK_WIX_EXTRA_OBJECTS¶

額外的 WiX 物件檔案或程式庫，與 WiX Toolset v3 一起使用。

此變數提供一個可選的額外 WiX 物件 (.wixobj) 和/或 WiX 程式庫 (.wixlib) 檔案清單。路徑必須是絕對路徑。

CPACK_WIX_EXTENSIONS¶: 指定 WiX 工具的額外擴充功能清單。請參閱 WiX Toolsets 以了解擴充功能命名模式。

CPACK_WIX_<TOOL>_EXTENSIONS¶: 指定特定 WiX 工具的額外擴充功能清單。請參閱 WiX Toolsets 以了解可能的 <TOOL> 名稱。

CPACK_WIX_<TOOL>_EXTRA_FLAGS¶

指定特定 WiX 工具的額外命令列旗標清單。請參閱 WiX Toolsets 以了解可能的 <TOOL> 名稱。

請自行承擔使用風險。未來版本的 CPack 可能會產生與您自己的旗標衝突的旗標。

CPACK_WIX_CMAKE_PACKAGE_REGISTRY¶

如果設定此變數，產生的安裝程式將會在 Windows 登錄機碼 HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName> 中建立一個項目。<PackageName> 的值由此變數提供。

假設您也安裝了 CMake 組態檔，這將允許其他 CMake 專案使用 find_package() 命令來尋找您的套件。

CPACK_WIX_PROPERTY_<PROPERTY>¶

在 3.1 版本中新增。

此變數可用來提供 Windows Installer 屬性 <PROPERTY> 的值

以下清單包含一些範例屬性，可用來自訂「程式和功能」（也稱為「新增或移除程式」）下的資訊

ARPCOMMENTS - 註解
ARPHELPLINK - 說明和支援資訊 URL
ARPURLINFOABOUT - 一般資訊 URL
ARPURLUPDATEINFO - 更新資訊 URL
ARPHELPTELEPHONE - 說明和支援電話號碼
ARPSIZE - 應用程式的大小（以 KB 為單位）

CPACK_WIX_ROOT_FEATURE_TITLE¶: 在 3.7 版本中新增。

設定 WIX 安裝程式中根安裝功能表的名稱。與元件的 CPACK_COMPONENT_<compName>_DISPLAY_NAME 相同。

CPACK_WIX_ROOT_FEATURE_DESCRIPTION¶: 在 3.7 版本中新增。

設定 WIX 安裝程式中根安裝功能表的描述。與元件的 CPACK_COMPONENT_<compName>_DESCRIPTION 相同。

CPACK_WIX_SKIP_PROGRAM_FOLDER¶: 在 3.7 版本中新增。

如果此變數設定為 true，則產生的套件的預設安裝位置將直接是 CPACK_PACKAGE_INSTALL_DIRECTORY。安裝位置將不會位於 ProgramFiles 或 ProgramFiles64 下方的相對位置。

注意

使用此功能建立的安裝程式不會考慮建立安裝程式的系統與可能使用安裝程式的系統之間的差異。

因此，安裝程式可能會嘗試安裝到不可用或非預期的磁碟機上，或安裝到不符合執行安裝的系統的本地化或慣例的路徑上。

CPACK_WIX_ROOT_FOLDER_ID¶

在 3.9 版本中新增。

此變數允許指定自訂根資料夾 ID。產生器特定的 <64> 符記可用於 32 位元和 64 位元變體的資料夾 ID。在 32 位元組建中，符記將展開為空，而在 64 位元組建中，它將展開為 64。

如果未設定，產生的安裝程式預設會安裝到 ProgramFiles<64>Folder。

CPACK_WIX_ROOT¶

此變數可選擇性地設定為自訂 WiX Toolset 安裝的根目錄。

如果未指定，CPack 將嘗試透過 WIX 環境變數來尋找 WiX Toolset 安裝。

CPACK_WIX_CUSTOM_XMLNS¶: 在 3.19 版本中新增。

此變數提供使用 WiX 擴充功能所必需的自訂命名空間宣告清單。每個宣告的格式應為 name=url，其中 name 是沒有通常的 xmlns: 前置詞的純命名空間，而 url 是未加引號的命名空間 url。可以在此處找到常用的 WiX 結構描述清單：https://wixtoolset.org/docs/v3/xsd/

CPACK_WIX_SKIP_WIX_UI_EXTENSION¶: 在 3.23 版本中新增。

如果此變數設定為 true，則會略過預設包含的 WiX UI 擴充功能，也就是說，不會將 -ext WixUIExtension 或 -ext WixToolset.UI.wixext 旗標傳遞給 WiX 工具。

CPACK_WIX_ARCHITECTURE¶

在 3.24 版本中新增。

此變數可選擇性地設定以指定安裝程式的目標架構。例如，可以設定為 x64 或 arm64。

如果未指定，CPack 將預設為 x64 或 x86。

CPACK_WIX_INSTALL_SCOPE¶

在 3.29 版本中新增。

此變數可選擇性地設定以指定安裝程式的 InstallScope

perMachine

建立一個為所有使用者安裝且需要管理員權限的安裝程式。安裝程式建立的「開始」功能表項目對所有使用者都可見。

這是預設值。請參閱原則 CMP0172。

perUser

尚未支援。這保留供未來使用。

NONE

建立一個沒有任何 InstallScope 屬性的安裝程式。

只有在未設定 CPACK_WIX_VERSION 或設定為 3 時才支援此功能。

自 3.29 版本起已棄用：此值僅為相容於 CPack 3.28 及更舊版本所使用的不一致行為。產生的安裝程式需要管理員權限，並安裝到系統範圍的 ProgramFiles 目錄，但開始選單項目和解除安裝程式註冊僅為目前使用者建立。

警告

若安裝程式在沒有任何 InstallScope 的情況下執行，則具有 InstallScope 的安裝程式無法乾淨地更新或取代該安裝。為了將專案的安裝程式從 NONE 轉換為 perMachine，後者的安裝程式應附帶指示，要求先手動解除安裝任何舊版本。

請參閱 https://wixtoolset.org/docs/v3/xsd/wix/package/

CPack WIX 產生器¶

WiX Toolsets¶

WiX .NET 工具¶

WiX Toolset v3¶

CPack WIX 產生器特定的變數¶

目錄

上一主題

下一主題

本頁