Welcome, Guest. Please login or register.

Author Topic: XAmiga : How to -- A minimal Linux for E-UAE  (Read 29382 times)


0 Members and 1 Guest are viewing this topic.

Offline FraccyTopic starter

  • Jr. Member
  • **
  • Join Date: Jan 2006
  • Posts: 64
    • Show only replies by Fraccy
XAmiga : How to -- A minimal Linux for E-UAE
« on: February 25, 2007, 04:11:18 PM »
X-Amiga 'How-To'
A minimal Linux for E-UAE


This is a step-by-step guide to setting up a minimal version of Linux which can run E-UAE.

What makes this better than other emulation options? Well, this one is light, fast and streamlined - more optimized than anything else out there. The Linux part of the installation takes just 16MB of hard drive space. Bootup times can be as fast as 15s - almost as fast as a real Amiga. The underlying Linux is very simple to understand and work with; in fact, the directory structure turns out to have more similarities with the Amiga than one might expect. E-UAE also gains the wide hardware support of Linux.

Unfortunately, the process isn't as simple as installing from a CD or setup-file. This method involves some effort because the packages have to be compiled specifically for your computer. Although this guide appears verbose and ponderous, I'm just trying to cover all the details; it's really not too difficult!

This guide parallels the usual installation procedure for an embedded Linux system; the following references may be useful:

Gentoo Embedded x86 Guide

BTW, why 'X-Amiga'? Well, Apple appended X to their Unix-based OS, and this is a Linux-based Amiga emulation, so...

Technical details at a glance

  *  Based on Gentoo Linux
  *  Uses the framebuffer for graphics display - up to 1600x1200x32 using DirectFB and SDL
  *  Full system - with graphics, networking & sound - consists of just 15 packages (depending on hardware support)


Only one problem at present: the keyboard isn't 100% working (only lower case letters and numbers work). This is an E-UAE issue which could be fixed at any time.

Other things to be aware of:

DirectFB (used by SDL for display on the framebuffer) may have limited support for some graphics cards. More information at: www.directfb.org

If there's no driver for your card, you can use the generic VESA driver - but it won't have any hardware acceleration.

I haven't tested everything yet (such as sound). But I can verify that my laptop boots into Workbench (RTG, 1024x768x16bit) with wireless networking, and so far all applications have worked without problems! (Note: DirectFB supports up to 32bit colour resolution.)


Linux actually refers to the kernel. To make a computer usable, extra packages have to be installed to work alongside the kernel. A Linux distribution such as Ubuntu or Knoppix consists of many software packages which work together to give a complete desktop environment. However, in this case, we need only a very simple system - enough to kick-start the Amiga emulation.

You'll first need to set up Gentoo Linux on your computer. Gentoo is the most convenient distribution for this task, since the packages are easy to install and customize.

Part of the Gentoo installation process involves configuring the kernel specifically for your computer. You'll need to find out all the details of your computer's hardware beforehand, either from the technical specifications, the manufacturer's website, or by physical inspection. Kernel configuration may take a while, but it's relatively straightforward.

Once your computer is working properly, you'll use it as a host to set up a minimal Linux/Amiga system in a target directory, which will finally be copied to another partition or drive.

The process is very similar to setting up embedded Linux on a small system. We're using BusyBox, a package which combines the essential Linux commands into a single executable (imagine having the contents of the Amiga c directory all in a single file). However, whereas most embedded systems use uclibc (a very small C library), we're sticking to the standard glibc for maximum compatibility.

There are two ways to have a graphical display in Linux. One is to use X windows, which is rather complicated, and avoided here. The simplest is to use the framebuffer - this uses the kernel to access the graphics hardware directly. It's like having graphics in AmigaDOS without having to start Workbench.

This is a list of Gentoo packages to be installed:

Base System:
Code: [Select]
[color=800000][b]Package[/b] [b]Description[/b][/color]

[color=404040]sys-apps/baselayout-lite Baselayout for embedded systems
sys-apps/busybox Linux utilities for small systems
sys-apps/hotplug Monitors plugging in or removal of devices, configuring them for immediate use
sys-apps/hotplug-base Base hotplug framework
sys-fs/udev Works with hotplug to ensure that /dev matches devices present on your system
sys-libs/glibc GNU C library

Code: [Select]
[color=800000][b]Package[/b] [b]Description[/b][/color]

[color=404040]dev-libs/DirectFB Provides graphics & input device handling on top of the Linux framebuffer
media-libs/audiofile Provides access to variety of audio file formats
media-libs/libsdl Simple DirectMedia Layer multimedia library
media-libs/alsa-lib Advanced Linux Sound Architecture library for sound cards
media-sound/alsa-utils ALSA utilities (alsamixer, etc.)
sys-libs/zlib Data compression library
app-emulation/e-uae Amiga emulator

