TiXL 安装程序构建指南:基于 Inno Setup 的 Windows 发行包制作全流程

原创2026-09-18 21:47:051,819 阅读
文章标签:音视频图形学桌面应用

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 的说明,最简单的构建路径是:

  1. 安装 Inno Setup(需要其官方最新版本);
  2. 用 Inno Setup 打开 Installer/installer.iss;
  3. 点击 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
  1. 若未检测到 .NET SDK 10.0.201,静默安装随包携带的 SDK 安装器;
  2. 若缺少 vcruntime140.dll,安装 VC++ 运行库;
  3. 隐藏运行 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 安装程序。

登录后查看全文
t3