Screens and YAML Reference¶

This document is a field-by-field reference for amistaller's screens and YAML configuration. For a guided introduction and Workbench instructions, see the User Guide.

Global Configuration¶

These settings apply to the entire installer and all screens.

Relevant YAML Fields¶

global:
  header_image: "path/to/header.png"    # Optional: image for top of every screen
  enable_auto_restart: false            # Optional: show restart checkbox on final screen

Field Descriptions¶

Path Resolution for header_image¶

The header_image path is resolved relative to the directory containing your YAML script, not PROGDIR. See Path Resolution for more information.

Examples:

• header_image: header.png → looks for scriptDir/header.png
• header_image: images/banner.png → looks for scriptDir/images/banner.png
• header_image: /images/header.png → walks up one level, looks for parentDir/images/header.png
• header_image: SYS:images/header.png → absolute path, used verbatim

Missing Files: If the image cannot be found, a warning is printed and the header is simply not displayed (graceful degradation).

Example¶

global:
  header_image: "header.png"
  enable_auto_restart: true

Introduction Screen¶

Purpose¶

Optional welcome/introductory text shown as the first screen when the installer starts.

User Interaction¶

• User reads introduction text
• User clicks Continue to proceed to the next screen (or licence if defined)
• User clicks Cancel to abort the installer
• Back button is not enabled (there is no previous screen)

When This Screen Appears¶

• This screen is shown first if and only if intro is defined in the YAML
• If no intro is defined, the installer skips directly to the licence screen (if defined) or packages screen

Field Descriptions¶

Relevant YAML Fields¶

intro:
  title: "Welcome"            # Optional: shown in window title bar
  text: |
    Welcome to the Amistaller

    This installer will install version 1.0 of our software.

    Prerequisites:
    - AmigaOS 4.1 or later
    - At least 100MB free disk space
    - Internet connection (for downloading components)

    Click Continue to proceed.

Licence (Agreement) Screen¶

Purpose¶

Optional screen to display a licence agreement or terms of use. The user must explicitly check an "I agree to the terms above" checkbox to enable the Continue button.

User Interaction¶

• User reads licence text (may scroll to see all content)
• User checks the "I agree to the terms above" checkbox at the bottom
• When checkbox is checked, the Continue button becomes enabled
• User clicks Continue to proceed to the next screen
• User clicks Cancel to abort the installer
• Back button returns to intro screen (if it exists), otherwise it is disabled

When This Screen Appears¶

• This screen is shown if and only if licence is defined in the YAML
• It appears after the intro screen (if any) or as the first screen if no intro is defined

Field Descriptions¶

Relevant YAML Fields¶

You can provide the licence text in two ways:

Option 1: Inline text

licence:
  title: "License Agreement"    # Optional: shown in window title bar
  text: |
    SOFTWARE LICENSE AGREEMENT

    This software is licensed under the following terms:

    1. License Grant
    Permission is granted to install and use this software on a single computer.

    2. Restrictions
    You may not modify, decompile, or reverse-engineer this software.

    3. Warranty
    This software is provided "as is" without warranty of any kind.

Option 2: From file

licence:
  title: "License Agreement"    # Optional: shown in window title bar
  file: "LICENSE.txt"           # Path resolved RELATIVE TO SCRIPT DIRECTORY

Path Resolution for licence.file¶

The file path is resolved relative to the directory containing your YAML script, not PROGDIR.

Examples:

• file: LICENSE.txt → looks for scriptDir/LICENSE.txt
• file: docs/LICENSE.txt → looks for scriptDir/docs/LICENSE.txt
• file: /LICENSE.txt → walks up one level from script directory
• file: SYS:docs/LICENSE.txt → absolute path, used verbatim

Missing Files: If the licence file cannot be found:

• A warning is printed
• The licence text field is set to NULL
• If text is defined, it is used instead
• If neither text nor file are accessible, the licence screen is shown blank

Button States¶

