xref: /external/vulkan-validation-layers/windowsRuntimeInstaller

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, /GS and
       /guard:cf options to the NSIS compile/link steps, so that the Runtime
       Installer and Uninstaller are built with address space layout randomization,
       buffer overrun checks and control flow guard.

       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.