This document explains how to create self-installing packages similar to AmiKit and AmigaSYS in Amiga Forever.
Setting up a new add-on in Amiga Forever can be described in a practical way by explaining how entries are added to two configuration text files:
- Software Director INI file sections to describe download source URL and destination directory
- Amiga Forever RP9 manifest entry for the item, referencing the Software Director download item as well as Amiga Forever configuration information
AmiKit and AmigaSYS will be used as a reference in this example. Both have some content that is contained in a ZIP archive, which is installed via Software Director into the "Shared" directory of Amiga Files. More specifically, mounted directories go into Shared/dir, and hardfiles go into Shared/hdf. AmiKit has one mounted directory. AmigaSYS has both a directory and a hardfile.
Both AmiKit and AmigaSYS, like other popular add-ons, have a one-time initial setup phase during which they copy system files from an existing source.
In the player, the user initially sees the addon entry marked with a Status of "Download" (if advertised but not installed), then this changes to "Setup" (one time only, until setup is complete), and after that it is "Ready" or "Running", "Paused" or "Saved".
Software Director needs to reference a file anywhere in the addon that contains either an Amiga VER$ string, or a version in an INI file, or a version in the first line of a text file. The preferred version format is the dotted notation, as in x.x, x.x.x or x.x.x.x.
This does not work inside HDF files (see below).
Access to Documentation
Amiga Forever can reference HTML, PDF or text documentation in the addon. This can be accessed by the user from the player even without running the application.
This does not work inside HDF files (see below).
"Ready to Setup" Marker File (XML: "precondition")
Amiga Forever checks for the existence of one file in the addon distribution to confirm that the addon has been downloaded and extracted successfully. This may for example be the same file that is also the root of the documentation, or it can be another file.
If the "Ready to Setup" marker file is present and the "Setup Complete" marker file is not present, the Status indication in the player is "Setup" to indicate to the user that the first time the configuration is run it will perform an initial setup. Also, during the Setup phase the addon can access an additional read-only partition from which to copy files from the Amiga Forever "Workbench 3.X" configuration. By default, these source directories are "AF-Setup:System" and "AF-Setup:Work". "AF-Setup:System" may or may not include (setup should be failsafe) "Fonts/_TrueType" (same name as AmigaOS 4.0) and "Devs/kickstarts" (WHDLoad ROMs, including .rdb files). The C directory includes a "Shutdown" command that can be used to terminate the session.
Because of the possible interaction between writes to HDF and data written to a mounted directory, changes applied by the Setup phase are always permanent (the Undo/Commit option is unavailable). It is strongly recommended to have the setup phase end with a final confirmation/status message to the user, followed by the creation of the "Setup Complete" Marker File, followed by the execution of "AF-Setup:System/C/Shutdown" command. Allowing the addon configuration to run after the setup may be confusing and would be inconsistent with the setup experience of other addons.
"Setup Complete" Marker File (XML: "complete")
Amiga Forever checks for the existence of one file in the addon distribution to confirm that the addon has completed its one-time setup. This causes the Status information in the player to change from "Setup" to "Ready". The additional read-only partition (default name "AF-Setup") is not present any more at this stage. If the "Setup Complete" marker file is present and the "Ready to Setup" marker file is not present, the Status indication in the player remains "Ready".
Hardfiles vs. Mounted Directories
Hardfiles preserve Amiga filenames and attributes in a cross-system fashion, at the possible cost of some extra space occupation in the host environment. Hardfiles cannot be accessed by Software Director for version checking, nor by Amiga Forever to link to documentation.
Mounted directories generally work well, and behave as Amiga CD-ROM and network file systems have done since 1990 or so, i.e. lacking certain Amiga-specific attributes (e.g. AmigaDOS script files must be run via Execute, and not counting on implicit behavior determined by S flag), and requiring some care for characters > 128 in file and directory names. Once installed, these files work well on Windows. However, the names may be corrupted in the Zip/Unzip process. If your directory-based (opposed to HDF-based) distribution has file names with characters > 128, as used in Amiga locale names, please double-check with us how to best do this, so that this information is not lost in the Zip/Unzip process. AmiKit solved this problem by including a subset of file names into an extra LhA archive, which is extracted in the one-time initial setup procedure.
For the purpose of embedding version information and allowing Amiga Forever to directly open a documentation file (e.g. HTML contained in your distribution), it is recommended to always have a directory, even if it is a small directory that only contains version information and documentation (the version string may even be embedded in one of the HTML documentation files).
Uninstalling/Resetting the Addon Configuration
The <addon> tag supports description of simple delete-based uninstall information by means of one or more <uninstall> tags. If one or more <uninstall> tags are present, a capable player (e.g. Amiga Forever 2012 or higher) will display an "Uninstall" option in the right-click menu for the title.
Uninstalling or resetting the addon to force a new installation can also be done manually. For example, in Amiga Forever:
- Select Open/Amiga Files from the File menu
- Go inside Shared/dir and/or Shared/hdf
- Delete the directory and/or hardfile
- If the player is still open, press F5 to force a refresh of the list
Sample Software Director Entries
The following two sections indicate where the version string is found in the cases of AmiKit and AmigaSYS. The files are parsed top to bottom, stopping at the first file that is found. In this example, Software Director first looks for Amiga Forever 2010, then for Amiga Forever 2009.
The following section indicates the location of the "Amiga Files/Shared" directory.
[InstalledVersion] ID = "installedversion-amikit" Application = "HKEY_LOCAL_MACHINE\SOFTWARE\Cloanto\Amiga Forever\2010.0\AmigaFiles", "Shared\dir\AmiKit\Prefs\Env-Archive\AmiKitVersion" Application = "HKEY_LOCAL_MACHINE\SOFTWARE\Cloanto\Amiga Forever\2009.0\AmigaFiles", "Shared\dir\AmiKit\Prefs\Env-Archive\AmiKitVersion" [InstalledVersion] ID = "installedversion-amigasys" Application = "HKEY_LOCAL_MACHINE\SOFTWARE\Cloanto\Amiga Forever\2010.0\AmigaFiles", "Shared\dir\AmigaSYS4-Work\Documentation\start.html" Application = "HKEY_LOCAL_MACHINE\SOFTWARE\Cloanto\Amiga Forever\2009.0\AmigaFiles", "Shared\dir\AmigaSYS4-Work\Documentation\start.html"
[Path] ID = "path-amigafiles-shared" Path = "HKEY_LOCAL_MACHINE\SOFTWARE\Cloanto\Amiga Forever\2010.0\AmigaFiles", "Shared" Path = "HKEY_LOCAL_MACHINE\SOFTWARE\Cloanto\Amiga Forever\2009.0\AmigaFiles", "Shared"
The following two sections indicate the URL of the ZIP file and the destination (target) directory.
[Action] ID = "action-amikit-download" Type = Download Subtype = Generic, Update Flags = Install, Archive Privileges = Standard Version = 159 Date = 2009-06-04 Bytes = 172869388 Resource = "http://example.com/amikit.zip", "path-amigafiles-shared" [Action] ID = "action-amigasys-download" Type = Download Subtype = Generic, Update Flags = Install, Archive Privileges = Standard Version = 22.214.171.124 Date = 2009-06-05 Bytes = 48392479 Resource = "http://example.com/amigasys.zip", "path-amigafiles-shared"
Sample Amiga Forever Entries
The following XML sections in the rp9-manifest.xml file illustrate how all the parts described so far are combined to form the working end result.
<application> <description> <title>AmiKit</title> ... </description> <addon> <download type="softwaredirector">item-amikit</download> <setup precondition="Shared\dir\AmiKit\Prefs\Presets\AmiKit\Doc\amikit.amiga.sk\what-is-it.htm" complete="Shared\dir\AmiKit\Prefs\Env-Archive\AmiKitAFDone" root="data"></setup> <uninstall action="delete">Shared\dir\AmiKit</uninstall> </addon> <media> <harddrive root="data">Shared\dir\AmiKit</harddrive> <harddrive root="data" volumename="AF-Setup" readonly="true" addonsetup="true">Shared\dir</harddrive> </media> <configuration> <system>a-amikit</system> <compatibility>mouse-integration</compatibility> <peripheral>automount-removable</peripheral> </configuration> </application> <application> <description> <title>AmigaSYS</title> ... </description> <addon> <download type="softwaredirector">item-amigasys</download> <setup precondition="Shared\dir\AmigaSYS4-Work\Documentation\start.html" complete="Shared\dir\AmigaSYS4-Work\AmigaSYSAFDone" root="data"></setup> <uninstall action="delete">Shared\hdf\AmigaSYS4.hdf</uninstall> <uninstall action="delete">Shared\dir\AmigaSYS4-Work</uninstall> </addon> <media> <harddrive root="data">Shared\hdf\AmigaSYS4.hdf</harddrive> <harddrive root="data" volumename="Work">Shared\dir\AmigaSYS4-Work</harddrive> <harddrive root="data" volumename="AF-Setup" readonly="true" addonsetup="true">Shared\dir</harddrive> </media> <configuration> <system>a-amigasys</system> <compatibility>mouse-integration</compatibility> <peripheral>automount-removable</peripheral> </configuration> </application>
Additional Information and Steps
The configuration referenced in the
Contact us for additional information, and to set up a supported download location, entries in Software Director and Amiga Forever, and assigning a unique application ID.
For high-quality addons we are happy to host the archive on our servers, which is also a way to ensure continuity once the entry has been added to the Amiga Forever tab. You can of course also use this information to edit the RP9 manifest yourself, and create your own directory or hardfile, rather then installing one with Software director.
It is safe to link to this page.