Introduction
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
Cloanto's AmiKit and AmigaSYS
distributions 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
Amiga OS 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".
Version Checking
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" 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 Folder/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.
[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"
The following section indicates the location of the "Amiga Files/Shared" directory.
[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 = 4.0.0.0
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 <configuration> tag is a combination of an .ini file (e.g. for Vista/7 x64 inside "C:\Program Files (x86)\Common Files\Cloanto\RetroPlatform\Player\Plugins\WinUAEPlugin") and data that is built at run time by the player. If the existing configurations are not sufficient for your needs, a new configuration can be set up.
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.
Related Links
