.. py:currentmodule:: starlark_tugger
====================
``WiXBundleBuilder``
====================
.. py:class:: WiXBundleBuilder
The ``WiXBundleBuilder`` type allows building simple *bundle* installers
with the `WiX Toolset `_.
``WiXBundleBuilder`` instances allow you to create ``.exe`` installers that are
composed of a chain of actions. At execution time, each action in the chain is
evaluated. See the WiX Toolset documentation for more.
.. py:method:: __init__(id_prefix: str, name: str, version: str, manufacturer: str, arch: str = "x64") -> WiXBundleBuilder
``WiXBundleBuilder()`` 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.
``name``
The name of the application being installed.
``version``
The version of the application being installed.
This is a string like ``X.Y.Z``, where each component is an integer.
``manufacturer``
The author of the application.
``arch``
The WiX architecture of the installer being built.
.. py:method:: add_condition(condition: str, message: str)
Defines a ```` that must be satisfied to run this installer.
See the WiX Toolkit documentation for more.
This method accepts the following arguments:
``condition``
The condition expression that must be satisfied.
``message``
The message that will be displayed if the condition is not met.
.. py:method:: add_vc_redistributable(platform: str)
This method registers the Visual C++ Redistributable to be installed.
This method accepts the following arguments:
``platform``
The architecture to install for. Valid values are ``x86``, ``x64``, and
``arm64``.
The bundle can contain Visual C++ Redistributables for multiple runtime
architectures. The bundle installer will only install the Redistributable
when running on a machine of that architecture. This allows a single bundle
installer to target multiple architectures.
.. py:method:: add_wix_msi_builder(builder: WiXMSIBuilder, display_internal_ui: Optional[bool] = False, install_condition: Optional[str] = None)
This method adds a :py:class:`WiXMSIBuilder` to be installed
by the produced installer.
This method accepts the following arguments:
``builder``
The :py:class:`WiXMSIBuilder` representing an MSI to install.
``display_internal_ui``
Whether to display the UI of the MSI.
``install_condition``
An expression that must be true for this MSI to be installed.
This method effectively coerces the :py:class:`WiXMSIBuilder` instance to an
```` element and adds it to the ```` in the bundle XML.
See the WiX Toolset documentation for more.
.. py:method:: build(target: str) -> ResolvedTarget
This method will build an exe 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
Build an exe installer using the WiX Toolset and return a
:py:class:`FileContent` representing the built installer.
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
Build an exe installer using the WiX Toolset and write the built installer
to the directory specified, 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*.