Amistaller

Run amistaller from Workbench¶

The simplest setup is to put amistaller and a file named installer.yaml in the same directory, and double-click the amistaller icon. When no SCRIPT tooltype is set, amistaller opens PROGDIR:installer.yaml by default. If your yaml file is named differently, set the SCRIPT tooltype to PROGDIR:<insert yaml filename here> or rename the file to installer.yaml.

A Workbench icon can also point directly to a YAML file:

1. Create an icon for the YAML file.
2. Set its Default Tool to the full path of amistaller, such as Work:Tools/amistaller.
3. Double-click the YAML icon.

The YAML file is passed as a project argument, so no SCRIPT tooltype is needed on that icon.

Command-line use¶

From a Shell, pass the YAML file as the required argument:

amistaller Work:Install/install.yaml
amistaller Work:Install/install.yaml LOG=Work:Install/install.log

The directory for a LOG file must already exist. The log is written when the user starts the installation; cancelling before installation begins does not create it.

How the installer works¶

The installer reads and validates the YAML file before showing the package choices. It then opens the screens that are present in the configuration, installs selected packages in dependency order, and displays a final message.

The usual screen order is:

1. Introduction, if intro is defined.
2. Licence agreement, if licence is defined.
3. Packages.
4. Confirmation.
5. Progress.
6. Final message.

The packages screen is always shown. The introduction and licence screens are optional. The final screen is always shown after the installation process finishes.

On the packages screen, you can set the installation destination in either of two ways: click the destination button and choose a folder in the requester, or drag an existing target folder from Workbench onto the amistaller window. The folder is used immediately as the destination, and the space check is updated.

YAML configuration¶

The configuration must contain schema_version, packages, and final sections. The current schema starts at version 1.

The smallest configuration looks like this:

schema_version: 1

packages:
  target: "Work:Apps"
  list:
    editor:
      title: "Text editor"
      file: "archives/editor.lha"
      size: 2048

final:
  text: |
    Installation complete.
    The application is installed in Work:Apps.

Paths and the YAML file¶

All relative paths in the YAML file are resolved from the directory containing the YAML configuration file, not from the directory containing the amistaller executable. This includes:

• global.header_image — header image for installer screens
• licence.file — licence text file
• Package file — local archive files

global:
  header_image: "images/header.png"

licence:
  file: "docs/LICENSE.txt"

packages:
  list:
    app:
      title: "Application"
      file: "archives/app.lha"

This allows you to place amistaller anywhere on your system while keeping the YAML and its related files together.

Path resolution rules:

• Relative paths (e.g., "archives/app.lha", "docs/LICENSE.txt"): resolved relative to the YAML directory using AddPart().
• Absolute AmigaOS paths (e.g., "SYS:Docs/LICENSE.txt"): used verbatim as they contain a volume separator (:).
• Leading-slash paths (e.g., "/images/banner.png", "//images/banner.png"): each / walks up one directory level from the YAML location before resolving the remainder. This stops at the volume root.

Check the screen reference for additional details and more examples.

Global options¶

global:
  header_image: "images/header.png"
  enable_auto_restart: false

• header_image is optional. It places an image at the top of the installer screens. A missing image produces a warning and the installer continues without it. It is recommended the image to be a horizontal one, although amistaller doesn't check its dimensions.
• enable_auto_restart is optional. When true, the final screen offers a Restart system when closing checkbox. The system restarts only if the user selects it.

Introduction options¶

The optional intro section adds a welcome screen:

intro:
  title: "Welcome"
  text: |
    This installer will install the application and its documentation.

    Click Continue to choose the components.

title changes the screen title. text is the message shown to the user. On this screen, Continue moves forward and Cancel exits. There is no Back button.

Licence options¶

The optional licence section asks the user to accept terms before continuing. Supply either inline text or a file containing the licence:

licence:
  title: "Licence Agreement"
  file: "docs/LICENSE.txt"

or:

licence:
  title: "Licence Agreement"
  text: |
    You may install and use this software on your AmigaOS system.

The user must select the I agree to the terms above checkbox before the Continue button becomes available. Back returns to the introduction when one exists. If a licence file cannot be read, amistaller can use inline text when it is provided; if no usable text remains, the agreement screen is going to be blank.

Package options¶

Packages are entries under packages.list. The mapping key is the package ID used by depends_on.

packages:
  title: "Choose components"
  target: "Work:Apps"
  list:
    runtime:
      title: "Runtime files"
      text: "Required files used by the application."
      version: "1.2"
      file: "runtime.lha"
      size: 4096
      tags: [required]

    documentation:
      title: "Documentation"
      file: "docs.lha"
      size: 1024
      tags: [optional]
      depends_on: [runtime]

Use file for an archive bundled with the installer:

local_app:
  title: "Local application"
  file: "archives/app.lha"
  size: 8192

Size values support optional unit suffixes for convenience:

packages:
  list:
    small_app:
      title: "Small App"
      file: "small.lha"
      size: 512KB              # Explicit KB

    medium_app:
      title: "Medium App"
      file: "medium.lha"
      size: 50MB               # 50 MB

    large_app:
      title: "Large App"
      file: "large.lha"
      size: 2GB                # 2 GB

    legacy_app:
      title: "Legacy App"
      file: "legacy.lha"
      size: 8192               # 8192 KB (default if no suffix)

