TiXL 安装程序构建指南:基于 Inno Setup 的 Windows 发行包制作全流程
TiXL 安装程序构建指南:基于 Inno Setup 的 Windows 发行包制作全流程
TiXL 是一个开源的实时动态图形(realtime motion graphics)创作工具,其 Windows 发行版通过 Inno Setup 为核心,结合 installer.iss、build-release.ps1 等真实构建脚本,完整讲解从源码一键打包到最终安装程序落地的全过程。读完本文,你将掌握 TiXL 的发布流水线(发布 Player、编译 Editor、下载运行时依赖、打包安装包),理解 Inno Setup 脚本中各段落的实际作用,并能够独立构建出可分发、可安装的 TiXL 安装程序。
构建方式总览
TiXL 的安装程序构建只有一条主线:先完成 Release 构建,再用 Inno Setup 打包。整个流程分为两种执行方式:
- 一键构建(Quick Build):在 Inno Setup 中直接打开 Installer/installer.iss 并点击运行,脚本会在打包前自动触发
build-release.ps1完成全部编译工作; - 手动构建(Manual Build):不依赖 Inno Setup GUI,在命令行逐条执行
pwsh Installer/build-release.ps1,适合 CI 或需要单独控制各步骤的场景。
无论哪种方式,最终产物都输出到 Installer/Output/ 目录,即 Tixl-v4.2.0.5.exe 这样的安装程序文件。
快速构建(一键打包)
根据 Installer/README.md 的说明,最简单的构建路径是:
- 安装 Inno Setup(需要其官方最新版本);
- 用 Inno Setup 打开
Installer/installer.iss; - 点击 Play(运行)按钮。
这里的关键机制是 installer.iss 第 5 行的预编译钩子:
#expr Exec("powershell", "-ExecutionPolicy Bypass -File build-release.ps1", ".", 1, SW_SHOW)
#expr Exec 是 Inno Setup 的预处理器指令,它会在脚本编译(即点击 Play)时立即执行同目录下的 build-release.ps1,等待其完成后才继续打包。也就是说,编译安装脚本本身就等价于触发了一次完整发布构建——它发布 Player、编译整个解决方案、下载运行时依赖,最后将产物收进安装包。-ExecutionPolicy Bypass 用于绕过 PowerShell 的执行策略限制,"." 表示在脚本所在目录下执行。
手动构建(分步执行)
如果需要在没有 Inno Setup 的环境下构建(例如 CI),或者想单独观察每个阶段的输出,可以在仓库根目录执行:
pwsh Installer/build-release.ps1
build-release.ps1 从 $PSScriptRoot/.. 解析出仓库根目录后,依次执行三个阶段,并在任一步骤失败时抛出异常($ErrorActionPreference = "Stop")。
阶段一:依赖还原
dotnet restore "$root/t3.sln"
对整个解决方案 t3.sln 执行 NuGet 依赖还原,还原全部项目(Core、Editor、Player、Operators 各模块等)引用的包。CI 场景下若已单独还原,可用 -SkipRestore 开关跳过此步:
pwsh Installer/build-release.ps1 -SkipRestore
阶段二:发布 Player(自包含、win-x64)
dotnet publish "$root/Player/Player.csproj" -c Release -p:PublishProfile=FolderProfile
这一步以 Release 配置发布 Player/Player.csproj(TiXL 的实时渲染运行模块),关键参数来自 Player/Properties/PublishProfiles/FolderProfile.pubxml:
| 参数 | 值 | 作用 |
|---|---|---|
PublishDir |
bin\ReleasePublished |
发布输出目录,是后续 Editor 复制 Player 的来源 |
TargetFramework |
net10.0-windows |
目标框架为 .NET 10 + Windows 平台 |
RuntimeIdentifier |
win-x64 |
仅面向 64 位 Windows 运行时 |
SelfContained |
true |
自包含发布,携带 .NET 运行时,目标机器无需预装 .NET |
PublishSingleFile |
false |
不合并单文件,保持多文件布局便于增量复制 |
PublishReadyToRun |
false |
关闭 ReadyToRun 预编译 |
发布结果落在 Player/bin/ReleasePublished/,同时 Player.csproj 会把 ../Dependencies/**(bass.dll、Emgu.CV.dll、ffmpeg 相关等原生依赖)直接复制进输出目录,保证 Player 运行时所需的所有 DLL 齐备。
阶段三:Release 编译整个解决方案
dotnet build "$root/t3.sln" -c Release --no-restore
使用 Release 配置编译整个解决方案,其中最关键的是 Editor 在编译完成后会自动把已发布的 Player 复制到自己的输出目录。这一机制定义在 Editor/Editor.csproj 的 CopyPlayer 目标中:
<ItemGroup>
<Player Include="../Player/bin/ReleasePublished/**/*" Visible="false" />
</ItemGroup>
<Target Name="CopyPlayer" AfterTargets="AfterBuild">
<Copy SourceFiles="@(Player)" SkipUnchangedFiles="true" UseHardlinksIfPossible="true"
DestinationFiles="@(Player->'$(OutputPath)/Player/%(RecursiveDir)%(Filename)%(Extension)')" />
</Target>
CopyPlayer 挂接在 AfterBuild 之后,将上一阶段发布的 Player 全部文件复制到 Editor/bin/Release/net10.0-windows/Player/ 下,从而把 Editor 与 Player 合并进同一份构建产物。UseHardlinksIfPossible 在可行时使用硬链接以减少磁盘占用。
三个阶段完成后,build-release.ps1 还会检查并下载安装程序所需的运行时依赖(见下一节),最终打印 Release build complete.。
运行时依赖与自动下载
build-release.ps1 会在打包前确保两个运行时组件位于 Installer/dependencies/downloads/:
| 文件 | 来源 URL | 用途 |
|---|---|---|
dotnet-sdk-10.0.201-win-x64.exe |
https://builds.dotnet.microsoft.com/dotnet/Sdk/10.0.201/dotnet-sdk-10.0.201-win-x64.exe |
.NET SDK 10.0.201,为已安装的应用提供 .NET 运行时与开发支持 |
VC_redist.x64.exe |
https://aka.ms/vs/17/release/vc_redist.x64.exe |
Visual C++ 运行库,TiXL 依赖的原生库(BASS、ffmpeg、Emgu CV 等)需要它 |
下载采用"已存在则跳过"的策略(Test-Path 检查),避免重复下载;CI 与本地构建共用同一套逻辑。这两个安装包随后会被 installer.iss 的 [Files] 段临时放入 {tmp} 目录,安装完成后自动删除(Flags: deleteafterinstall),不会残留在用户机器上。
Inno Setup 脚本逐段解析
Installer/installer.iss 是安装程序的"总图纸",下面按段落拆解其作用。
版本与身份信息
#define MyAppVersion "4.2.0.5"
#define MyAppName "TiXL-v4.2.0.5"
#define MyAppPublisher "TiXL Community"
#define MyAppURL "https://tixl.app//"
#define MyAppExeName "TiXL.exe"
#define DotNetSdkInstaller "dotnet-sdk-10.0.201-win-x64.exe"
通过 #define 定义版本号、程序名、发布者、主可执行文件名等常量,脚本其余部分通过 {#MyAppVersion} 这类预处理器引用,保证版本号只改一处。
[Setup] 安装配置段
AppId=t3.tixl
AppName={#MyAppName}
AppVersion={#MyAppVersion}
DefaultDirName={autopf}\TiXL\TiXL {#MyAppVersion}
UsePreviousAppDir=no
AppId是应用的唯一标识(GUID),用于区分升级安装,官方注释强调不能与其他应用共用;- 默认安装目录为
{autopf}\TiXL\TiXL 4.2.0.5({autopf}在 64 位模式下指向Program Files),UsePreviousAppDir=no强制每次使用当前版本目录,避免多版本目录混淆; DisableProgramGroupPage=yes跳过开始菜单程序组选择页。
ArchitecturesAllowed=x64compatible
ArchitecturesInstallIn64BitMode=x64compatible
这两行将安装程序限定为 x64 及 Windows 11 on Arm 可运行,且强制以 64 位模式安装(使用原生 64 位 Program Files 目录与 64 位注册表视图),与 Player 的 win-x64 发布目标保持一致。PrivilegesRequired=lowest 默认被注释,即安装需要管理员权限(这样才能安装 .NET SDK 与 VC++ 运行库、启用 Windows 图形工具)。
OutputDir=.\Output
OutputBaseFilename=Tixl-v{#MyAppVersion}
SetupIconFile=..\EditorResources\images\t3.ico
Compression=lzma
SolidCompression=yes
WizardStyle=modern
安装包输出到 Output/,文件名为 Tixl-v4.2.0.5.exe,使用仓库自带的 t3.ico 作为图标,LZMA 实心压缩以减小体积,向导采用 modern 风格。
[Files] 文件清单段
[Files] 段决定安装包里装入哪些文件,是保证"开箱即用"的核心:
Source: "..\Editor\bin\Release\net10.0-windows\*"; DestDir: "{app}";
Excludes: "*.proxy.mov,*.waveform.png,*.waveform.jpg,win-x86,win-arm64,osx*,linux-*,android-*,maccatalyst-*,unix";
Flags: ignoreversion recursesubdirs
- 安装目录
{app}的完整内容来自 Editor 的 Release 构建输出(net10.0-windows目标框架目录),其中已包含 Editor、Player 及其全部 DLL 与资源; Excludes排除了代理视频(*.proxy.mov)、波形缓存(*.waveform.png/jpg)以及其它平台残留目录(win-x86、win-arm64、osx*、linux-*、android-*、maccatalyst-*、unix),保证安装包只携带 Windows x64 内容;ignoreversion表示安装时覆盖已存在的同名文件,recursesubdirs递归包含所有子目录。
Operator 缩略图单独从源码树拉取:
Source: "..\Operators\Lib\.meta\*"; DestDir: "{app}\Operators\lib\.meta"; ...
Source: "..\Operators\examples\.meta\*"; DestDir: "{app}\Operators\examples\.meta"; ...
脚本注释说明了原因:操作符缩略图(operator thumbnails)存放在源码项目旁的 .meta\Thumbnails\ 下,csproj 的内容规则不会把它们复制进构建输出,因此需要直接从源码树把它们装进发布包,否则用户界面中的算子图库会缺少缩略图。此处同样应用了平台排除规则。
运行时依赖装入 {tmp} 临时目录(安装完成后自动删除):
Source: "dependencies\downloads\{#DotNetSdkInstaller}"; DestDir: "{tmp}"; Flags: deleteafterinstall
Source: "dependencies\downloads\VC_redist.x64.exe"; DestDir: "{tmp}"; Flags: deleteafterinstall
Source: "dependencies\grafiktools.bat"; DestDir: "{tmp}"; Flags: deleteafterinstall ignoreversion
[Tasks] 与 [Icons] 段
[Tasks]
Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"; Flags: unchecked
提供"创建桌面快捷方式"可选任务(默认不勾选)。对应地,[Icons] 段创建开始菜单快捷方式(始终创建)与桌面快捷方式(仅当勾选任务时):
[Icons]
Name: "{autoprograms}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"
Name: "{autodesktop}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"; Tasks: desktopicon
[Code] 段:运行时前置检测
安装程序在真正安装依赖前,先用 Pascal 脚本检测目标机器是否已具备这些组件,避免重复安装:
function GetDotNetSdkInstalled: Boolean;
var
Key: string;
Versions: TArrayOfString;
I: Integer;
begin
Result := False;
Key := 'SOFTWARE\dotnet\Setup\InstalledVersions\x64\sdk';
if RegGetSubkeyNames(HKLM, Key, Versions) then
begin
for I := 0 to GetArrayLength(Versions) - 1 do
begin
if CompareStr(Versions[I], '10.0.201') = 0 then
begin
Result := True;
Exit;
end;
end;
end;
end;
function GetvcruntimeVersion: Boolean;
begin
Result := FileExists('C:\Windows\System32\vcruntime140.dll');
end;
GetDotNetSdkInstalled读取注册表HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x64\sdk的子键列表,精确匹配 SDK 版本10.0.201才判定已安装;GetvcruntimeVersion直接检查系统目录下是否存在vcruntime140.dll。
注意脚本中 [Run] 段的提示文本写着 "Install .NET 9 SDK",但实际检测与安装的是 .NET SDK 10.0.201(#define DotNetSdkInstaller 与注册表检测均以 10.0.201 为准),属于脚本中遗留的文案,请以实际版本号为准。
[Run] 段:安装后动作序列
安装文件复制完成后,[Run] 段按顺序执行四个动作:
Filename: "{tmp}\{#DotNetSdkInstaller}"; StatusMsg: "Install .NET 9 SDK"; Check: not GetDotNetSdkInstalled
Filename: "{tmp}\VC_redist.x64.exe"; StatusMsg: "Install Visual C++ Redistributable"; check: not GetvcruntimeVersion
Filename: "{tmp}\grafiktools.bat"; StatusMsg: "Start Windows Graphic Tools. This can take up to 10 minutes."; Flags: runhidden
Filename: "{app}\{#MyAppExeName}"; Description: "{cm:LaunchProgram,...}"; Flags: nowait postinstall skipifsilent
- 若未检测到 .NET SDK 10.0.201,静默安装随包携带的 SDK 安装器;
- 若缺少
vcruntime140.dll,安装 VC++ 运行库; - 隐藏运行 grafiktools.bat,内容为:
dism /online /add-capability /capabilityname:Tools.Graphics.DirectX~~~~0.0.1.0
该命令通过 DISM 在线启用 Windows 的 "Graphics Tools (DirectX)" 可选功能,TiXL 的实时图形渲染依赖此系统能力。脚本提示该步骤最长可能需要 10 分钟,runhidden 表示后台执行不弹窗;
4. 安装完成后立即启动 TiXL.exe(nowait 不等待程序退出、postinstall 在向导结束后执行、skipifsilent 在静默安装时跳过启动)。
输出产物与验证
安装程序构建完成后,在 Installer/Output/ 下生成 Tixl-v4.2.0.5.exe。一份完整可用的安装包应满足:
- 体积与内容:LZMA 实心压缩,内含 Editor 完整构建(含 Player)、Operator 缩略图
.meta目录,且不含代理视频、波形缓存与非 Windows 平台文件; - 目标机器前置条件:安装过程按需安装 .NET SDK 10.0.201、VC++ 运行库并启用 Graphics Tools,之后即可直接启动 TiXL;
- 安装位置:默认
Program Files\TiXL\TiXL 4.2.0.5,开始菜单与桌面(可选)快捷方式指向TiXL.exe。
常见问题与注意事项
- 一键构建卡在 PowerShell 窗口:
#expr Exec会在打包前完整执行build-release.ps1,首次构建需要还原依赖、发布 Player、编译解决方案并下载依赖安装包,耗时较长属正常现象; - CI 与本地构建复用:build-release.ps1 注释标明其同时供本地与 GitHub Actions 使用,CI 中可用
-SkipRestore避免重复还原; - 版本更新:发布新版本时只需同步修改 installer.iss 顶部的
MyAppVersion与MyAppName常量,构建产物文件名、安装目录与快捷方式名称会随之自动更新; - 架构限制:安装程序明确面向 x64 / Windows 11 on Arm,在 32 位系统上无法运行,这与 Player 的
win-x64自包含发布目标一致; - 安装目录策略:
UsePreviousAppDir=no意味着不同版本安装在不同子目录,老版本不会自动清理,升级时建议先卸载旧版本或手动清理。
小结
TiXL 的安装程序构建是一套"预编译钩子 + Release 构建 + Inno Setup 打包"的自动化流水线:installer.iss 通过 #expr Exec 在编译期调用 build-release.ps1,后者依次完成 dotnet restore、Player 自包含发布(FolderProfile.pubxml)与解决方案 Release 构建(其中 Editor.csproj 的 CopyPlayer 目标把 Player 并入 Editor 输出),最后脚本负责下载 .NET SDK 与 VC++ 运行库;打包阶段由 installer.iss 的 [Files]、[Code]、[Run] 段协同完成文件安装、运行时前置检测、Windows Graphics Tools 启用与启动器生成。理解了这条链路,无论是本地发版还是接入 CI,都能快速产出开箱即用的 TiXL Windows 安装程序。