Whilst Trance, the MorphOS m68k emulator, is able to execute Motorola m68k code, Trance runs in a shared space inhabited by MorphOS while Trance maps Amiga primitives to MorphOS. In other words, Trance is the opposite of containerization; it is an emulation layer designed a shim to be able to execute m68k code completely transparently by blending MorphOS and AmigaOS.

When developing programs, even though toolkits and compilers allow targeting different platforms and in spite of the fact that MorphOS has the exactly same structure like AmigaOS, it becomes useful to test applications in their native environment and with the constraints of the target platform.

For example, while Hunt and Gather runs flawlessly on MorphOS via Trance, because the distributed binaries are nothing more than m68k code, "Hunt and Gather" is a project that was designed to maintain constant memory complexity throughout its execution such that "Hunt and Gather" should work great even on an A500 with a 68000 CPU and up to 512KiB or 2MiB of RAM. Now, testing "Hunt and Gather" on MorphOS can be a little confusing, namely because MorphOS, being actively developed, patches most of the well-known AmigaOS bugs, such that iff. a program runs on MorphOS, even via an emulation shim like Trance, it is not an absolute guarantee that it would run on a native Amiga.

Other possible applications would include testing out software packages, in particular crapware and other paraphernalia that one would not want to install directly into the MorphOS operating system.