All size values are converted to and displayed as kilobytes (KB). Supported unit suffixes are: KB (kilobytes, default), MB (megabytes), GB (gigabytes). Suffix matching is case-insensitive.

Use url for a remote archive. Add sha256 when the download should be checked:

remote_tools:
  title: "Tools"
  url: "https://example.org/tools.lha"
  sha256: "0123456789abcdef..."
  size: 4096

Packages are selected by default. A package selected because another package depends on it is marked as required. If a package has a URL and the required AmiSSL support is unavailable, it and packages that depend on it cannot be installed.

Tags and dependencies¶

If at least one package has tags, amistaller shows a tag filter above the list of the packages. Choosing a tag selects the packages with that tag and also selects their dependencies.

packages:
  list:
    base:
      title: "Base files"
      file: "base.lha"
      tags:
      - core
    games:
      title: "Games"
      file: "games.lha"
      tags:
      - optional
      depends_on:
      - base

Selecting optional selects both games and base. Dependencies must name existing package IDs. Unknown or circular dependencies make the configuration invalid.

Install scripts¶

Each item in preinstall and postinstall is run as a separate AmigaOS shell command in the target directory. %TARGETDIR% is replaced with the selected destination:

tools:
  title: "Tools"
  file: "tools.lha"
  preinstall:
    - "makedir \"%TARGETDIR%/Config\" FORCE"
  postinstall:
    - "echo Installation finished"

A failed script is logged but does not stop the rest of the installation. Test commands in a Shell before adding them to the YAML.

Final options¶

The final section supplies the message shown when installation finishes:

final:
  title: "Ready to use"
  text: |
    The installation is complete.

    Start the application from Work:Apps.

The Continue button is labelled Close on this screen. If automatic restart is enabled, the restart checkbox is shown here.

The installer screens¶

Introduction¶

The introduction explains what the installer will do. Read the message and choose Continue, or choose Cancel to leave without installing anything.

Licence agreement¶

Read the licence text and select I Accept. Until the checkbox is selected, Continue remains disabled. Use Back to return to the introduction, or Cancel to exit.

Packages¶

This is the main choice screen.

• Select or clear package checkboxes.
• Select a tag to select a group of packages.
• Select a package to read its description.
• Choose a destination with the folder requester, or drag a folder onto the window.
• Check the required and available space values.

Continue becomes available only when the destination exists, at least one package is selected, and the estimated required space fits on the destination volume. The size values control the estimate, so keep them reasonably accurate.

Confirmation¶

Review the selected packages, destination, and space values. Choose Back to change the selection, Continue to begin, or Cancel to leave the installer.

Progress¶

The progress screen shows overall progress, progress for the current package, and an installation log. For each package, the log can include pre-install commands, downloads, extraction, post-install commands, and the final package status.

The navigation buttons are unavailable while installation is running. When it finishes, Continue becomes available.

Final¶

Read the completion message and choose Close. If the configuration enabled automatic restart, select Restart system when closing only when a restart is appropriate.

A complete Workbench example¶

As a full example, a self-contained installer directory can look like this:

MyInstaller/
  amistaller
  install.yaml
  images/header.png
  docs/LICENSE.txt
  archives/app.lha

The matching install.yaml is:

schema_version: 1

global:
  header_image: "images/header.png"
  enable_auto_restart: false

intro:
  title: "Install Example App"
  text: |
    This installer installs Example App and its documentation.
    Choose Continue to select the destination and components.

licence:
  title: "Licence"
  file: "docs/LICENSE.txt"

packages:
  title: "Select components"
  target: "Work:Apps/Example"
  list:
    app:
      title: "Example App"
      text: "The application and its runtime files."
      file: "archives/app.lha"
      version: "1.0"
      size: 8192
      tags: [required]

final:
  title: "Installation complete"
  text: |
    Example App has been installed.
    Start it from Work:Apps/Example.

Place the directory where ever you want, then double-click amistaller. More example YAML files can be found in the examples folder.

About local and downloaded packages¶

Local packages specified with file paths are located using the same path resolution rules as the YAML file itself. This means a local archive in "archives/app.lha" is found in archives/ next to the YAML file, regardless of where amistaller is installed.

If a local archive file cannot be accessed when amistaller loads the configuration, a warning is displayed in the output. The package is removed from the list and will not appear in the installer screens. If you need to fix a missing file, check the file path in your YAML configuration and the actual file location.

Downloaded packages specified with a url are downloaded to a temporary location before extracting. To keep the installer directory clean, downloads are cached in T: (AmigaOS temporary partition) if available, or in Ram: (RAM disk) if T: is not available. This allows amistaller to be installed anywhere without cluttering the installation folder.

Troubleshooting¶

• The installer cannot find a file: Check that relative paths are relative to the YAML file, and that the spelling and filename are correct. If a file cannot be accessed when the YAML is loaded, a warning is displayed and the package will be hidden from the installer screens. Fix the file path in the YAML and reload.
• Continue is disabled on Packages: Set an existing destination, select at least one package, and reduce the selection if required space is greater than available space.
• A package cannot be selected: Check its dependency chain and whether it requires AmiSSL for a remote download.
• A download fails: Check the URL and network connection. If a checksum is configured, make sure it matches the archive.
• A script fails: Inspect the progress log and run the command manually in the target directory.
• The YAML is rejected: Check indentation, required top-level sections, package IDs, and dependency names.

For the complete field-by-field screen reference, see Screen Reference. Example manifests are available in the examples directory.