How-to guides#

Control which kind of installer gets generated#

Constructor is currently limited to generating installers for the platform on which it is running. In other words, if you run constructor on a Windows computer, you can only generate Windows installers. This is largely because OS-native tools are needed to generate the Windows .exe files and macOS .pkg files. There is a key in construct.yaml, installer_type, which dictates the type of installer that gets generated. This is primarily only useful for macOS, where you can generate either .pkg or .sh installers. When not set in construct.yaml, this value defaults to .sh on Unix platforms, and .exe on Windows. Using this key is generally done with selectors. For example, to build a .pkg installer on MacOS, but fall back to default behavior on other platforms:

installer_type: pkg  #[osx]

See installer_type for more details.

Customization and branding#

Graphical installers (.pkg on macOS and .exe on Windows) support some level of branding and customization.

Logos, backgrounds and banners:

Refer to welcome_image and icon_image. Windows also supports header_image.
Alternatively, a text-based image can be autogenerated from text if you set welcome_image_text and header_image_text, respectively. The color of such text can be provided via default_image_color.

Messages and texts. You can specify these via *_file (a path is expected) or _text (raw string expected).

welcome_file and welcome_text: The text that is shown in the first page of the installer.
readme_file and readme_text: Optional text to be displayed on an extra page before the license. macOS only.
conclusion_file and conclusion_text: The text to be shown at the end of the installer, on success.

On Windows, you can also add extra pages to the installer. This is an advanced option, so your best bet is to check the examples in the source repository at examples/customized_welcome_conclusion.

Signing and notarization#

Signing EXE installers#

Windows can trigger SmartScreen alerts for EXE installers, signed or not. It does help when they are signed, though. Read this SO answer about SmartScreen reputation for more details.

constructor supports the following tools to sign installers:

The signtool that is used can be set in the construct.yaml file via the windows_signing_tool key. If the signing_certificate key is set, windows_signing_tool defaults to signtool.

For each tool, there are environment variables that may need to be set to configure signing.

Environment variables for SignTool#

Variable	Description	CLI flag	Default
`CONSTRUCTOR_PFX_CERTIFICATE_PASSWORD`	Password for the `pfx` certificate file.	`/p`	Empty
`CONSTRUCTOR_SIGNTOOL_PATH`	Path to `signtool.exe`. Needed if `signtool` is not in `PATH`.	N/A	`signtool`
`CONSTRUCTOR_SIGNTOOL_FILE_DIGEST`	Digest algorithm for creating the file signatures.	`/fd`	`sha256`
`CONSTRUCTOR_SIGNTOOL_TIMESTAMP_SERVER_URL`	URL to the RFC 3161 timestamp server.	`/tr`	http://timestamp.sectigo.com
`CONSTRUCTOR_SIGNTOOL_TIMESTAMP_DIGEST`	Digest algorithm for the RFC 3161 time stamp.	`/td`	`sha256`

Environment variables for AzureSignTool#

Variable	Description	CLI flag	Default
`AZURE_SIGNTOOL_FILE_DIGEST`	Digest algorithm for creating the file signatures.	`-fd`	`sha256`
`AZURE_SIGNTOOL_KEY_VAULT_ACCESSTOKEN`	An access token used to authenticate to Azure.	`-kva`	Empty
`AZURE_SIGNTOOL_KEY_VAULT_CERTIFICATE`	The name of the certificate in the key vault.	`-kvc`	Empty
`AZURE_SIGNTOOL_KEY_VAULT_CLIENT_ID`	The client ID used to authenticate to Azure. Required for authentication with a secret.	`-kvi`	Empty
`AZURE_SIGNTOOL_KEY_VAULT_SECRET`	The client secret used to authenticate to Azure. Required for authentication with a secret.	`-kvs`	Empty
`AZURE_SIGNTOOL_KEY_VAULT_TENANT_ID`	The tenant ID used to authenticate to Azure. Required for authentication with a secret.	`-kvt`	Empty
`AZURE_SIGNTOOL_KEY_VAULT_URL`	The URL of the key vault with the certificate.	`-kvu`	Empty
`AZURE_SIGNTOOL_PATH`	Path to `AzureSignTool.exe`. Needed if `azuresigntool` is not in `PATH`.	N/A	`azuresigntool`
`AZURE_SIGNTOOL_TIMESTAMP_SERVER_URL`	URL to the RFC 3161 timestamp server.	`-tr`	http://timestamp.sectigo.com
`AZURE_SIGNTOOL_TIMESTAMP_DIGEST`	Digest algorithm for the RFC 3161 time stamp.	`-td`	`sha256`

