David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 1 | This folder contains the files required for building the Windows Vulkan
|
| 2 | Runtime Installer Package.
|
David Pinedo | c21fdb9 | 2016-01-04 16:31:57 -0700 | [diff] [blame] | 3 |
|
David Pinedo | 7f44f4f | 2016-03-18 13:15:27 -0600 | [diff] [blame] | 4 | To build the Vulkan Runtime Installer:
|
David Pinedo | c21fdb9 | 2016-01-04 16:31:57 -0700 | [diff] [blame] | 5 |
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 6 | 1. Install Nullsoft Install System (NSIS) version 3.0b3. The
|
David Pinedo | ef68bbe | 2016-03-29 13:46:12 -0600 | [diff] [blame] | 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
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 10 | set). The NSIS AccessControl plug-in should also be installed. (Available
|
| 11 | from http://nsis.sourceforge.net/AccessControl_plug-in.)
|
David Pinedo | c21fdb9 | 2016-01-04 16:31:57 -0700 | [diff] [blame] | 12 |
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 13 | 1a. Note that the NSIS binary version available at
|
| 14 | http://nsis.sourceforge.net/Download is not built with
|
David Pinedo | 9dc2819 | 2016-05-02 12:12:04 -0600 | [diff] [blame] | 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
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 19 | https://sourceforge.net/projects/nsis/files/NSIS%203%20Pre-release/3.0b3/nsis-3.0b3-src.tar.bz2/download
|
David Pinedo | c21fdb9 | 2016-01-04 16:31:57 -0700 | [diff] [blame] | 20 |
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 21 | Instructions for building NSIS are available at
|
| 22 | http://nsis//sourceforge.net/Docs/AppendixG.html.
|
David Pinedo | 7f44f4f | 2016-03-18 13:15:27 -0600 | [diff] [blame] | 23 |
|
Slawomir Cygan | c075b75 | 2017-06-14 19:15:31 +0200 | [diff] [blame] | 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.
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 28 |
|
David Pinedo | 9dc2819 | 2016-05-02 12:12:04 -0600 | [diff] [blame] | 29 | The security changes to NSIS can be made by applying the patch in the
|
| 30 | NSIS_Security.patch file in this folder.
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 31 |
|
David Pinedo | 9dc2819 | 2016-05-02 12:12:04 -0600 | [diff] [blame] | 32 | After you have applied the security patch, build NSIS with this command:
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 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
|
David Pinedo | 9dc2819 | 2016-05-02 12:12:04 -0600 | [diff] [blame] | 39 |
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 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
|
David Pinedo | 9dc2819 | 2016-05-02 12:12:04 -0600 | [diff] [blame] | 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
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 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
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 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
|
David Pinedo | 3f537a5 | 2016-02-10 11:29:33 -0700 | [diff] [blame] | 63 | !define PUBLISHER
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 64 |
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 65 | 4. Edit the CreateInstaller.sh file and replace SIGNFILE with your
|
David Pinedo | 5925ba0 | 2016-03-03 21:25:45 -0700 | [diff] [blame] | 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 |
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 69 | 5. Run the CreateInstaller.sh script from a Cygwin bash command prompt.
|
David Pinedo | 7f44f4f | 2016-03-18 13:15:27 -0600 | [diff] [blame] | 70 | The Cygwin bash shell must be running as Administrator. The Windows
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 71 | Vulkan Runtime Installer will be created in this folder. The name
|
| 72 | of the installer file is VulkanRT-<version>-Installer.exe.
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 73 |
|
| 74 |
|
| 75 | Some 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 |
|
Lenny Komow | 74cdfc9 | 2016-08-15 14:41:26 -0600 | [diff] [blame] | 82 | o The VulkanRT-<version>-Installer.exe created with the above steps
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 83 | can be run in silent mode by using the /S command line option when
|
| 84 | invoking the installer.
|
| 85 |
|
David Pinedo | 3f537a5 | 2016-02-10 11:29:33 -0700 | [diff] [blame] | 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 |
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 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 |
|
David Pinedo | 3f537a5 | 2016-02-10 11:29:33 -0700 | [diff] [blame] | 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 |
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 111 | o The Vulkan Runtime Installer installs the Vulkan loader as
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 112 | C:\Windows\System32\vulkan-<version>.dll. It then runs the
|
Lenny Komow | 769b9df | 2016-08-12 13:26:20 -0600 | [diff] [blame] | 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
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 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:
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 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.
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 126 | The other numbers identify the release version.] The script
|
David Pinedo | 36048ab | 2016-02-04 13:31:28 -0700 | [diff] [blame] | 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.
|
David Pinedo | 5f7ebd8 | 2016-02-10 11:20:44 -0700 | [diff] [blame] | 131 |
|
David Pinedo | 8733866 | 2016-02-19 12:37:48 -0700 | [diff] [blame] | 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.
|
David Pinedo | 6d5fcfd | 2016-02-11 12:06:38 -0700 | [diff] [blame] | 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 |
|
David Pinedo | 7c4de87 | 2016-04-29 11:33:59 -0600 | [diff] [blame] | 146 | HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\VulkanRT<version>\UninstallString
|
David Pinedo | ef68bbe | 2016-03-29 13:46:12 -0600 | [diff] [blame] | 147 |
|
| 148 | o The Installer and Uninstaller create log files, which can be
|
Lenny Komow | 769b9df | 2016-08-12 13:26:20 -0600 | [diff] [blame] | 149 | found in the VulkanRT folder in the current TEMP folder.
|
David Pinedo | ef68bbe | 2016-03-29 13:46:12 -0600 | [diff] [blame] | 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
|
Lenny Komow | 769b9df | 2016-08-12 13:26:20 -0600 | [diff] [blame] | 153 | ConfigureRT.exe program.
|