Important Notes¶

• Text is displayed in a read-only text editor
• User can scroll through the entire licence to read it
• The I agree to the terms above checkbox must be explicitly checked to enable the Continue button
• Unchecking the checkbox disables the Continue button again
• The checkbox state is preserved if user clicks Back and returns to this screen

Packages Screen¶

Purpose¶

Main screen where users:

• Select which packages to install
• Filter packages by tags
• Read package descriptions
• Choose the installation destination folder
• Review available vs. required disk space

User Interaction¶

1. View Available Packages: A list shows all packages with columns for name and size
2. Select Packages: Click checkbox next to each package to select/deselect
3. Filter by Tags (if tags defined): Choose a tag from the dropdown to quickly select related packages
4. Read Descriptions: Click a package to see its description in a panel on the right
5. Choose Destination:
   • Click the destination button to open a folder browser (ASL requester)
   • OR drag a folder directly onto the window to set it as destination
6. Review Space: See required vs. available space at the bottom
7. Proceed: Click Continue when ready (only enabled if destination is valid and space is sufficient)

When This Screen Appears¶

• Always shown; this is the core screen of the installer

Field Descriptions¶

Relevant YAML Fields (packages Section)¶

packages:
  title: "Select Components"            # Optional: title at top
  target: "DH0:Apps"                    # Optional: pre-fill destination
  list:                                 # Required: package list
    base_system:
      title: "Base System"
      # ... (see Package Fields below)

Package Fields (Detailed)¶

Each entry under packages.list can contain these fields. The mapping key becomes the package ID:

Size Field Format¶

The size field specifies estimated installed size for disk-space calculations. It accepts values with optional unit suffixes for convenience:

Supported Formats:

• 2048 → 2048 KB (plain number, default unit)
• 512KB → 512 KB (explicit kilobytes)
• 50MB → 51200 KB (megabytes)
• 1GB → 1048576 KB (gigabytes)
• 2 MB → 2048 KB (whitespace allowed)

Suffix Matching: Case-insensitive (e.g., MB, mb, Mb all work)

Display: All values are internally converted to and consistently displayed as kilobytes (KB) in all screens.

Examples:

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

    medium_app:
      title: "Medium App"
      file: "medium.lha"
      size: 50MB               # More intuitive than 51200

    large_app:
      title: "Large App"
      file: "large.lha"
      size: 1GB                # 1GB instead of 1048576

    legacy_app:
      title: "Legacy App"
      file: "legacy.lha"
      size: 4096               # Plain number = KB (for backwards compatibility)

Local vs. Remote Packages¶

Local Package (archive is bundled with the installer):

base_system:
  title: "Base System"
  file: base-1.0.tgz          # Resolved RELATIVE TO SCRIPT DIRECTORY
  size: 10240

Remote Package (archive is downloaded):

extra_tools:
  title: "Extra Tools"
  url: https://example.org/extra-1.0.tgz
  sha256: "abcd1234..."       # Recommended for verification
  size: 5120

Path Resolution for package.file¶

The file path is resolved relative to the directory containing your YAML script, not PROGDIR.

Local File Examples:

• file: base-1.0.tgz → looks for scriptDir/base-1.0.tgz
• file: archives/base-1.0.tgz → looks for scriptDir/archives/base-1.0.tgz
• file: /base-1.0.tgz → walks up one level from script directory
• file: SYS:apps/base-1.0.tgz → absolute path, used verbatim

Remote URLs:

• URLs starting with http:// or https:// are used verbatim (no path resolution)
• The file field is ignored if url is set

Missing Local Files: If a local archive file cannot be found:

• A warning is printed at parse time
• The package is marked as unavailable
• Installation continues without it (user can skip it)

Tag Filter¶

If any package defines tags, a dropdown appears at the top of the packages list:

Behavior:

