Who should read this guide

This guide will help you getting used with AROS. It is written for everybody who is interested in AROS. Keep in mind that you are actually using software that is BETA and in research. It is currently mostly fun to play with and cool to program for and program in. So I expect that your interest in AROS is explained by one of these reasons. If you came until here because you thought AROS was a Multimedia Internet-Ready Etc. OS, well, you might be right, but it is not finished, so you need to be patient. If you thought AROS was a Grapefruit-Machine or a Free Money Project, you are entirely in the wrong place.

How you should read this guide

This guide is ordered from "simple" to "advanced". You can start reading at any chapter that contains information that is new to you. But maybe even more important, you should stop reading at any chapter that contains information going beyond your interest. In this way you can learn yourself the advanced topics starting from scratch, or you can stop earlier if you think you only want to use AROS, and not program it. People with an Amiga background can skip the introduction, and start at "Developing for the AROS platform" if they never programmed an Amiga before, or go directly to "Developing inside AROS" if they already did. So there is a starting point and a stop point for everyone.

It is important to realize that this guide is meant for AROS, not Amiga. So even if you owned an Amiga for years, you might need to read "Using AROS" too. This is not an embarrassment: you will notice that using AROS is very slightly different from using AmigaOS. This is because our Workbench is not finished. At the moment the system mostly works through a AmigaDos shell - replacement (or Cli to older users), although we do have a Workbench and you can navigate disks and launch the applications with it, but file operations is not yet complete. Old Amiga programmers should read "differences with Amiga programming" to get an overview of the differences.

AROS-hosted: An Operating System in an Operating System?

AROS is originally developed on Linux running on an Intel-based computer. It runs on many more machines and Operating Systems, though. This may sound strange: an OS running on top of an other OS, that's emulation, right?

A nice term for what AROS-hosted does is "API emulation". API is a three-letter acronym for Application Programmer's Interface. In plain English: an API provides (C Language) functions that a programmer can use. The AmigaOS API consists of a load of library calls that an Amiga programmer can use to make an Amiga program. AROS emulates the AmigaOS API: it tries to provide the same library calls as AmigaOS. An Amiga emulator, such as UAE; emulates the Amiga computer: the processor, the connected hardware, everything. This has its advantages, like being able to play binary Amiga games on different hardware, and its disadvantages, like not being able to use the emulator as a "real" OS, on a "real" processor. AROS-hosted runs on the "real" processor. But it isn't a "real" OS, unless you run in such a way that it doesn't require Linux. This is called "native" AROS.

AROS can run natively on the Intel and Amiga computers, but not quite as good as it runs on Linux. AROS library functions are made to run under Linux first, internally using Linux kernel and library calls. This way a programmer has got the opportunity to bother about the implementation of the whole system first, and to bother about the technical details in a later stadium. People are currently working on making the "native" AROS more usable. The results are very impressive and it is perfectly possible to use AROS-native as a real (and only) Operating system on an IBM PC compatible machine.

Of course, AROS is not only an API emulator. It also tries to provide replacements to all the AmigaOS3.1 system software, and you will also find a few demos and games being shipped with AROS, just to show that they work - we might just be at 77% of the whole system, but we already have Quake running!

Using "native" AROS on i386

Native AROS is currently under heavy development. If you want to see cool tricks, try AROS on Linux. But if you're (also) interested in what a great job the programmers have done, you can try "native" too.

The instructions for installing native AROS are varying depending on which platform you use. Because "native" is still in great development, the results from installing native AROS can also vary depending on the age of the code that you use.

On i386 there's a different booting media available. First and most useful binaries set is an AROS LiveCD which you can get in the Downloads section. It can be either a snapshot or a nightly build (first is more stable but outdated, last has latest changes made but can be unstable in rare cases). Second is the AROS boot floppy, which is intended to boot systems that are unable to boot from CD. It has a minimal set of features but thus have small size also. If you have no CD drive it still can show some part of an AROS to you.