Code: [Select]
[color=800000][b]Package[/b] [b]Description[/b][/color]

[color=404040]net-wireless/wireless-tools Tools to configure wireless LAN cards
net-misc/dhcpcd DHCP client


  *  A computer running Gentoo Linux. Visit www.gentoo.org and follow the detailed installation instructions! If you encounter any problems, the Gentoo forums are an invaluable source of information and help.
  *  A fast internet connection!
  *  A spare partition or second hard drive, since the intention is to be able to boot into the new Linux/Amiga build. (Keep this in mind before installing Gentoo.)


1. Create a directory for the installation

This is going to be the target directory for the Linux/Amiga installation.

[color=800000]Listing 1: Create target directory[/color]
Code: [Select]
   > mkdir /target[/color]

2. Modify /etc/make.conf

This specifies hardware for DirectFB and ALSA, and cuts out unnecessary items when installing packages (such as manuals, documentation, etc.) It might be a good idea to first back up the previous make.conf...

Note: there's no need to change the previous values for CFLAGS and CHOST. However, note the new USE flags: everything is disabled by '-*' except for the essentials: alsa, directfb, sdl, fbcon (for sound and framebuffer); nptl, nptlonly, userlocales (for glibc).

Also note that I've replaced various entries with '...', indicating that there should already be something typed there, or that you need to enter something of your own. Don't type just those dots!

Make sure you select the appropriate INPUT_DEVICES and VIDEO_CARDS from the list, and delete the rest. You'll probably need only one video card ;-) Sensible input devices are "keyboard ps2mouse linuxinput"...

For the ALSA_CARDS flag, select the driver for your card from the list of ALSA cards at the alsa web site: www.alsa-project.org/alsa-doc/

[color=800000]Listing 2: Modify /etc/make.conf[/color]
Code: [Select]
   > nano /etc/make.conf

        USE="-* make-symlinks alsa directfb fbcon sdl nptl nptlonly userlocales"
        USE="mmx sse"
        INPUT_DEVICES="dbox2remote elo-input gunze h3600_ts joystick keyboard dreamboxremote linuxinput
          lirc mutouch none permount ps2mouse serialmouse sonypijogdial wm97xx"
        VIDEO_CARDS="ati128 cle266 cyber5k i810 i830 mach64 matrox neomagic nsc nvidia radeon savage
          sis315 tdfx unichrome"
        FEATURES="ccache nodoc noinfo noman"

3. Emerge packages into /target

In this step we'll install ('emerge', in Gentoo terminology) all the major packages. First the base system, all in a single step. Of course, you're free to emerge each package one at a time. Wait a few hours while it all compiles...;-)

