Amiga Forever by Cloanto
 
Home Products
 
 
TITLE

Structure and Names of Emulation and System Files

 

TOPIC

This article describes parts of the Amiga Forever directory structure which apply to the emulation and operating system components.

 

DISCUSSION

Overview

All versions of Amiga Forever and C64 Forever use a common directory structure for the emulation, operating system and application storage subsystem, which for the Amiga originally took into account discussions with the developers of UAE and Fellow. The result is a unified directory structure for items like ROMs, ADFs, hardfiles (which we agreed to name "HDF" when using three-letter abbreviations), so that shared system files can be used by different emulators or titles.

In Practice

The following are some of the directories and files (including example-only items) which are distributed with Amiga Forever and C64 Forever:

Amiga Files/Demoscene/
Amiga Files/Demoscene/What a Demo (Inspired Group, 1987, Amiga).rp9
Amiga Files/Games/
Amiga Files/Games/Asteroid Invader II (Acme Games, 1986, Amiga).rp9
Amiga Files/Applications/
Amiga Files/Shared/
Amiga Files/Shared/adf/
Amiga Files/Shared/adf/amiga-os-134-workbench.adf
Amiga Files/Shared/adf/amiga-os-204-workbench.adf
Amiga Files/Shared/adf/amiga-os-310-workbench.adf
Amiga Files/Shared/adf/aros-20110625-boot.adf
Amiga Files/Shared/cd/
Amiga Files/Shared/cd/mycd.iso
Amiga Files/Shared/dir/
Amiga Files/Shared/dir/System/
Amiga Files/Shared/dir/System/C/
Amiga Files/Shared/dir/System/libs/
Amiga Files/Shared/dir/Work/
Amiga Files/Shared/hdf/
Amiga Files/Shared/hdf/workbench-211.hdf
Amiga Files/Shared/nvram/
Amiga Files/Shared/nvram/cd32.nvr
Amiga Files/Shared/rom/
Amiga Files/Shared/rom/amiga-os-310-a4000.rom
Amiga Files/Shared/rom/aros-20110625.rom
Amiga Files/Shared/rom/aros-20110625-ext.rom
Amiga Files/Shared/rom/rom.key
Amiga Files/WinFellow/
Amiga Files/WinUAE/
CBM Files/Demoscene/
CBM Files/Demoscene/Hello World (Inspired Group, 1982, C64).rp9
CBM Files/Games/
CBM Files/Games/Asteroid Invader (Acme Games, 1983, C64).rp9
CBM Files/Shared/rom/
CBM Files/Shared/rom/c-64-kernal.rom
CBM Files/Shared/rom/c-drive-1541.rom

The above "Amiga Files" directory refers to the system folder installed by Amiga Forever on Windows. To open the Amiga Files folder from within Amiga Forever select Open/Amiga Files from the File menu. This folder contains no Windows executables (e.g. WinUAE.exe is not stored here).

Beginning with Amiga Forever 2008, "Amiga Files" is also present on the CD or DVD root. Prior to Amiga Forever 2008, the above files were in the "Emulation" (instead of "Amiga Files") directory, also relative to the root of the medium or installation.

Windows-specific application files are on a separate "Windows" directory:

Windows/WinFellow/
Windows/WinFellow/WinFellow.exe
Windows/WinUAE/
Windows/WinUAE/WinUAE.exe

On Windows systems the content of "Windows" is installed inside "C:\Program Files\Cloanto\Amiga Forever".

C64 Forever follows a structure inspired from Amiga Forever, with the default content directory named "CBM Files" instead of "Amiga Files".

Windows Systems

In Amiga Forever 2005 the "Amiga Files" folder was introduced for enhanced long-term compatibility and security in the Windows versions of the software. This means that under Windows the common directory structure is stored in two physical directories, reflecting different access and execution privileges.

After installation of Amiga Forever under Windows, emulation-related data files, including Amiga operating system and application files (Amiga executables) can be accessed under:

%AMIGAFOREVERDATA%

Windows executables, including the emulation binary files for Windows, can be accessed under:

%AMIGAFOREVERROOT%

The two paths will generally point to different physical directories, referencing different parts (Windows binaries vs. other files) of the same overall structure outlined in this document.

For additional access instructions, please see:

Non-Windows Systems and Run-from-Medium

Since Amiga Forever 2008, "Amiga Files" also applies to the CD and DVD directory structure. Prior to that, the "Emulation" directory, stored at the root of the Amiga Forever medium, contained all files (software and data) which are related to the Amiga and its emulation.

Other directories at the root level, like "Windows", and other platform-specific directories, contain unrelated items which are not relevant to this document.

For programmatic access on Android systems, please see:

For programmatic access within the Chrome environment, please see:

All Systems (Windows and Non-Windows)

