CPack WIX 產生器¶

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

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

WiX 工具組¶

CPack 根據 CPACK_WIX_VERSION 變數，選擇以下 WiX 工具組的其中一個變體

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。

新增 WiX UI 擴充功能，CPack 的預設 WiX 範本需要此擴充功能

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 應具有以下固定長度語法

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://docs.firegiant.com/wix3/wixui/wixui_localization/

CPACK_WIX_TEMPLATE¶

WiX 產生的範本檔案

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

如果未設定此變數，將使用 CMake 隨附的預設 MSI 範本。

CPACK_WIX_PATCH_FILE¶

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

版本 3.5 新增：支援列出多個修補程式檔案。

此可選變數可用於指定 WIX 產生器將用於將片段注入其產生的原始檔中的 XML 檔案。

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 Toolset v3 搭配使用的額外 WiX 物件檔案或程式庫。

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

CPACK_WIX_EXTENSIONS¶: 指定 WiX 工具的其他擴充功能清單。請參閱 WiX 工具組以取得擴充功能命名模式。

CPACK_WIX_<TOOL>_EXTENSIONS¶: 指定特定 WiX 工具的其他擴充功能清單。請參閱 WiX 工具組以取得可能的 <TOOL> 名稱。

CPACK_WIX_<TOOL>_EXTRA_FLAGS¶

指定特定 WiX 工具的其他命令列旗標清單。請參閱 WiX 工具組以取得可能的 <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://docs.firegiant.com/wix3/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://docs.firegiant.com/wix3/xsd/wix/package/

CPack WIX 產生器¶

WiX 工具組¶

WiX .NET 工具¶

WiX Toolset v3¶

CPack WIX 產生器特定的變數¶

目錄

上一主題

下一主題

本頁