README.txt
1This folder contains the files required for building the Windows Vulkan
2Runtime Installer Package.
3
4To build the Vulkan Runtime Installer:
5
6 1. Install Nullsoft Install System (NSIS) version 3.0b3. The
7 version of NSIS needed for building the Vulkan Runtime Installer
8 must support logging (i.e. must have been built with NSIS_CONFIG_LOG=yes
9 set), and must support long strings (i.e. NSIS_MAX_STRLEN=8192 must be
10 set). The NSIS AccessControl plug-in should also be installed. (Available
11 from http://nsis.sourceforge.net/AccessControl_plug-in.)
12
13 1a. Note that the NSIS binary version available at
14 http://nsis.sourceforge.net/Download is not built with
15 NSIS_CONFIG_LOG=yes and NSIS_MAX_STRLEN=8192 set. Also, changes to need
16 to be made to NSIS to increase the security of the Runtime Installer.
17
18 The source for NSIS 3.0.b3 can be downloaded from
19 https://sourceforge.net/projects/nsis/files/NSIS%203%20Pre-release/3.0b3/nsis-3.0b3-src.tar.bz2/download
20
21 Instructions for building NSIS are available at
22 http://nsis//sourceforge.net/Docs/AppendixG.html.
23
24 The security changes to NSIS involve adding the /DYMANICBASE and /GS options
25 to the NSIS compile/link steps, so that the Runtime Installer and Uninstaller
26 are built with address space layout randomization and buffer overrun checks.
27
28 The security changes to NSIS can be made by applying the patch in the
29 NSIS_Security.patch file in this folder.
30
31 After you have applied the security patch, build NSIS with this command:
32
33 scons SKIPUTILS="NSIS Menu","MakeLangId" UNICODE=yes \
34 ZLIB_W32=<path_to_zlib>\zlib-1.2.7-win32-x86 NSIS_MAX_STRLEN=8192 \
35 NSIS_CONFIG_LOG=yes NSIS_CONFIG_LOG_TIMESTAMP=yes \
36 APPEND_CCFLAGS="/DYNAMICBASE /Zi" APPEND_LINKFLAGS="/DYNAMICBASE \
37 /DEBUG /OPT:REF /OPT:ICF" SKIPDOC=all dist-zip
38
39 This will create a zip file in the nsis-3.0.b3-src directory. Unpack
40 the zip file anywhere on your system. The resulting tree will contain a
41 Plugins directory. Install the NSIS AccessControl plugin in this directory.
42 Add the Bin directory to your PATH enviroment variable so that the
43 CreateInstaller.sh step below will use your custom-built version of
44 NSIS.
45
46 Before using NSIS and creating the installer, make sure that all shared
47 libraries in your custom-built version of NSIS have the DYNAMIC_BASE and NX_COMPAT
48 flags set. If they are not set, you will have to rebuild those libraries with
49 those options enabled.
50
51 2. Build Vulkan-LoaderAndValidationLayers as described in ../BUILD.md.
52
53 3. Edit the InstallerRT.nsi file in this folder and modify the following
54 lines to match the version of the Windows Vulkan Runtime you wish to
55 build:
56
57 !define VERSION_ABI_MAJOR
58 !define VERSION_API_MAJOR
59 !define VERSION_MINOR
60 !define VERSION_PATCH
61 !define VERSION_BUILDNO
62 !define PUBLISHER
63
64 4. Edit the CreateInstaller.sh file and replace SIGNFILE with your
65 command and necessary args for signing an executable. If you don't
66 wish to sign the uninstaller, you can comment out that line.
67
68 5. Run the CreateInstaller.sh script from a Cygwin bash command prompt.
69 The Cygwin bash shell must be running as Administrator. The Windows
70 Vulkan Runtime Installer will be created in this folder. The name
71 of the installer file is VulkanRT-<version>-Installer.exe.
72
73
74Some notes on the behavior of the Windows Vulkan Runtime Installer:
75
76 o When VulkanRT-<version>-Installer.exe is run on a 64-bit version
77 of Windows, it will install both the 32 and 64 bit versions of
78 the Vulkan runtime. When it is run on a 32-bit version of
79 Windows, it will install the 32 bit version of the Vulkan runtime.
80
81 o The VulkanRT-<version>-Installer.exe created with the above steps
82 can be run in silent mode by using the /S command line option when
83 invoking the installer.
84
85 o If the Vulkan Runtime is already installed on the system,
86 subsequent installs of the same version of the Vulkan Runtime
87 will be installed to the same folder to which it is was
88 previously installed.
89
90 o The Vulkan Runtime Installer uses "counted" installs. If the
91 same version of the Vulkan Runtime is installed multiple times
92 on a system, the Vulkan Runtime must be uninstalled the same
93 number of times before it is completely removed from the system.
94
95 o If the Vulkan Runtime is already installed on a system and a
96 different version is subsequently installed, both versions will
97 then co-exist on the system. The Vulkan Runtime Installer does
98 not remove prior versions of the Vulkan Runtime when a newer
99 version is installed.
100
101 o The Vulkan Runtime can be uninstalled from Control Panel ->
102 Programs and Features. It can also be uninstalled by running
103 UninstallVulkanRT.exe in the install folder. The uninstall can
104 be run in silent mode by using the /S command line option
105 when invoking the uninstaller. The location of the the
106 UninstallVulkanRT.exe can be found in the registry value
107 HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\
108 VulkanRT<version>\UninstallString
109
110 o The Vulkan Runtime Installer installs the Vulkan loader as
111 C:\Windows\System32\vulkan-<version>.dll. It then runs the
112 program ConfigureRT.exe (the source for which is included), that
113 compares versions of the loader in C:\Windows\System32 that have
114 the same VERSION_ABI_MAJOR as the version being installed. The
115 script selects the most recent one of these loader files and
116 copies it to C:\Windows\System32\vulkan-<VERSION_ABI_MAJOR>.dll.
117 For example, during the install of Vulkan Runtime version 2.0.1.1,
118 the following files might be present in C:\Windows\System32:
119
120 vulkan-1-1-0-2-3.dll
121 vulkan-1-2-0-1-0.dll
122 vulkan-1-2-0-1-1.dll
123
124 [Note that the first "1" in the above files is VERSION_ABI_MAJOR.
125 The other numbers identify the release version.] The script
126 will copy the most recent one of these files (in this case
127 vulkan-1-2-0-1-1.dll) to vulkan-1.dll. This is repeated for
128 C:\Windows\SYSWOW64 on 64-bit Windows systems to set up the
129 32-bit loader.
130
131 o The Vulkan Runtime Uninstaller returns an exit code of 0-9
132 to indicate success. An exit code of 3 indicates success, but
133 a reboot is required to complete the uninstall. All other
134 exit codes indicate failure. If the Uninstaller returns a
135 failure exit code, it will have simply exited when the failure
136 was detected and will not have attempted to do further uninstall
137 work.
138
139 o The ProductVersion of the installer executable (right click on
140 the executable, Properties, then the Details tab) can be used
141 by other installers/uninstallers to find the path to the
142 uninstaller for the Vulkan Runtime in the Windows registry.
143 This ProductVersion should always be identical to <version> in:
144
145 HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\VulkanRT<version>\UninstallString
146
147 o The Installer and Uninstaller create log files, which can be
148 found in the VulkanRT folder in the current TEMP folder.
149 (The TEMP folder is generally identified by the TEMP environment
150 variable). In addition to installer/uninstaller logs files,
151 the folder also contains a log from the last run of the
152 ConfigureRT.exe program.
153