• Selecting a tag selects all packages with that tag
• Deselects packages without that tag
• Dependencies are propagated: if a selected package depends on another, that dependency is also selected and locked
• Locking is visual only; the package remains selectable but is highlighted as required

Example:

packages:
  list:
    base:
      title: "Base"
      tags:
      - core
    games:
      title: "Games"
      tags:
      - optional
    docs:
      title: "Docs"
      tags:
      - optional
      - "other tag"

Selecting "optional" selects both games and docs; selecting "core" selects only base.

Pre/Post Install Scripts¶

Custom shell commands can be executed before and after each package extraction. This is useful for:

• Creating directories or symbolic links
• Setting file permissions
• Running configuration scripts
• Cleaning up temporary files
• Integration with existing toolchains
• Move files and folders

Execution Context:

• Scripts execute with the target installation folder as the current directory
• Each script runs independently in the system shell
• stdout is suppressed (scripts run silently)
• stderr is captured and logged if the script fails

Preinstall Scripts (preinstall):

• Executed before the package archive is extracted
• Runs in the target destination folder
• Useful for creating directory structures or checking prerequisites

Postinstall Scripts (postinstall):

• Executed after the package archive is extracted
• Runs in the target destination folder
• Useful for setting permissions, moving files or folders, or creating soft links

Variable Substitution:

• Scripts can use %TARGETDIR% which is replaced with the actual installation path
• This is useful when creating absolute paths or passing to external programs

Error Handling:

• Script failures are logged with exit codes and error output
• Installation continues even if a script fails (non-fatal)
• Error messages are displayed in the progress screen for diagnostics

Example:

tools:
  title: "Development Tools"
  file: tools-1.0.lha
  size: 5000
  preinstall:
    - echo "Setting up directories..."
    - makedir "%TARGETDIR%/Bin" FORCE
    - makedir "%TARGETDIR%/Lib" FORCE
  postinstall:
    - echo "Finalizing installation..."
    - protect "%TARGETDIR%/Bin/#?" +e
    - echo "Tools are ready to use!"

Important Notes:

• Scripts must be valid AmigaOS shell commands
• Test scripts manually before adding to the YAML
• Each script line is executed independently
• Use proper escaping for special characters
• The order of script lines is preserved

Methods for the user to define the destination:

1. ASL Requester (Drawer Browser):

   • Click the destination button to open a file browser
   • Navigate to desired folder
   • Accept to set it as destination

2. Drag & Drop:

   • Drag a folder from the file manager onto the installer window
   • The folder is immediately set as destination
   • Space checks run automatically

Validation:

• Destination must be a valid, existing folder
• If invalid or missing, Continue button is disabled
• A message shows required vs. available space

Space Checks¶

Required Space Calculation:

• Sum of size values for all selected packages
• Packages with size: 0 are skipped
• Updated in real-time as user selects/deselects packages

Available Space:

• Calculated for the chosen destination folder
• Updated when destination is changed
• Shown as "Available: X KB"

Continue Button Enable Conditions:

1. A valid destination folder is set (not empty, path exists)
2. At least one package is selected (required space > 0)
3. Required space ≤ available space
4. If these conditions are not met, Continue remains disabled (greyed out)

Continue Button State¶

Confirmation Screen¶

Purpose¶

Final review screen summarizing:

• All selected packages
• Installation destination
• Required and available disk space

User Interaction¶

• User reviews the summary
• User clicks Continue to start installation
• User clicks Back to return to packages screen to make changes
• User clicks Cancel to abort

What's Shown¶

• List of selected packages with their versions, sizes and source (Local or Download)

When Install is Enabled¶

• Always enabled on this screen (if user reaches it, all checks passed on packages screen)

Button States¶

Progress Screen¶

Purpose¶

Displays live installation progress with:

• Overall installation progress gauge
• Current operation progress gauge
• Append-only log of all installation steps

User Interaction¶

• User watches progress during installation
• User reads log messages to understand what's happening
• User cannot interact during installation (Back/Continue buttons disabled)
• User can save the installation log from the menu (useful for diagnostics or record-keeping), when the installation is completed
• User clicks Continue once installation completes

