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