This folder contains the files required for building the Windows Vulkan
Runtime Installer Package.
To build the Vulkan Runtime Installer:
1. Install Nullsoft Install System (NSIS) version 3.0b3. The
version of NSIS needed for building the Vulkan Runtime Installer
must support logging (i.e. must have been built with NSIS_CONFIG_LOG=yes
set), and must support long strings (i.e. NSIS_MAX_STRLEN=8192 must be
set). The NSIS AccessControl plug-in should also be installed. (Available
from http://nsis.sourceforge.net/AccessControl_plug-in.)
1a. Note that the NSIS binary version available at
http://nsis.sourceforge.net/Download is not built with
NSIS_CONFIG_LOG=yes and NSIS_MAX_STRLEN=8192 set. Also, changes to need
to be made to NSIS to increase the security of the Runtime Installer.
The source for NSIS 3.0.b3 can be downloaded from
https://sourceforge.net/projects/nsis/files/NSIS%203%20Pre-release/3.0b3/nsis-3.0b3-src.tar.bz2/download
Instructions for building NSIS are available at
http://nsis//sourceforge.net/Docs/AppendixG.html.
The security changes to NSIS involve adding the /DYMANICBASE and /GS options
to the NSIS compile/link steps, so that the Runtime Installer and Uninstaller
are built with address space layout randomization and buffer overrun checks.
The security changes to NSIS can be made by applying the patch in the
NSIS_Security.patch file in this folder.
After you have applied the security patch, build NSIS with this command:
scons SKIPUTILS="NSIS Menu","MakeLangId" UNICODE=yes \
ZLIB_W32=<path_to_zlib>\zlib-1.2.7-win32-x86 NSIS_MAX_STRLEN=8192 \
NSIS_CONFIG_LOG=yes NSIS_CONFIG_LOG_TIMESTAMP=yes \
APPEND_CCFLAGS="/DYNAMICBASE /Zi" APPEND_LINKFLAGS="/DYNAMICBASE \
/DEBUG /OPT:REF /OPT:ICF" SKIPDOC=all dist-zip
This will create a zip file in the nsis-3.0.b3-src directory. Unpack
the zip file anywhere on your system. The resulting tree will contain a
Plugins directory. Install the NSIS AccessControl plugin in this directory.
Add the Bin directory to your PATH enviroment variable so that the
CreateInstaller.sh step below will use your custom-built version of
NSIS.
Before using NSIS and creating the installer, make sure that all shared
libraries in your custom-built version of NSIS have the DYNAMIC_BASE and NX_COMPAT
flags set. If they are not set, you will have to rebuild those libraries with
those options enabled.
2. Build Vulkan-LoaderAndValidationLayers as described in ../BUILD.md.
3. Edit the InstallerRT.nsi file in this folder and modify the following
lines to match the version of the Windows Vulkan Runtime you wish to
build:
!define VERSION_ABI_MAJOR
!define VERSION_API_MAJOR
!define VERSION_MINOR
!define VERSION_PATCH
!define VERSION_BUILDNO
!define PUBLISHER
4. Edit the CreateInstaller.sh file and replace SIGNFILE with your
command and necessary args for signing an executable. If you don't
wish to sign the uninstaller, you can comment out that line.
5. Run the CreateInstaller.sh script from a Cygwin bash command prompt.
The Cygwin bash shell must be running as Administrator. The Windows
Vulkan Runtime Installer will be created in this folder. The name
of the installer file is VulkanRT-<version>-Installer.exe.
Some notes on the behavior of the Windows Vulkan Runtime Installer:
o When VulkanRT-<version>-Installer.exe is run on a 64-bit version
of Windows, it will install both the 32 and 64 bit versions of
the Vulkan runtime. When it is run on a 32-bit version of
Windows, it will install the 32 bit version of the Vulkan runtime.
o The VulkanRT-<version>-Installer.exe created with the above steps
can be run in silent mode by using the /S command line option when
invoking the installer.
o If the Vulkan Runtime is already installed on the system,
subsequent installs of the same version of the Vulkan Runtime
will be installed to the same folder to which it is was
previously installed.
o The Vulkan Runtime Installer uses "counted" installs. If the
same version of the Vulkan Runtime is installed multiple times
on a system, the Vulkan Runtime must be uninstalled the same
number of times before it is completely removed from the system.
o If the Vulkan Runtime is already installed on a system and a
different version is subsequently installed, both versions will
then co-exist on the system. The Vulkan Runtime Installer does
not remove prior versions of the Vulkan Runtime when a newer
version is installed.
o The Vulkan Runtime can be uninstalled from Control Panel ->
Programs and Features. It can also be uninstalled by running
UninstallVulkanRT.exe in the install folder. The uninstall can
be run in silent mode by using the /S command line option
when invoking the uninstaller. The location of the the
UninstallVulkanRT.exe can be found in the registry value
HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\
VulkanRT<version>\UninstallString
o The Vulkan Runtime Installer installs the Vulkan loader as
C:\Windows\System32\vulkan-<version>.dll. It then runs the
program ConfigureRT.exe (the source for which is included), that
compares versions of the loader in C:\Windows\System32 that have
the same VERSION_ABI_MAJOR as the version being installed. The
script selects the most recent one of these loader files and
copies it to C:\Windows\System32\vulkan-<VERSION_ABI_MAJOR>.dll.
For example, during the install of Vulkan Runtime version 2.0.1.1,
the following files might be present in C:\Windows\System32:
vulkan-1-1-0-2-3.dll
vulkan-1-2-0-1-0.dll
vulkan-1-2-0-1-1.dll
[Note that the first "1" in the above files is VERSION_ABI_MAJOR.
The other numbers identify the release version.] The script
will copy the most recent one of these files (in this case
vulkan-1-2-0-1-1.dll) to vulkan-1.dll. This is repeated for
C:\Windows\SYSWOW64 on 64-bit Windows systems to set up the
32-bit loader.
o The Vulkan Runtime Uninstaller returns an exit code of 0-9
to indicate success. An exit code of 3 indicates success, but
a reboot is required to complete the uninstall. All other
exit codes indicate failure. If the Uninstaller returns a
failure exit code, it will have simply exited when the failure
was detected and will not have attempted to do further uninstall
work.
o The ProductVersion of the installer executable (right click on
the executable, Properties, then the Details tab) can be used
by other installers/uninstallers to find the path to the
uninstaller for the Vulkan Runtime in the Windows registry.
This ProductVersion should always be identical to <version> in:
HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall\VulkanRT<version>\UninstallString
o The Installer and Uninstaller create log files, which can be
found in the VulkanRT folder in the current TEMP folder.
(The TEMP folder is generally identified by the TEMP environment
variable). In addition to installer/uninstaller logs files,
the folder also contains a log from the last run of the
ConfigureRT.exe program.