Log Messages¶

The log shows real-time updates for each package:

1. Pre-install Scripts: Running preinstall scripts (if defined)
   • Each script line is logged
   • Failures are logged with error output but don't stop installation
2. Download (if URL): Downloading the archive
3. Extract: Extracting files with percentage
4. Post-install Scripts: Running postinstall scripts (if defined)
   • Each script line is logged
   • Failures are logged with error output but don't stop installation
5. Done or Skipped: Package status

Real-Time Updates¶

• Important: As of the recent update, log messages now refresh immediately on screen
• Users see progress in real-time, not just at the end
• Both gauges update live

Menu Options¶

The menu bar provides options to:

• Save log: Save the complete installation log to a file for diagnostics or record-keeping

Button States During Installation¶

After Installation Completes¶

• Overall gauge reaches 100%
• Continue button becomes enabled
• Proceed to the Final Screen

Final Screen¶

Purpose¶

Show completion message and optional restart checkbox. On successful installation, displays a summary with:

• Installation completion status
• Suggestions for next steps (documentation, support links, etc.)
• Optional checkbox to restart the system (if enable_auto_restart is enabled)

User Interaction¶

• User reads final message
• If checkbox is present: User can check "Restart system when closing" to reboot after closing
• User clicks Continue (labelled "Close") to close the installer
• If restart checkbox is checked, system reboots immediately after closing

When This Screen Appears¶

• Always shown after installation completes

Field Descriptions¶

Relevant YAML Fields¶

You can provide the final message via inline text or from a file:

Inline text (recommended):

final:
  title: "Installation Complete"  # Optional: shown in window title bar
  text: |
    Installation Successful!

    The software has been successfully installed to DH0:Apps.

    Next Steps:
    1. Read the README.txt file in the installation folder
    2. Run "DH0:Apps/bin/app" to start the software
    3. Consult the documentation at "DH0:Apps/docs/" for more information

    Thank you for using our installer!

Button States¶

Restart Checkbox Behavior¶

Complete YAML Example¶

Here's a comprehensive example using all available fields:

schema_version: 1

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

intro:
  text: |
    Welcome to the Software Installer

    This will install Version 2.0 on your system.

    System Requirements:
    - AmigaOS 4.1 or later
    - 50MB free disk space
    - Graphics card with 1024x768 support

    Click Continue to proceed.

licence:
  file: "LICENSE.txt"           # Resolved relative to script directory

packages:
  title: "Select Components to Install"
  target: "DH0:Apps/Software"
  list:
    core:
      title: "Core Runtime"
      text: "Essential runtime components"
      file: core-2.0.tgz        # Resolved relative to script directory
      version: "2.0"
      size: 20480
      tags: [required]

    docs:
      title: "Documentation"
      text: "User and API documentation"
      file: docs-2.0.tgz        # Resolved relative to script directory
      size: 5120
      tags:
      - optional

    games:
      title: "Game Pack"
      text: "Collection of classic games"
      url: https://example.org/games-2.0.tgz
      sha256: "abc123def456..."
      version: "2.0"
      size: 30720
      tags: [optional]
      depends_on:
        - core
      preinstall:
        - echo "Setting up games..."
      postinstall:
        - protect "%TARGETDIR%/games/bin/#?" +e

    source:
      title: "Source Code"
      text: "Complete source code for developers"
      url: https://example.org/source-2.0.tgz
      sha256: "def456ghi789..."
      version: "2.0"
      size: 10240
      group: "Developer Tools"
      tags: [developer, main files]
      depends_on:
        - core

final:
  text: |
    Installation Successful!

    The software has been installed to your chosen destination.

    To get started:
    1. Open a shell and run: cd DH0:Apps/Software && ./setup.sh
    2. Read the README.txt file in the installation folder
    3. Visit our website for updates and support

    Thank you for installing our software!

