.. py:currentmodule:: starlark_tugger ================= ``WiXMSIBuilder`` ================= .. py:class:: WiXMSIBuilder The ``WiXMSIBuilder`` type allows building simple MSI installers using the `WiX Toolset `_. ``WiXMSIBuilder`` instances allow you to create and build a ``.wxs`` file with common features. A goal of this type is to allow simple applications - without complex installer needs - to generate MSI installers without having to author your own ``.wxs`` files. Instances have multiple attributes, which are write-only. .. py:method:: __init__(id_prefix: str, product_name: str, product_version: str, product_manufacturer: str, arch: str = "x64") -> WiXMSIBuilder ``WiXMSIBuilder()`` is called to construct new instances. It accepts the following arguments: ``id_prefix`` The string prefix to add to auto-generated IDs in the ``.wxs`` XML. The value must be alphanumeric and ``-`` cannot be used. The value should reflect the application whose installer is being defined. ``product_name`` The name of the application being installed. ``product_version`` The version of the application being installed. This is a string like ``X.Y.Z``, where each component is an integer. ``product_manufacturer`` The author of the application. ``arch`` The WiX architecture of the installer. .. py:attribute:: arch (``str``) The WiX architecture of the installer. No validation is performed that the value is a valid WiX architecture or that the content of the installer matches the provided architecture. .. py:attribute:: banner_bmp_path (``str``) The path to a 493 x 58 pixel BMP file providing the banner to display in the installer. .. py:attribute:: dialog_bmp_path (``str``) The path to a 493 x 312 pixel BMP file providing an image to be displayed in the installer. .. py:attribute:: eula_rtf_path (``str``) The path to a RTF file containing the EULA that will be shown to users during installation. .. py:attribute:: help_url (``str``) A URL that will be presented to provide users with help. .. py:attribute:: license_path (``str``) Path to a file containing the license for the application being installed. .. py:attribute:: msi_filename (``str``) The filename to use for the built MSI. If not set, the default is ``-.msi``. .. py:attribute:: package_description (``str``) A description of the application being installed. .. py:attribute:: package_keywords (``str``) Keywords for the application being installed. .. py:attribute:: product_icon_path (``str``) Path to a file providing the icon for the installed application. .. py:attribute:: upgrade_code (``str``) A GUID defining the upgrade code for the application. If not provided, a stable GUID derived from the application name will be derived automatically. .. py:method:: add_program_files_manifest(manifest: FileManifest) This method registers the content of a :py:class:`FileManifest` to be installed in the *Program Files* directory for this application. This method accepts the following arguments: ``manifest`` Files to register for installation. As files are added, they are checked for code signing compatibility with the action ``windows-installer-file-added``. .. py:method:: add_visual_cpp_redistributable(redist_version: str, platform: str) This method will locate and add the Visual C++ Redistributable runtime DLL files (e.g. ``vcruntime140.dll``) to the *Program Files* manifest in the builder, effectively materializing these files in the installed file layout. This method accepts the following arguments: ``redist_version`` The version of the Visual C++ Redistributable to search for and add. ``14`` is the version used for Visual Studio 2015, 2017, and 2019. ``platform`` Identifies the Windows run-time architecture. Must be one of the values ``x86``, ``x64``, or ``arm64``. This method uses ``vswhere.exe`` to locate the ``vcruntimeXXX.dll`` files inside a Visual Studio installation. This should *just work* if a modern version of Visual Studio is installed. However, it may fail due to system variance. .. py:method:: build(target: str) -> ResolvedTarget This method will build an MSI using the WiX Toolset. This method accepts the following arguments: ``target`` The name of the target being built. Upon successful generation of an installer, the produced installer will be assessed for code signing with the ``windows-installer-creation`` *action*. .. py:method:: to_file_content() -> FileContent Builds the MSI using the WiX Toolset and returns a :py:class:`FileContent` representing the built MSI. Upon successful generation of an installer, the produced installer will be assessed for code signing with the ``windows-installer-creation`` *action*. .. py:method:: write_to_directory(path: str) -> str Builds the MSI using the WiX Toolset and writes that installer to the specified directory, returning the absolute path of the written file. Absolute paths are treated as-is. Relative paths are relative to the current build path. Upon successful generation of an installer, the produced installer will be assessed for code signing with the ``windows-installer-creation`` *action*.