Кому следует читать это руководство

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, boy. If you thought AROS was a Grapefruit-Machine or a Free Money Project, you are entirely in the wrong place.

Как следует читать это руководство

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 whole system works through a AmigaDos shell (or Cli to older users), although we do have a Workbench, you can not navigate disks with it yet. Old Amiga programmers should read "differences with Amiga programming" from chapter 4 to get an overview of the differences.

Операционная система в операционной системе ?

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 is 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 unable to boot from CD. It`s have 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 end 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 can`t be called easy, and must be treated as experimental. It has beed desribed in Installation Doc. Anyway, remeber 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), 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 on Linux is quite easy to setup. All you need is to apt-get the package on Debian/Ubuntu/Knoppix/DSL or use any other package manager for other distributions or download and unpack the archive manually. You can get the archive from the QEMU Website.

QEMU on Windows is almost the same thing. The difference is in networking and some other issues. You can find useful information and packages on QEMU On Windows page . Also there`s nice GUI for QEMU called QEMU Manager, including the QEMU package. There`s also some GUI`s for QEMU for some systems can be found in links.

QEMU must be launched as a console application with some parameters given. We will review some options in other sections, meaning you must append these to your launch string (or a script).

QEMU is fast virtualiser, but it`s speed can be increased by installing the KQEMU kernel module (and appending the -kernel-kqemu option if in Windows). But remember that KQEMU can make guest system unstable.

Also if you considered to try installing AROS to HD, you can create the virtual HDD for QUMU using the qemu-img program (replace <size> with needed size in bytes, M or G for mega- or giga-) with a command like:

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

Applying to VMWare or VPC it`s even easier to setup. All you need is to install some virtual hardware like network and sound card and create an virtual HDD. Everything managed by a simple GUI.

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`s some command line options for aros executable that could be used. You can get this list with ./aros -h option given.

To be appended ...

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 systems use definitely and common principles, as you can already note. First, any menu options 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`re 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. Also you can enable the menu to appear on any place of the screen, where you press left mouse button. To do so ... For example, 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 a Wanderer becomes just another window you can move, resize etc. So, you can see it isn`t like a Windows 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 open? 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`s usually happens in other OS - your app will appear as window on desktop. Also window usually can be open on it`s own screen - it looks like it captures the whole screen. But you can switch the screens with a gadget in top right corner fo the screen (this is also applicable to the windows). So you can switch between Wanderer, Directory Opus and any other apps 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 window usually has controls to manupalte with it. This control buttons are 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 sreens. Windows can have no gadgets at all (look at the Kitty demo - it`s doesn`t even have a borders and yet has well-curved shape) or have a different set of them.

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 it`s meaning remains the same. Translate it as a directory if you`re unsure.

There`s a 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 in replacement and best traditions of MUI (Magic User Interface), widely used on Amiga`s. 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 it`s menu, or to set Zune prefs for other apps you can use it as the CLI command Zune <app filename>.

To be finished...

AROS CLI (Command Line Interface)

ToDO - CLI commands abstract and comparision ...

AROS has it`s 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`s 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 Tab 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. So, there`s a groups of the AROS system applications collected in the separate directories:

• C - the place for all the system commands used in CLI
• Classes - the place for datatypes, gadget`s 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 dir.
• Libs - where the system libraries are located.
• Locale - holds catalog files of various AROS apps 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 apps
• Utilities - the place for some not-so-commonly used but useful apps

Instead of applications, there`s more permanent running programs called tasks.

Another kind of AROS applications is the Commodities. This is 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 uncommodable. 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 is using the datatypes. Datatype is the kind of system library allows the programs to read or/and write to such files without taking care of the implementing such a format in that program.

And if we dig a little deeper there`s some system terms that can be explained. AROS uses handlers to communicate with the filesystems and HIDD`s 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 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 fonts used 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 set 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 a 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 comination, 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 SYS: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 /Extras/Networking/Stacks/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 it`s 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/pcnet.device UNIT=0 IP=10.0.2.2 UP

Setting Up The Sound

Currently there`s not much to sound in AROS. First, at the moment there`s no working drivers 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...