The directory containing the Amiga data files contains a "Shared" directory, where all shared Amiga files (ROMs, system disks, etc.) are grouped, and one or more emulator-specific directories. The level immediately inside "Shared" also contains unified names, which include "adf" (Amiga floppy disk image files, with .adf or .adz suffix), "cd" (CD images as .iso or .bin/.cue/.wav/.mp3), "dir" (directories mounted as Amiga volumes, e.g. "System" and "Work"), "hdf" (Amiga hardfiles, with .hdf or .hdz suffix), "rom" (Amiga ROM files with optional .key file) and "amiga_utilities" (emulation utilities in Amiga binary format, as they are distributed before installation).

The Amiga "Games" and "Demoscene" directories are respectively dedicated to games and demoscene productions. They are application-centric, containing one subdirectory per game or demo. Each application directory contains that application's files (e.g. disk images in any format, including floppy, CD, hardfile, etc.)

Amiga Forever operating system ADF files use the amiga-os-version-diskname.adf format for file names, where "amiga" denotes the Amiga hardware, "os" stands for "operating system", version is 100, 130, 204, 300, 310, etc. for version 1.0, 1.3, 2.04, 3.0, 3.1, etc., and diskname indicates the specific floppy disk. For example, the image file for the disk labelled "Workbench" of operating system version 2.04 is named "amiga-os-204-workbench.adf".

Amiga Forever Amiga ROM files follow the amiga-romtype-version-machinetype-ext.rom naming format, where romtype uses "os" to refer to standard operating system ROMs, "boot" indicates a boot ROM, "crt" indicates an external cartridge, and machinetype is a model-specific tag used for ROMs that have hardware-specific features, e.g. "cdtv", "cd32", "a1000", "a1200", etc. No hardware model tag is used for machine-neutral 68000 versions. Amiga-600 ROMs are compatible with other 68000-based Amiga models, however they are marked "a600" because they include scsi.device, card.resource and carddisk.device functionality. The optional "ext" part indicates an additional (extended) ROM, as used in the CDTV, CD³² and in AROS where the code cannot be stored all in a single ROM. As a rule of thumb, machine-specific versions are included where this is important for application compatibility. The Amiga 1000 boot ROM, which contains the code used to load the version-specific ROM from a Kickstart floppy disk, is version-neutral, and has no version number (it is named "amiga-boot-a1000.rom"). Since AROS uses the build date instead of version numbers, the "YYYYMMDD" format is used for the version part.

Directories inside "Shared/dir" are named after the volume name with which they are mounted. In Amiga Forever, the "Shared/dir" directory contains "System" and "Work". The System partition is prepared in such a way as to boot and function properly even if the Work partition is not mounted. The System partition can be upgraded as new versions of the operating system are released. Amiga Forever includes older operating system versions, such as Workbench 1.3, only in ADF format.

It is recommended to use suffixes for file names wherever possible, and in particular for documentation files. Several operating systems, not just DOS and Windows, make it possible to recognize file types and associate them to the correct viewer, based on the suffix. Under Windows, if a "readme" file ends with .txt, .htm or .html, then it can easily be opened with one or two mouse clicks. Otherwise the only party that wins is user frustration. Other suffixes used in Amiga Forever are .rp9, .hdf, .adf and .rom.

Ideally, each distribution which has one or more documentation files would also contain an index.html or index.htm file which links all the files together, whether they are text or HTML files. Complex projects, like UAE, could have an index file for each component maintained by a different person, whether that be the base UAE documentation, the Polish translation, or the Windows port. Once a standard is agreed on for the directory containing each index file, nobody would have to worry any more about broken links, and the same files could be used both in the regular distribution, and for online reading.

The rom.key file, which is the Amiga Forever ROM encoding key (as originally requested by some of Cloanto's licensors), should be placed in "Shared/rom".

It is recommended not to embed version names in the names of executable files. If the file name for the emulation software executable remains constant, the user's scripts and links will continue to work properly even after upgrades to the software.

Relative Paths

Emulation settings files which are redistributed should not contain paths which are absolute to a certain drive on the machine on which they were created. For example, on a Windows computer, the "Work" volume should be mounted as "%AMIGAFOREVERDATA%\Shared\dir\Work", and not as "C:\MyPrograms\Emulation\Shared\dir\Work". This makes it possible for settings files to be used on different computers and configurations. Similarly, on a run-from-CD compilation the "Work" volume should be mounted as "..\Shared\dir\Work", rather than as "D:\Emulation\Shared\dir\Work".

Read-Only Media

Emulation code, add-ons and configurations should work properly even on a read-only medium. This makes it possible to publish a configuration on a CD, and use it without installing it. Many work and school environments have security policies about installing software which make running applications from CD a rare but very appreciated feature. Cover CDs are also a case where users might prefer to run applications directly from CD.

The Amiga Forever player supports "virtual writing", i.e. for games and other applications that require write access to a disk in order to start or otherwise properly, it provides virtual read/write images (feature supported for ADF, ADZ, HDF and HDZ - if running from read-only media, change are lost at the end of the emulation session).

Related Links

 

Article Information
Article ID: 15-101
Platform: All
Products: Amiga Forever, C64 Forever
Additional Keywords: None
Last Update: 2014-04-07
Your feedback is always appreciated. It is safe to link to this page.