So, after you download the AROS LiveCD archive unpack it and write ISO image to the CD-R(W). If you intent to use AROS in virtual machine, you can use ISO as-is. Once the disc is ready, you can reboot your PC with the LiveCD. If your system does not support booting from CD, also download and write an AROS boot floppy to disk (with Rawrite or Winimage program, for example) and boot from it, leaving CD in drive. After the CD is booted you will find yourself in AROS (it is looks stunningly close to AmigaOS). You can fool around LiveCD with the Wanderer (or with Shell), play some games/demos included in contributed programs on the CD, look at system basics until you get bored. Also it's possible to add files to ISO image and get some extra software written for AROS, and rewrite the LiveCD. For now here ends simple part of using an AROS-native. To test all other features it's required to install the system to the hard disk (real or virtual). This process must be still treated as experimental. It has been described in Installation Doc. Anyway, remember that work continues and soon you can get more from native AROS - keep in touch!

Using "native" AROS i386 in Virtual Machines

Currently the Virtualization technologies is developed to a almost complete real machine replacement, have been burned-on by the increasing CPU speeds. You can make a "virtual" machine inside of your system ("host") and launch AROS on it, without being worried about any failures and relaunching the "guest" system quickly if something has happened.

There's a number of free virtual machine packages, most knowingly is QEMU (Free, Open Source, for many host systems), VMWare Player (Free. There's also a full VMWare server for free that require a free serial) and Microsoft VPC (Free). You can get a version for your "host" system that suits your needs. We will describe some tips on launching AROS for different VM's.

Instead of having almost the same AROS setup inside the VM's, there's a difference in setting the VM itself.

qemu-img create -f qcow aros.img <size>

Using the AfA on m68k

On an Amiga (m68k), you can place the native code somewhere on your harddisk, double-click the "boot" icon, do a reset and enjoy a complete Amiga system. This is because it is not really native. The boot program just temporarily replaces a few AmigaOS libraries with AROS libraries. For testing purposes this is of course good, but in the end you still run good ol' AmigaOS and not plain native AROS. This will change as we build a more complete 68k AROS system. This system is often called AfA (AROS for Amigas).

Using AROS hosted on Linux or FreeBSD

Once you got the binaries for your system, either by compiling or by downloading pre-compiled binaries, you should go down into the "bin/$TARGET/AROS" directory, where $TARGET is your system target (something like "linux-i386"). Run the file "aros" ("./aros"). The Workbench replacement "Wanderer" will be started.

There are some command line options for aros executable that could be used. You can get this list with ./aros -h option given:

AROS for Linux
usage: ./aros [options]
 -h                 show this page
 -m <size>          allocate <size> Megabytes of memory for AROS
 -M                 allows programs to read SysBase from Address $4; SysBase is
                    found there in big endian format
 -t <value>         timer ticks per second. Must be Multiple of 50; max value
                    working on 2.4 kernels is 100; on 2.6 kernels it is 1000;
                    default is 100.
 --help             same as '-h'
 --memsize <size>   same as '-m <size>'
 --mapsysbase       same as '-M'
 --tickrate <value> same as '-t <value>'
 --hostmem          Let AROS use the host operating system's facilities to
                    manage memory, rather than the AROS' builtin ones.

You may have to add some more memory for hosted AROS with -m option to made some programs working properly.

Because "Wanderer" is very limited you'll prefer to work with the Shell. You can start it from the menu "Wanderer/Shell". Now you should type in commands, and the most important command is "dir": it will show you a directory's contents. The directory named "C" contains all the commands, so it might be useful to display its contents with "dir c:". The shell behaves like an AmigaDOS shell, and the commands in "C" behave like their AmigaDOS equivalents. (Note to UNIX folks: to address the parent directory, use "/" and not "..": this will look ugly because AROS thinks that Linux's ".." is a normal directory. You shouldn't use "./" as a prefix to address a command within the current directory either, but leave this away instead.) Once you are used to it, try to execute a few programs (especially the "Demos" and "Games") to get an impression of AROS capabilities.

Using AROS-hosted on PPC

To be filled by someone...

AROS Zune GUI Basics