(Note the first line: baselayout-lite is still not finalized as a Gentoo package, so it's necessary to enable it in package.keywords)

[color=800000]Listing 3a: Emerge the base system[/color]
Code: [Select]
   > echo "sys-apps/baselayout-lite -*" >> /etc/portage/package.keywords
    > ROOT=/target emerge -O baselayout-lite busybox hotplug hotplug-base udev glibc

Now install E-UAE packages...

[color=800000]Listing 3b: Emerge E-UAE packages[/color]
Code: [Select]
   > ROOT=/target emerge -O directfb audiofile libsdl alsa-lib alsa-utils zlib e-uae[/color]

4. Chroot into /target and set passwords

Now that it's set up, we need to enter the target system to configure it. Since Linux is a multiuser OS, each user needs to have a password. The 'root' user is the top-level user (i.e. administrator), so it's important to at least set the root password.

Note: 'chroot' = 'change root'.

[color=800000]Listing 4a: Set root password[/color]
Code: [Select]
   > chroot /target /bin/ash
    > passwd

We also should add a regular user. Without this step you wouldn't be able to log in as anything other than root. Substitute your preferred username for 'username' below.

[color=800000]Listing 4b: Add user[/color]
Code: [Select]
   > addgroup -g 100 users username
    > adduser -h /home/username -s /bin/ash -G users username

Finally, exit the target environment.

[color=800000]Listing 4c: Exit chroot[/color]
Code: [Select]
   > exit[/color]

5. Tidy up base system

Some files may need to be added manually. Make sure the following directories are present in /target/dev (if not, copy these over from your host):

/dev/fb (needed for DirectFB)
/dev/input (needed for mouse)
/dev/snd (both needed for ALSA)

Create /proc and /sys directories in /target (needed by udev, and for poweroff & reboot):

[color=800000]Listing 5a: Create /proc and /sys[/color]
Code: [Select]
   > mkdir /target/proc
    > mkdir /target/sys

To make the system as small as possible, several directories can be safely deleted from /target.

[color=800000]Listing 5b: Remove redundant directories[/color]
Code: [Select]
   > rm -rf /target/var/cache /target/var/db /target/var/lib
    > rm -rf /target/usr/include /target/usr/lib/pkgconfig /target/usr/share/aclocal

6. udev and hotplug

You'll need to download the udev startup script 'init-udev' for BusyBox and make sure it's present in /target/etc/init.d

Note: wget works at the moment, but the file name or location may change. If you need to use a browser, you can find the link to 'init-udev' at busybox.net/cgi-bin/viewcvs.cgi/trunk/buildroot/package/udev/?rev=10953

[color=800000]Listing 6a: Download init-udev[/color]
Code: [Select]
   > cd /target/etc/init.d
    > wget http://busybox.net/cgi-bin/viewcvs.cgi/*checkout*/trunk/buildroot/package/udev/init-udev?rev=10487

/dev is populated with device nodes on bootup, but udevstart is needed to detect new devices. Edit init-udev and uncomment the line 'echo $UDEV_BIN > /proc/sys/kernel/hotplug':

[color=800000]Listing 6b: Edit init-udev[/color]
Code: [Select]
   > nano /target/etc/init.d/init-udev

        # heck, go whole-hog:  use only new style hotplug
        echo $UDEV_BIN > /proc/sys/kernel/hotplug

7. Sound

First make sure sound is working properly on your Gentoo host computer! Use alsamixer to unmute the channels, and set the levels as you wish. The following step will ensure there's sound in the Linux/Amiga system.

[color=800000]Listing 7: Copy alsa configuration to /target[/color]
Code: [Select]
   > alsactl store
    > cp /etc/asound.state /target/etc

8. Edit the startup script

The Amiga uses a startup script, and so does Linux! Here it's located in /target/etc/init.d, and we're going to add some lines to the end of it to make sure everything starts properly. (Remember not to type those dots! They only indicate that there's some configuration stuff preceding this.)

[color=800000]Listing 8: Edit /etc/init.d/rcS[/color]
Code: [Select]
   > nano /target/etc/init.d/rcS

        # udev startup
        /etc/init.d/init-udev start

        # Reset sound levels
        alsactl -f /etc/asound.state restore

9. Copy /boot to /target

You configured the kernel when you first installed Gentoo, so there's no need to redo it. This step only copies /boot to the /target directory to make it bootable. /target will eventually end up on its own partition.

[color=800000]Listing 9: Copy /boot to /target[/color]
Code: [Select]
   > cp -a /boot /target[/color]

10. Amiga things

Now let's create a directory for the Amiga installation, and make sure that .uaerc points to it correctly.

Note the upper case 'A' in 'Amiga' - Linux is case sensitive, so if you use 'Amiga' here, stick to it.

[color=800000]Listing 10a: Create Amiga directory[/color]
Code: [Select]
   > mkdir /target/Amiga[/color]

Note that this next portion of text has been extracted from the .uaerc file; it's only here to illustrate how to point to the correct directories. (As usual, ignore the '...' entries.)

[color=800000]Listing 10b: Edit .uaerc[/color]
Code: [Select]
   > nano /target/root/.uaerc



11. Create a separate partition for the installation

In order to boot into it, the custom Linux/Amiga should be set up in a separate partition or even another drive. My primary partition (/dev/hda1) contained the main Gentoo installation, so I prepared my second partition (/dev/hda2) for the Linux/Amiga installation.

I used ext2 as the filesystem because it's not journalled, and I wanted to avoid excessive disk activity. However, you're not limited to using ext2 - Linux gives you plenty of choices.

[color=800000]Listing 11: Format and mount /dev/hda2[/color]
Code: [Select]
   > mke2fs /dev/hda2
    > mkdir /mnt/hda2
    > mount /dev/hda2 /mnt/hda2

12. Modify fstab

/target/etc/fstab needs to be modified... In this guide, we'll be booting into /dev/hda2, so fstab must reflect this.

[color=800000]Listing 12: Modify fstab[/color]
Code: [Select]
   > nano /target/etc/fstab

        # (fs)        (mountpoint)    (type)        (opts)

        /dev/hda2     /               ext2          noatime
        proc          /proc           proc          defaults
        shm           /dev/shm        tmpfs         nodev,nosuid,noexec
        tmp           /tmp            tmpfs         noatime,defaults

13. Copy /target to the new partition (or drive)

Now that it's all set up, time to copy the contents of /target to the new partition or hard drive.

[color=800000]Listing 13: Copy /target to new partition[/color]
Code: [Select]
   > cp -a /target/* /mnt/hda2[/color]

14. Modify grub.conf

If the installation is on another partition, there's no need to re-install grub; you only need to modify grub.conf. However, if you're using a second hard drive, grub will need to be installed (not covered here).

[color=800000]Listing 14: Modify grub.conf[/color]
Code: [Select]
   > nano /boot/grub/grub.conf

        default 0
        timeout 5

        title=Gentoo Linux
        root (hd0,0)
        kernel /boot/kernel-2.6 root=/dev/hda1

        root (hd0,1)
        kernel /boot/kernel-2.6 root=/dev/hda2

15. Finished!

Reboot the computer, select the new 'Amiga' option in grub, and hopefully after a few seconds you'll see the login prompt...

(Just remember, the /Amiga directory is empty - you'll need to fill it with a Kickstart ROM, and a proper Amiga OS installation!)

To start E-UAE, type 'e-uae' at the command prompt.

Note that BusyBox doesn't have a 'halt' command; when you finish your session you need to use 'poweroff'.


If E-UAE on the framebuffer just isn't working for you, you could always install xorg-x11 - the full X windows environment. This'll take up about 60MB (and a few more hours of compilation). Then you need to configure it... ;-)

Compile the kernel without modules (for simplicity, it's usually better to build everything into the kernel)

An alternative to emerging all the packages into one /target directory is to emerge each package into its own individual directory. First create each directory, then use 'ROOT= emerge -O '. Lastly, manually copy the files into the correct locations. Why? You'll see exactly which files are installed where. Some of them may not be strictly necessary. For instance, it seems that not everything in the glibc package is needed, only the items in /lib. If this is the case, it's possible to save space. My final E-UAE Linux installation is ~16MB!

In case it's useful, here's the directory structure of my own installation:

Code: [Select]


BTW, I made myself the root user. This is strongly NOT recommended for all sorts of reasons, but it's my computer and I don't care. I edited /etc/passwd, changed my user id to 0 (root) and got rid of root, then deleted /root. More information at: www-128.ibm.com/developerworks/library/l-roadmap4/

I also mentioned in Step 11 that my preference was to avoid excessive disk activity. Accordingly, I turned off system logging by commenting out some lines in /etc/inittab

Still to do (if there's any interest): a nice Amiga-themed startup logo to go with the login prompt, using either /etc/issue, Linux_Logo (text based 'ASCII art' login) or Qingy (framebuffer based graphical login); perhaps instructions on how to start E-UAE automatically on log-in, and shut down when logging out...

I think it may be possible to automate the whole process, from beginning to end, and make it more of a standard 'installation' procedure - select a few options, then go off while the computer does all the boring stuff...

Comments? Mistakes? Abstruseness? My amiga.org handle is "Fraccy".

(c) 2007  Amir Ansari (Fractallyte)

Offline guru-666

  • Hero Member
  • *****
  • Join Date: Dec 2006
  • Posts: 587
    • Show only replies by guru-666
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #1 on: February 25, 2007, 05:57:34 PM »
COOL!!  Thanks

Offline InTheSand

  • Hero Member
  • *****
  • Join Date: Nov 2004
  • Posts: 1766
    • Show only replies by InTheSand
    • http://www.ali.geek.nz
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #2 on: February 27, 2007, 06:49:05 AM »
Looks good, and a nice viable alternative to the KXLite provided with Amiga Forever...

Might have to give this a go when I have a spare couple of hours or so!

 - Ali

Offline motorollin

  • Hero Member
  • *****
  • Join Date: Nov 2005
  • Posts: 8669
    • Show only replies by motorollin
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #3 on: February 27, 2007, 08:52:48 AM »
Would this run from a read-only filesystem (i.e. a CD)?

Code: [Select]
20  FOR C = 1 TO 2
50  NEXT C
80  GOTO 10

Offline benJamin

  • Full Member
  • ***
  • Join Date: Mar 2003
  • Posts: 226
    • Show only replies by benJamin
    • http://cms.jaminjay.com/
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #4 on: February 27, 2007, 01:03:19 PM »
You've been hearing my dreams!

Sounds like a project to sink my teeth into if I get a spare moment now and then.

Thankyou very much!

"I wonder if there is a 'Kill Bill' movie on UTube about Microsoft..."
Amiga.org - The site for MiniMig support and news.

Offline FraccyTopic starter

  • Jr. Member
  • **
  • Join Date: Jan 2006
  • Posts: 64
    • Show only replies by Fraccy
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #5 on: March 01, 2007, 03:19:09 PM »
@ motorollin

It'll work fine on a read-only filesystem.  However, some tweaks will be necessary - /etc/fstab needs to be modified to move /tmp, /var and possibly /home into RAM.  And, of course, all changes will be lost when shutting down.

Would you like me to go into more detail?

Also remember, this is a highly specific setup (which makes it ideal for, say, an Amiga laptop), unlike KXLight which is designed to be portable between computers.  So running from CD is fine if you bear in mind that the CD will only work in one computer (or any other computer with exactly the same hardware configuration).


Offline Ratte

  • Sr. Member
  • ****
  • Join Date: Sep 2006
  • Posts: 380
    • Show only replies by Ratte
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #6 on: March 02, 2007, 02:34:54 PM »
great work ...
I want to support you.

Offline FraccyTopic starter

  • Jr. Member
  • **
  • Join Date: Jan 2006
  • Posts: 64
    • Show only replies by Fraccy
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #7 on: March 02, 2007, 03:39:33 PM »
Minor correction:

The Linux framebuffer actually DOES support 32bit colour!


Offline cayenne

  • Newbie
  • *
  • Join Date: Mar 2007
  • Posts: 1
    • Show only replies by cayenne
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #8 on: March 05, 2007, 07:46:27 PM »
Hello there!

Indeed this is the coolest idea I've heard of in the last months regarding Amiga emulation on Linux but, did anybody try this in a PPC G4 computer? baselayout-lite can't be emerged and bulding e-uae only with framebuffer support (no X11) seems to fail... :-(


Offline FraccyTopic starter

  • Jr. Member
  • **
  • Join Date: Jan 2006
  • Posts: 64
    • Show only replies by Fraccy
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #9 on: March 08, 2007, 09:58:44 AM »
@ cayenne

You can unarchive baselayout-lite and copy it manually; should work without any problems.

As for Mac framebuffer support - I have no idea!  What error do you get from the E-UAE compilation?

I'd like to add some further instructions on setting up X, but I'm working on an installer at the moment...  I think this tutorial is too complicated!


Offline Methanoid

  • Full Member
  • ***
  • Join Date: Jan 2004
  • Posts: 147
    • Show only replies by Methanoid
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #10 on: August 28, 2007, 08:27:36 AM »
Any updates on this Fraccy, especially on the installer or any options to make it more "noob-friendly".

How does the resultant Amiga compare to Amithlon for speed?

Offline FraccyTopic starter

  • Jr. Member
  • **
  • Join Date: Jan 2006
  • Posts: 64
    • Show only replies by Fraccy
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #11 on: August 28, 2007, 09:04:42 AM »
The X-Amiga install CD is nearly ready!

Sadly, the 'How-To' is out of date, and I haven't had time to tidy it up...

Having a minimal Linux does nothing for emulation speed, but it does help a lot with boot-up times and system overhead. In comparison to Amithlon, it's just like any other *UAE - Amithlon will always be a bit faster.


Offline roguebeck

  • Full Member
  • ***
  • Join Date: Oct 2005
  • Posts: 188
    • Show only replies by roguebeck
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #12 on: September 19, 2007, 02:32:10 PM »
Ah ha, I've been tinkering with something like this for quite a while. This will make it so much easier.
A500 - A501, Supradrive 500XP
C64 - TSR Gold Box AD&D games forever!

Always looking for parts, mods and upgrades!

Offline Amiten

  • Full Member
  • ***
  • Join Date: Jul 2011
  • Posts: 135
    • Show only replies by Amiten
    • http://amiftp.honor.es
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #13 on: January 17, 2013, 07:20:21 PM »

anybody knows if this project still alive the web site disapear?¿:evil:

there is any other way more easy to install the X-Amiga??

Amiten TV - Amiga Channel

Offline som99

  • Lifetime Member
  • Hero Member
  • *****
  • Join Date: Sep 2005
  • Posts: 1566
    • Show only replies by som99
    • http://www.som99.se
Re: XAmiga : How to -- A minimal Linux for E-UAE
« Reply #14 on: January 17, 2013, 08:12:24 PM »
Quote from: Amiten;722967

anybody knows if this project still alive the web site disapear?¿:evil:

there is any other way more easy to install the X-Amiga??


You could always install DSL (damn small linux) and then e-UAE if you want a small footprint and a more user friendly way :) I like DSL and one of my low power thin clients run it and the thin client is used as an webserver,  great for low spec devices.
« Last Edit: January 17, 2013, 08:16:47 PM by som99 »