1 This folder contains the files required for building the Windows Vulkan 2 Runtime Installer Package. 3 4 To 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 74 Some 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