GUI abbreviation stands for Graphical User Interface, and is applied to all the means used by OS to interact with user other than plain command-line interface (CLI). For those who never have used any OS from Amiga branch, it will be useful to give some GUI basics to help them in use of our system. Some of it, however, will be AROS-specific.

An Amiga system uses definite and common principles, as you can already note. First, the menu bar of any application's window isn't attached to that window - it moved to upper strip, where it can be easily acessed. To do this, select window you need, and move mouse pointer to upper side of a screen. Then, if you press right mouse button there, you can see the pull-down menu, representing our application's options. Yes, it looks like MacOS somehow. If no application window is selected, you can see the Wanderer's menu then.

Now, let's consider our desktop - as you probably already know, it's called Wanderer. What is this ? Well, Wanderer is an application, just like all others. In fact, it is an AROS file manager, allowing you to choose and operate files (the functionality isn't complete yet), launch programs, get some system information, launch CLI (shell window) and other functions. Usually it opens on wide screen and acts like your desktop (icons on this desktiop represents the volumes and disks you can work with). It can be set aside by unselecting Backdrop option, which can be found in Wanderer's menu (remember paragraph above?). After that Wanderer becomes just another window you can move, resize etc. So, you can see it isn't like a Window or another system's desktop, fixed to it's place. Of course, you can even not use the Wanderer at all and use your preferred file manager (e.g. Directory Opus).

But how do the applications behave then, where will the windows be opened? There's a "screen" term - screen is the place where your window is meant to be open. If it's said that application going to open on Wanderer screen, it will look like it usually happens in other OS - your application will appear as window on desktop. On another hand, the window can be open on its own screen - it looks like it captures the whole screen. But you can switch the screens with a gadget in top right corner of the screen (this is also applicable to the simple windows). So you can switch between Wanderer, Directory Opus and any other applications opening on it's own screen. This behaviour also comes from Amiga's history.

Well, the time has come to say something about windows itself. AROS windows usually have control buttons to manipulate them, called gadgets (which can be translated as interactive kind of graphical element). First one in the top left corner of a window allows to close it. Next, in the right part allows to minimise/maximise window. And the last used to put window to front or to back just like we switch screens. Windows can have no gadgets at all (look at the Kitty demo - it doesn't even have a borders and yet has well-curved shape) or have a different set of it.

The window's contents consists from some usual elements could be seen in any GUI - buttons, lists, strings of text, any other kind of gadgets. If application is intended to change any preferences of a system or an application it's usual shortly called Pref and has a set of buttons to operate. Usually this buttons are: TEST (applies all the changes made by Pref but doesn't save and do not the changes but close the window), SAVE (saves the changes and close the window), USE (applies the changes and close the window, but do not saves them), CANCEL (discard all the changes and close the window).

Also, from Amiga's history the file placement unit is often called a drawer instead of a folder/directory in other systems, but its meaning remains the same. Translate it as a directory if you're unsure.

There are special keys in AROS, just like on original Amiga, used to make quick commands with it. Left and Right WinKey (on PC keyboard) replaces the original Amiga keys and is used in different combinations to launch commands.

Another unknown name you can encounter in AROS is Zune. What's that? Zune is GUI toolkit developed as replacement for MUI (Magic User Interface), widely used on Amigas. But is there an application called Zune? You can find Zune Pref and it allows you to set settings for Zune-based applications altogether or in particular. For example, to set Zune prefs for Wanderer you can select GUI prefs from its menu, or to set Zune prefs for other applications you can use it as the CLI command Zune <app filename>.

To be finished...

AROS CLI (Command Line Interface)

ToDO - CLI commands abstract and comparison ...

AROS has its CLI, the Command Line Interface, greatly expanding the capabilities of OS. Those who had used the AmigaOS can note that it looks pretty close to the AmigaDOS. There are some CLI basics described in introduction to CLI commands.

Currently you don't need to type all the commands to the end - now there's a neat tabulator completion similar to that on Linux consoles. This allows you also to append the filenames or choose them from the list.

To be finished...

AROS System programs

We have mentioned the applications, it's good to give a description of their functions. AROS system applications are collected in separate directories:

• C - the place for all the system commands used in CLI
• Classes - the place for datatypes, gadgets images and Zune classes
• Devs - where the device-related files (drivers, keymaps) and datatypes are placed
• Extras - where all the contributed programs reside
• Fonts - here you can find all of the system fonts. Any additional fonts must be appended (assigned) to this directory.
• Libs - where the system libraries are located.
• Locale - holds catalog files of various AROS applications translations
• Prefs - has a number of preferences-editing programs
• S - contains some system launch-time scripts
• System - the place for some system controls
• Tools - the place for some commonly used system applications
• Utilities - the place for some not-so-commonly used but yet useful applications

Another kind of AROS applications are the Commodities. This are applications which can help you make your system more comfortable. For example, AROS windows doesn't set to the top of others when you click on it, and you can find it uncomfortable. You can use the AROS commodity ClickToFront to fix it. It can be found beneath other commodities in SYS:Tools/Commodities directory. When you double-click on it, window will become to the top of others if double-clicked. Another example is Opaque commodity - it allows you to move windows with their contents. There's also an Exchange commodity which allows you to manipulate launched commodities and get information about them. Usually commodities do not open any windows.

To operate with files of different types Amiga-like systems are using datatypes. Datatype is the kind of system library which allows the programs to read or/and write to such files without taking care of the implementing of such formats.

And if we dig a little deeper there are some system term which have to be explained. AROS uses handlers to communicate with the filesystems and HIDDs to communicate with the hardware.

To be finished...

Setting up the Locale

AROS is becoming a really international system this days, being translated to many languages. Translating isn't very difficult, and the number of the AROS translators is still increasing. If unicode support will be implemented it can be translated in every language people use. If you feel you can give AROS to your country, both OS and documentation, do not hesitate to contact us and offer your help.

So about the language. First, depending on available fonts you must set fonts by launching SYS:Prefs/Fonts and designating Fonts to different system text: Icons (used for icons labels), Screen (used on common screen) and System (used in CLI window). If your language uses different codeset than ISO (for example, cyrillyc CP-1251) there's must be the fonts in correct codepage. AROS currently can use two kinds of fonts - the Amiga bitmap fonts (which can be used directly) and TrueType (via FreeType 2 manager, which still has some issues with non-ISO codepages). Bitmap fonts are in any particular codepage, and TTF can be unicode.

How can you change the AROS locale? To do this you need to launch the Locale pref in SYS:Prefs. You can see a list of supported locales there and select your preferred ones. On the second page of this Pref you can select the country used (it gives correct currency and date/time format). And the last tab allows you to change timezone to that used in your location.

After you've made changes to fonts, reboot the system, and you must be able to see all the translated content.

So now we can read, but can we write also in our language? To do this, you must change the keyboard layout.

Keyboard and mouse settings are managed by the Input pref. You can change the layout and click Use but we can do even better. This tool allows you also to save presets - just like any application it's got a menu, allows you to save your preferences to the file with the given name and keep different settings of locales. We will use it later to switch our keyboard layouts. Choose your locale's keyboard layout from the list and make a left click to open the context menu. Then enter the name of your preset to File string, say, locale1 and click Ok to save it to SYS:Prefs/Presets directory. Now choose an American (PC) layout and repeat the saving presets, say, with name english. This presets can be used later to switch the layouts. Click Cancel to exit.

There's an FKey commodity which allows you to make actions assigned to some combinations of keys. Now let's launch it and assign the locale switching. After you double-click on FKey icon, launch the Exchange, choose the FKey from list and click the Show button. This will invoke the FKey window. You can see the ALT TAB in list assigned to window switching. Now enter the first key combination, say, ALT Z and go to the right panel. Choose Launch the program from pulldown menu and enter SYS:Prefs/Input as an argument. Append the USE switch and english preset name to the string as shown:

SYS:Prefs/Input USE SYS:Prefs/Presets/english

Click on the New Button to add the another combination. Now set the combination for your locale as shown above, replacing english name with your preset name. Click New button again and then Save Settings. Now you can use defined combinations to switch the layouts.

Installing the software

Actually there's no installer system in AROS. Installing an application usually means you have to extract it to some directory on a harddrive or ramdisk. Then some programs require you to make assignments which is done in CLI with the Assign command and some start script additions. For example, Lunapaint needs the Lunapaint: to be assigned to the directory it was extracted to to work properly. You can do this with the command

Assign Lunapaint: Disk:Path/Lunapaint

But if you don't want to type this command after reboot to launch it again, you must put it to S:User-Startup script. To do this, type this command in CLI prompt:

:> edit S:User-Startup

Then insert the Lunapaint (or other program) assign at the end of file. Save the changes and you'll have that fixed. Such a procedure can be used for any program that needs it.

Another way is using the ENVARC:SYS/Packages directory. All you need here is create a text file with the name of your application and put a path to application in that file. Then create a directory named S in the program's directory and put the package-startup file there. This way is more safer, but can be not so Amiga-styled to you.

Setting up the Network

To communicate with other computers on network, AROS uses a TCP Stack, AROSTCP, which is a port of AmiTCP. This software is located in SYS:System/Network/AROSTCP directory. Setting up is not easy but some kind of GUI tool is in development. Also please note that actually there's a very little amount of networking program on AROS yet (but some interesting tools is in development to be soon released).

First you need is to setup your machine side of network. This part can differ depending on your hardware. On a real machine you need to install the supported network interface card (NIC) and plug the cable to it. On a virtual machine you must set up its NIC implementation and check if it's supported by AROS (at least, QEMU and VMWare ones is supported).

#> modprobe tun

#> echo 1 > /proc/sys/net/ipv4/ip_forward

#> iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

#> qemu -cdrom aros.iso -m 48

eth0 DEV=DEVS:networks/prm-rtl8029.device UNIT=0 NOTRACKING IP=172.20.0.10 UP

HOST 172.20.0.10 arosbox.lan arosbox
HOST 172.20.0.1 gateway
DOMAIN lan
NAMESERVER 192.168.0.1

ENV:AROSTCP/db

; $VER: AROSTCP-PackageStartup 1.0 (01/08/06)
; AROSTCP-PackageStartup (c) The AROS Dev Team.
;
Path "C" "S" ADD QUIET

If not exists T:Syslog
    makedir T:Syslog
Endif

If not exists EMU:
    if $AROSTCP/AutoRun eq "True"
    C:execute S/startnet
    EndIf
EndIf

; $VER: AROSTCP-startnet 1.0 (01/08/06)
; AROSTCP-startnet (c) The AROS Dev Team.
;
Run <NIL: >NIL: AROSTCP
WaitForPort AROSTCP
If NOT Warn
    run >NIL: route add default gateway
Else
; echo "Wait for Stack Failed"
EndIf

ifconfig -a

lo0: flags=8<LOOPBACK> mtu 1536
        inet 0.0.0.0 netmask 0x0
eth0: flags=863<UP,BROADCAST,NOTRAILERS,RUNNING,SIMPLEX> mtu 1500
        address: 52:54:00:12:34:56
        inet 172.20.0.10 netmask 0xff000000 broadcast 172.255.255.255

AROS:>ping 172.20.0.1
PING 172.20.0.1 (172.20.0.1): 56 data bytes
64 bytes from 172.20.0.1: icmp_seq=0 ttl=255 time=xx ms
64 bytes from 172.20.0.1: icmp_seq=1 ttl=255 time=xx ms
64 bytes from 172.20.0.1: icmp_seq=2 ttl=255 time=xx ms

--- 172.20.0.1 ping statistics ---
3 packets transmitted, 3 packets received, 0% packets loss
round trip min/avg/max = x/xx/xx ms

eth0 DEV=DEVS:networks/pcnet32.device UNIT=0 IP=10.0.2.2 UP

Setting Up The Sound

Currently there's not much support for sound in AROS. First, at the moment there's no working driver for virtual machine's implemented sound cards (usually sb16/es) so the only way to try to get sound is use AROS-native on pc with a real SB Live/Audigy card. Also the AC97-compliant codecs are supported.

AHI sound in AROS supports also no sound (VOID) and disk writing options.

To be written by someone...