<commit_before>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.0b1 or greater. 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).  Note that the NSIS binary version available at
       http://nsis.sourceforge.net/Download does not have these enabled. You
       may have to build NSIS yourself with these flags set - see
       http://nsis//sourceforge.net/Docs/AppendixG.html for information on
       building NSIS.

    2. Install the NSIS AccessControl plug-in. (Available from
       http://nsis.sourceforge.net/AccessControl_plug-in.)

    3. Build Vulkan-LoaderAndValidationLayers as described in ../BUILD.md.

    4. 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

    5. 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.

    6. 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 package file 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 compares all
      versions of the loader in C:\Windows\System32 that have the
      same VERSION_ABI_MAJOR as the version being installed. It 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 installer
     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\Uininstall\VulkanRT<version>\UinstalString

   o The Installer and Uninstaller create log files, which can be
     found in the VulkanrRT 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
     ConfigLayersAndVulkanDLL.ps1 script.
<commit_msg>windowsRuntimeInstaller: improve documentation on how to build RT installer<commit_after>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, so you may have
       to build NSIS from source with these flags set.  The source for
       NSIS 3.0.b3 is available 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.

       To increase the security of the Runtime Installer - specifically
       enabling buffer overrun security checks and enabling address space
       layout randomization (ASLR), these changes should be made to the NSIS source file
       nsis-3.0b3-src/SCons/Config/ms:

           - comment out the line enabling the /FIXED linker option
           - change the line that sets the /GS- compile option to instead set the /GS compile option
           - comment out the line that sets the NODEFLIBS_FLAG to /NODEFAULTLIB

       The command to build NSIS from source:

           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 script 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
      Powershell script ConfigLayersAndVulkanDLL.ps1, 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 VulkanrRT 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
     ConfigLayersAndVulkanDLL.ps1 script.

{'fraction_non_alphanumeric': 0.041401955885502176, 'fraction_numerical': 0.012349204083089442, 'mean_word_length': 2.6493878614222455, 'pattern_counts': {'":': 0, '<': 20, '<?xml version=': 0, '>': 22, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7640695', 'n_tokens_mistral': 4102, 'n_tokens_neox': 3649, 'n_words': 1746}