Additional Examples¶

The example above shows all available fields in one installer. For more practical examples tailored to different use cases and installation scenarios, check the examples folder included in the Amistaller archive. These files can be used as starting points for your own installers and provide guidance on common patterns and best practices.

Troubleshooting & Tips¶

Continue Button is Greyed Out on Packages Screen¶

Possible Causes:

1. No destination folder is set
2. Destination folder path is invalid or doesn't exist
3. Required disk space exceeds available space

Solutions:

• Click the destination button and select a valid folder, OR drag a folder onto the window
• Ensure the folder has write permissions
• Deselect some packages to reduce required space
• Verify the destination path exists

Tag Filter Doesn't Appear¶

Cause: No packages have tags defined

Solution: Add tags to at least one package entry in the YAML

Package Downloads are Failing¶

Possible Causes:

1. Incorrect URL in YAML
2. Network connectivity issue
3. SHA256 checksum mismatch (corrupted download)

Solutions:

• Verify the URL is correct and accessible
• Check your internet connection
• If using SHA256, verify the checksum value is correct
• The installer will retry on failure; you can skip the package

Missing Local Archive or Licence File¶

Cause: File specified in file: (package) or (licence) doesn't exist relative to the script directory

What Happens:

• For packages: Warning is printed at parse time; package becomes unavailable
• For licence: Warning is printed; inline text is used instead (if available)
• For header_image: Warning is printed; image is simply not displayed

Solutions:

• Ensure all files are placed in the same folder as your installer.yaml script
• Verify the filename matches exactly (case-sensitive)
• Use relative paths like docs/LICENSE.txt for files in subdirectories
• The installer will automatically check if files exist during startup

Example Directory Structure:

MyInstaller/
  ├─ amistaller                  (the executable, can be symlinked from C:)
  ├─ installer.yaml             (your config file)
  ├─ header.png                 (referenced as "header.png")
  ├─ LICENSE.txt                (referenced as "LICENSE.txt")
  ├─ archives/
  │  ├─ core-2.0.tgz            (referenced as "archives/core-2.0.tgz")
  │  ├─ docs-2.0.tgz
  │  └─ tools-1.0.lha
  └─ images/
     └─ banner.png              (referenced as "images/banner.png")

Scripts Not Running¶

Cause: preinstall or postinstall scripts may have issues

Solution:

• Ensure scripts are valid shell commands
• Test scripts manually before adding to YAML
• The installer logs script output; check the progress log

Installation Takes Longer Than Expected¶

Possible Causes:

1. Large package sizes or slow internet
2. Script execution overhead
3. Disk I/O bottleneck

Tips:

• Be patient during downloads
• Monitor the progress gauges
• Ensure your destination disk is not heavily fragmented

Drag & Drop Not Working¶

Possible Cause: Window manager may not support drag-drop

Solution: Use the ASL requester (click the destination button) instead

Path Resolution¶

All file paths in YAML (header_image, licence.file, package.file) are resolved relative to the directory containing the YAML script, not relative to PROGDIR (the directory where amistaller.exe is installed). This allows installers to be packaged as a self-contained folder with all resources together.

Three path forms are supported:

• Relative paths (e.g., images/banner.png): resolved from the script directory
• Leading-slash paths (e.g., /images/banner.png): walk up from the script directory (each / goes up one level)
• Absolute paths (e.g., SYS:images/banner.png): used verbatim as-is

Additional Notes¶

• Archive formats supported: All formats supported by the xad.library (e.g., .zip, .lha, and others)
• URLs support HTTP and HTTPS protocols
• Scripts are executed with working directory set to the target installation path
• The installer validates all YAML syntax before starting; malformed YAML will cause early error messages
• Package IDs are the mapping keys under packages.list, not a separate field
• Packages are selected by default; all selected packages will be installed
• Use depends_on to create dependencies between packages (snake_case, not camelCase)