Note

If neither AZURE_SIGNTOOL_KEY_VAULT_ACCESSTOKEN nor AZURE_SIGNTOOL_KEY_VAULT_SECRET are set, constructor will use a Managed Identity (-kvm CLI option).

Signing and notarizing PKG installers#

In the case of macOS, users might get warnings for PKGs if the installers are not signed and notarized. However, once these two requirements are fulfilled, the warnings disappear instantly. constructor offers some configuration options to help you in this process:

You will need to provide two identity names:

the installer certificate identity (via signing_identity_name) to sign the pkg installer,
the application certificate identity to pass the notarization (via notarization_identity_name); this certificate is used to sign binaries and plugins inside the pkg installer. These can be obtained in the Apple Developer portal. Once signed, you can notarize your PKG with Apple’s notarytool.

Note

To sign a pkg installer, the keychain containing the identity names must be unlocked and in the keychain search list.

Create shortcuts

On Windows, conda supports menuinst 1.x shortcuts. If a package provides a certain JSON file under $PREFIX/Menu, conda will process it to create the specified menu items. This happens by default for all packages. If you only want this to happen for certain packages, use the menu_packages key.

Starting with conda 23.11, menuinst 2.x is supported, which means you can create shortcuts in all platforms (Linux, macOS and Windows). The JSON document format is slightly different, so make sure to check the menuinst documentation. Your installer will need to be created with conda-standalone 23.11 or above. micromamba does not currently support menuinst 2.x style shortcuts (only 1.x on Windows).

To learn more about menuinst, visit conda/menuinst.

Find out the used constructor version

Recent constructor versions (>=3.4.2) burn-in their version into created installers in order to be able to trace back bugs in created installers to the constructor code base.

The burned-in version can be retrieved in different ways depending on the installer type:

For .sh intallers (via cli): head $installer.sh | grep "Created by constructor"
For .exe installers (via Windows Explorer): $installer.exe → Properties → Details → Comments, or (via cli) exiftool $installer.exe
For .pkg installers (via cli on macOS): xar -xf $installer.pkg -n run_installation.pkg/Scripts; zgrep -a "Created by constructor" run_installation.pkg/Scripts or pkgutil --expand $installer.pkg extracted; grep "Created by constructor" extracted/run_installation.pkg/Scripts/postinstall

Uninstall constructor-generated installations

Note

Many constructor installers ship conda (Miniconda, Miniforge, etc), and offer the user to initialize the installation. This adds further changes to the system configuration. These changes won’t be reverted by simply deleting the installation directory. If you want to revert these changes, you can execute this command before deleting the installation directory.

$ conda init --reverse --all

Use the --dry-run flag if you want to check what things will be reverted before actually doing it.

Windows#

On Windows, constructor-generated installations include an uninstaller executable, which is also exposed in the Control Panel menu “Add or remove programs”. The uninstaller executable is located in the installation directory, and is named Uninstall-<INSTALLATION_NAME>.exe.

Once opened, the uninstaller will guide the user through the uninstallation process. It will also remove the installation directory, and the uninstaller executable itself. In certain cases, some dangling files might be left behind, but these will be removed in the next reboot.

If you want to perform the uninstallation steps manually, you can:

Remove the installation directory. Usually this is a directory in your user’s home directory (user installs), or under C:\Program Files for system-wide installations.
In some installations, remove the entries added to the registry. System installs will use HKEY_LOCAL_MACHINE as the top level key; user installs will use HKEY_CURRENT_USER. You might find these items:
- Uninstaller information: TOP_LEVEL_KEY\Software\Microsoft\Windows\CurrentVersion\Uninstall\<INSTALLATION_NAME>.
- Python information: TOP_LEVEL_KEY\Software\Python\PythonCore\<PYTHON_VERSION>. Verify that these entries correspond to the installation directory you removed in step 1.
- PATH modifications. You’ll need to remove the entries corresponding to the installation directory, but leave the other locations intact. This is better handled via the UI available in the Control Panel (follow these instructions). The actual registry keys (in case you are curious) are located in:
  - System install: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\PATH.
  - User install: HKEY_CURRENT_USER\Environment\PATH
In some installations, remove the associated shortcuts under %APPDATA%\Microsoft\Windows\Start Menu\Programs\ (user installs) or %PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\ (system installs). You can enter these paths directly in the Windows Explorer address bar to open them.

macOS and Linux#

Remove the installation directory. Usually this is a directory in your user’s home directory (user installs), or under /opt for system-wide installations.