Aside from Trance, Amiga games, in particular those bundled by WHDLoad, are ran under MorphOS using an Amiga emulator such as the E-UAE emulator that seems to be the most popular. That is, MorphOS is an "Amiga-inspired" operating system running on the PowerPC, that has an m68k emulator shim named Trance and that is able to run Amiga games via an emulator such as E-UAE. Now, running Amiga games via an emulator is not so bad intrinsically because games were the primary way to get infected with virii. However, the isolation principle also serves for development when binaries would have to be tested out in their native environment. In fact, E-UAE and other emulators as well, pride themselves with the fact that they are able to provide clock-exact compatibility between the Amiga and the emulator environment. Creating an emulator is a tedious task because it would require implementing or rather virtualizing the Amiga chipsets using software methods (Amiga chipsets are very roughly the equivalent of dedicated ISA/PCI cards on the PC, with CIA being tasked with I/O and Paula, Denise and Alice all having roles from sound rendition to graphics rendering, aside from m86k Motorola CPU that, given the chipsets, was not all that important - arguably, it's the chipsets that made the Amiga, nor the CPU).

Setting up E-UAE itself is a matter of obtaining the E-UAE package and running the installer script. Typically, users would want to install E-UAE with the WHDLOpener package that allows conveniently running WHDLoad games just by clicking their icon in Ambient.

Interestingly, the E-UAE 1.0.0 package continued by Kjetil Hvalstrand has some "goodies" inside that hint to the usage that "WHDLOpener" already implements. Namely, there's an ARexx script called uaeexe.rexx that is meant to run programs within an environment emulated with E-UAE. Specifically, the script first starts E-UAE with a configuration file, then waits for a tool named uae_rcli to make an ARexx port available and then finally sends a command via the ARexx port in order to execute a command from the local filesystem inside the emulated environment. The emulator configuration used by uaeexe.rexx typically maps the local drives into the emulated Amiga environment in order to make the file to be executed from MorphOS available.

When it is all put together, an m68k executable or Amiga script on MorphOS is right-clicked from Ambient and conveniently the Run (UAE)... menu option is selected that will perform all the mentioned steps to run the executable or script within the emulated environment.

The ARexx script provided with E-UAE uaeexe.rexx is not that great such that we have rewritten the script for the purpose of this tutorial.

/*************************************************************************/
/*    Copyright (C) 2025 Wizardry and Steamworks - License: GNU GPLv3    */
/*************************************************************************/
/* Concatenates two filesystem paths a and b together.                   */
/*************************************************************************/
Parse Arg path
 
/*************************************************************************/
/* Configuration                                                         */
/*************************************************************************/
uaedir       = "SYS:Tools/E-UAE"
uaepath      = "SYS:Tools/E-UAE/e-uae"
uaeconfig    = "SYS:Tools/E-UAE/Conf/A1200_uaeexe.conf"
 
/*************************************************************************/
/* Internals                                                             */
/*************************************************************************/
uaeport      = "UAE" /* don't touch this one */
 
/* delete the quotation marks from the path if they exist */
i = Index(path, '"')
If i > 0 Then Do
    path = DelStr(path, i, 1)
End
i = lastpos('"', path)
If i > 0 Then Do
    path = DelStr(path, i, 1)
End
 
/* run UAE if it's not already running */
If Pos(' '||uaeport, Show('p')) = 0 Then Do
    Pragma('D', uaedir)
    Address COMMAND 'run > nil: '||uaepath||' -f '||uaeconfig
    Address COMMAND 'waitforport '||uaeport
End
 
/* wait for UAE DOS to be available */
Say 'Waiting for environment...'
Do LOOP=1 Until LOOP = 0
    Address COMMAND 'wait '||1
    Address UAE 'UAEEXE run <>NIL: version'
    LOOP=RC
End
 
/* resolve real path to emulation path */
resolvedpath = resolve(uaeconfig, path)
Say 'resolved: '||resolvedpath
Say 'Executing command...'
 
/* run the command */
ADDRESS(uaeport)
UAEEXE 'run '||resolvedpath||' >CON:0/0/1000/1000/UAE/AUTO/WAIT/CLOSE'
 
Exit
 
/* subroutine used to resolve MorphOS paths to emulator paths */
resolve:
    Parse Arg config,path
 
    If Open(f, config, 'R') ~= 0 Then Do
        done = 0
        Do While ~Eof(f) & ~done
            line = Readln(f)
            Parse Var line comment'filesystem='mode','volume':'hostpath
            If comment ~= '#' & volume ~= ''& hostpath ~= '' Then Do
                p = Pos(Upper(hostpath), Upper(path))
                If p > 0 Then Do
                    resolvedpath= volume':'Substr(path, Length(hostpath) + p)
                    done = 1
                End
            End
        End
        Close(f)
    End
    Return resolvedpath

The script should be placed at SYS:Prefs/Ambient/scripts/uaeexe.rexx and not within MOSSYS: as the E-UAE documentation would indicate.

The script is very straightforward, it will start E-UAE with a given configuration, then it will wait for Workench to load, specifically, for the C:version command to execute, and then it will finally run the executable selected from Ambient within E-UAE.

The E-UAE configuration at SYS:Tools/E-UAE/Conf/A1200_uaeexe.conf contains the necessary configuration parameters for E-UAE along with the MorphOS drive mappings. In this case, the machine that will run the selected executable will be an 68020 Amiga 1200 machine with 2MiB of chip RAM and 8MiB of fast RAM. Additionally, the emulation is configured to be "exact", that is, E-UAE will not use its optimizations such as JIT to speed up the emulation.

# kickstarts
kickstart_rom_file=PROGDIR:Roms/kick40068.A1200
kickstart_key_file=PROGDIR:Roms/rom.key

# drive mappings
filesystem=rw,Workbench:PROGDIR:HardDisks/AOS31EXE
filesystem=rw,Games:Games:
filesystem=rw,Work:Work:
filesystem=rw,Boot:Boot:
filesystem=rw,System:System:

filesys_nofsdb=true

# cpu settings

cpu_type=68020
cpu_speed=real
cpu_compatible=true
cpu_cycle_exact=true

# chipset settings

chipset=aga
#immediate_blits=true
#fast_copper=true
#collision_level=full
blitter_cycle_exact=true

# LEDs
show_leds=true

# memory settings
#fastmem_size=4
#chipmem_size=4
#z3mem_size=4
chipmem_size=2
fastmem_size=8

# gfx settings

gfx_width=640
gfx_height=512
gfx_width_windowed=640
gfx_height_windowed=512
gfx_width_fullscreen=640
gfx_height_fullscreen=512
gfx_lores=no
#gfx_colour_mode=8bit
gfx_linemode=double
#double, none, scanlines
gfx_center_horizontal=true
gfx_center_vertical=true
#gfx_fullscreen_amiga=yes
#gfx_fullscreen_picasso=yes
#gfx_vsync=true
#show_leds=true
#gfxcard_size=32

# sound settings (sound_output="normal" or "none")
#                (sound_channels="stereo or "mono" or "mixed")
#                (sound_bits="8" or "16")

sound_output=normal
sound_bits=16
sound_channels=stereo
sound_frequency=44100

# joy <n> where n is lowlevel unit in amigaos target. In SDL target it's the enumeration order.
#joyport0=mouse
#joyport1=kbd2
joyport0=mouse
joyport1=joy1

# overlay display
amiga.use_overlay=false

# screen type (public, custom or ask)
amiga.screen_type=public

# slow and endianess issue.Better don't use
#sdl.use_gl=yes

The emulation is configured to run in a 640 by 512 window on the MorphOS desktop. Note that the paths mentioned in the configuration file, namely:

filesystem=rw,RAM2:RAM:
filesystem=rw,Games:Games:
filesystem=rw,Work:Work:
filesystem=rw,Boot:Boot:
filesystem=rw,System:System:

are drives that exist on MorphOS and they are mapped because the script is meant to run from the Ambient desktop such that the drives that exist on MorphOS are mapped onto the drives within the emulation. Note that his setup can be used to launch programs within UAE from within the MorphOS RAM: drive even if it conflicts with the emulation environment RAM: mount because the MorphOS RAM: drive is mapped to RAM2: within the emulation environment and then RAM2 is resolved by uaeexe.rexx to the proper RAM: drive on MorphOS.

The last piece of the puzzle is given away by the E-UAE configuration from the previous section, namely the drive mapping:

filesystem=rw,Workbench:PROGDIR:HardDisks/AOS31EXE

maps the MorphoOS path PROGDIR:HardDisks/AOS31EXE to a drive named Workbench within the UAE emulation environment. PROGDIR will resolve to where E-UAE was installed and the folder that is mapped is under HardDisks/AOS31EXE.

The AOS31EXE contains an Amiga Workbench install. In this case, the name is a dead giveaway "AOES31EXE" as in "Amiga OS 3.1 Execute". Given that the emulator already emulates the kickstart and the necessary routines to boot a hard-drive, then the "AOS31EXE" folder on the MorphOS drive can just be populated with the bare-minimal files to boot "Workbench". In reality, only an S:Startup-sequence is needed but since we'd like a full environment, a Workbench 3.1 diskette ADF is mounted in MorphOS and all the files copied to AOS31EXE.

Or, in therms of commands, first create the AOS31EXE directory and then copy the contents of the Workbench ADF mount from FILE0: to the AOS31EXE folder.

makedir SYS:Tools/E-UAE/HardDisks/AOS31EXE
copy all clone FILE0:#? SYS:Tools/E-UAE/HardDisks/AOS31EXE

where it is assumed that E-UAE is installed at SYS:Tools/E-UAE.

Even though the Amiga has had a rough time with default icons and tools, more recent AmigaOS variants, including the side-evolution that is MorphOS have solved the matter of identifying files with MIME type resolution. That is, by going to the Ambient menu and selecting Ambient... and then navigating to Mime, it is possible to create menu items that should show up when a given file type is right-clicked.

In this case, a general action is configured that will apply to all files when they are right-clicked and will offer the menu option Run (UAE)... that can be used to run the right-clicked file in UAE.

Note that this is a bit general and it will offer a Run (UAE)... menu item even when a simple text-file is clicked, in which case the uaeexe.rexx script will dumbly try to execute the file within UAE. It might be possible to further restrict the menu option to more specific file types by playing around with the MIME types available.