.pn 51
.if \nh=0 .so macros
.LP
.CP 4 "\*(M0 ON THE COMMODORE AMIGA"
.PP
This chapter tells you how to install and run
.MX 
on a Commodore Amiga.
Four sections are present in this chapter.
The first section discusses the kind of hardware you need to run
.MX .
The second section gives an overview of how to get
.MX
running.
The third one goes into more details.
The fourth one is about troubleshooting.
If during the installation you have problems, please check the
troubleshooting section.
You may have run into a common problem whose solution is well known
and described there.
When you have finished reading this chapter and have successfully installed
.MX ,
please skip to Chap. 7 to learn about using your newly installed
.MX
system.
.SP 0.9
.SE "MINIX HARDWARE REQUIREMENTS"
.SP 0.9
.PP
.MX
should run on any Amiga 500 or Amiga 2000 that has at least 1M of memory.
The most common peripherals are supported, except for the hard disk.
Extra memory or a second drive makes programming much more pleasant.
While it is possible to boot
.MX
with a 512K 1 drive system, it is difficult to do anything serious,
certainly not recompiling the operating system.
To do that, you really should buy an additional 512K.
.SE "HOW TO START \*(M0"
.PP
Throughout the discussion below, lines printed in the
\s-2\f5Helvetica typeface\fR\s0
are either commands you should type on the keyboard, or are lines that
the computer will display for you.
.PP
A word of caution is in order about the diskettes.
Although the first one (called: \*(OQBOOT\*(CQ) is a standard AmigaDOS
diskette and can be copied (for backup) the same way as other AmigaDOS 
diskettes are copied, the other ones use the industry standard 720K format 
for the layout of the sectors, but the file systems on them are in
.MX
format, rather than in \s-2MS-DOS\s0 format.
Unless you have a program that can copy 720K diskettes sector by sector,
without looking at the contents, it is suggested that you do not attempt
to backup the diskettes until you have 
.MX 
running (see Sec. \na.3.4).
.MX
does not have a format utility, but you can format diskettes using 
the AmigaDOS format utility that can be found in the C directory of the boot 
disk and can be invoked by typing:
.HS
.Cx "BOOT:C/transfer  \(enf"
.HS
under AmigaDOS.
.PP
To boot 
.MX ,
proceed as follows.
.LI
.IT
Turn on the Amiga, and insert the boot diskette (BOOT)
in any drive. If the Amiga was already powered on, you may also press
both Amiga keys while holding down the control key to reset the Amiga.
.IT
Because the AmigaDOS diskette does not contain any of the usual utilities
such as
\fIsetmap, rename\fR, etc., you have to copy them from your original
Workbench disk onto the AmigaDOS disk yourself. 
When you boot
.MX
for the very first time, a little program will show you exactly how to do
so. When you have successfully copied the required utilities onto the AmigaDOS
disk you should re-boot the Amiga. From now on the Amiga will automatically
load
.MX
whenever your boot from the BOOT disk.
.IT
About 15 seconds later,
.MX
will ask you to either specify a root device or press return. Insert
the root disk (ROOT) and press return. The RAM-disk will now be
loaded into memory.
.IT
Another 10 seconds later
.MX
will display a line telling how much
memory the machine has, how large the operating system (including all its
tables and buffers) is, how large the RAM disk is, and how much memory is
available for user programs (the first number minus the next two).
Check to see that the available memory is at least positive.
.MX
will not run with negative memory.
To do anything useful, however, at least 200K of available memory is needed.
.IT
When the RAM disk has been loaded, the system initialization file,
.DI /etc/rc ,
is executed.
It asks you to remove the root file system and then insert the
.DI /usr
file system (\*(OQUSR\*(CQ) in drive 0 and type a carriage return.
Do so.
.IT
After 
.I /usr 
has been mounted,
you will next be requested to enter the date (and time).
Enter a 12-digit number in the form MMDDYYhhmmss, followed by a carriage
return.
For example, 3:35 p.m.
on July 4, 1976 was 070476153500.
.IT
You will now get the message:
.HS
.Cx "login:"
.HS
on the screen.
Type:
.HS
.Cx "ast"
.HS
and wait for the system to ask for your password.
Then type:
.HS
.Cx "Wachtwoord"
.HS
being careful to type the first letter in upper case.
Lower and upper case letters are always distinct in
.MX .
Do not use an upper case letter when a lower case one is called for or
vice versa.
Like 
.Ux ,
.MX
regards \*(OQa\*(CQ and \*(OQA\*(CQ as two distinct characters.
Please do not type \*(OQa\*(CQ when you mean \*(OQA\*(CQ.  It matters.
.IT
If you have successfully logged in, the shell will display a prompt 
(dollar sign) on the screen.
Try typing:
.HS
.Cx "ls  \(enl  /bin"
.HS
to see what is in the
.DI /bin
directory on the root device.
After that, try:
.HS
.Cx "ls  \(enl  /usr/bin"
.HS
to see what is on the drive 0 diskette.
To stop the display from scrolling out of view, type CTRL-S; to restart it,
type CTRL-Q.
(Note that CTRL-S means depress the \*(OQcontrol\*(CQ key on the keyboard
and then hit the S
key while \*(OQcontrol\*(CQ is still depressed.)
.IT
If you have more than one diskette drive, you can mount 
one of the other diskettes by inserting it into drive 1 and typing:
.HS
.Cx "/etc/mount  /dev/dd1  /user"
.HS
If you want to use drive 2 or 3, replace \fI/dev/dd1\fR by \fI/dev/dd2\fR or
\fI/dev/dd3\fR respectively. Use
.I ls
to inspect it.
You can now try out other commands.
.IT
When you are finished and want to log out, type: CTRL-D.
The
.HS
.Cx "login:"
.HS
message will appear, and you or another user can log in again.
.IT
When you want to shut the computer down, make sure all processes have
finished, if need be, by killing them with
.I kill .
Then type:
.HS
.Cx "sync"
.HS
or just log out.
When the disk light goes out, you can turn the computer power off.
.I Never ,
ever turn the system off without first running
.I sync
or logging out (which does an implied
.I sync ).
Failure to obey this rule might result in a garbled file system
and lost data.
If you forget and just turn off the computer, next time you boot, be sure
to run
.I fsck
to repair the file system.
.LX
.SP -1
.SE "A MORE DETAILED LOOK"
.PP
In this chapter we will describe some of the details of
.MX .
Note: some programming examples will be presented in the rest of this chapter.
You can recognize them by the prompts: The \s-2\f51>\fR\s+2 prompt indicates
that you should type the command in an AmigaDOS CLI window, the
\s-2\f5$\fR\s+2 indicates a normal
.MX
commando and the \s-2\f5#\fR\s+2 indicates commands that should be run by the
superuser (logged in as \fIroot\fR).
You \fImust not\fR type the prompts themselves, just type 
the commands following them.
.PP
The
.MX
distribution consists of one disk in the normal 880K AmigaDOS
format (which contains some tools and a binary of the operating system and
is used for booting
.MX ) 
plus a number of double-sided 720K
.MX
disks.  We will refer to these diskettes in the rest of this manual by
their name in the first column of the following table.
Here is the list of diskettes:
.HS
.TS
center,box;
c c c c
l l l l.
\fBName	Size	File system	Description\fR
_
01 BOOT	880K	AmigaDOS	Used for booting \*(M2
02 ROOT	720K	\*(M2	300K Root file system copied to RAM disk
03 USR1	720K	\*(M2	System Binaries 1 (/usr)
04 USR2	720K	\*(M2	System Binaries 2
05 USR3	720K	\*(M2	System Binaries 3
06 ACK	720K	\*(M2	C compiler
07 SRC1	720K	\*(M2	Operating System Sources
08 SRC2	720K	\*(M2	Commands Sources 1
09 SRC3	720K	\*(M2	Commands Sources 2
.TE
.HS
.PP
If you have not already made backups, now is the time to do so.
You can use the normal AmigaDOS procedure to copy BOOT, as is described
in the AmigaDOS manuals,
or you can use any of the available disk copiers.
To copy the
.MX
disks you will have to use
.MX
itself. Be sure you have 8 formatted (see section 4.2) disks ready, to
copy the original onto. Be sure to follow
.I diskcopy's 
instructions and repeat this 7 more times.
You can also use other means, e.g.,
.I dos2dos's 
format command or a real
PC or Atari-ST to format the disks.
We will refer to the copies as BOOT, ROOT, USR, ACK and SRC.
Keep the original disks write protected under all circumstances to prevent
accidental loss of the original source.
.SP 0.5
.SS "Keyboards"
.SP 0.5
.PP
The Amiga comes with different keyboards in different countries.
.MX
solves this in the normal Amiga-way: keymaps.
This section describes how to set up your keyboard for
.MX .
.PP
If you have one of the European keyboards,
you must first install a keymap for your particular version of the keyboard
(unless you are willing to live with the US key bindings, meaning that the
character engraved on the keytop will not always correctly describe which
key it is).
Life would have been a lot simpler if typewriter manufacturers had
devised an international standard keyboard 100 years ago.
.PP
There are several methods for installing a keymap, increasing in complexity.
If the one you use fails, please try one of the other methods.
For all of the methods, we assume that you are a bit familiar with the CLI.
If you are not, please read that part of the manual that came with your Amiga.
Start up your Amiga and boot from your favorite Workbench disk.
Now put BOOT: in a drive.
.SP 0.5
.UU "Using One of the Prefab Keymap Files."
.SP 0.5
.PP
Find out which one you normally use by typing:
.HS
.Cx "1>	type  S:startup-sequence"
.HS
You should see a line like:
.HS
.Cx "setmap  nl"
.HS
which means you normally use the Dutch (nl) map:
.HS
.Cx "1>	 cd  BOOT:
.br
.Cx "1>	 dir  devs/keymaps
.HS
You will see several files, all starting with \fIm_\fR, such as \fIm_usa0\fR.
These are keymap files. You should specify your keymap by
editing \fIBOOT:S/startup-sequence\fR.
To specify the \fInl\fR
keymap, change \fIBOOT:c/setmap m_usa1\fR
to
\fIBOOT:c/setmap m_nl\f1.
.PP
If you cannot find your favorite map among the \fIm_*\fR files, or it fails
for some other reason proceed with step 2.
.UU "Converting Your Keymap."
.PP
Patch a keymap using one of the keymap editors available.
We'll assume that you are using \fIKeyMapEd\fR because it is
public domain and quite good.
If you have another keymap editor it will probably do just fine.
.PP
The only changes necessary are: help, up, left, right, down to \ex00,
del to \ex7f,
f1 to \ex1bOP, f2 to \ex1bOQ, f3 to \ex1bOR, f4 to \ex1bOS, f5 to \ex1bOT,
f1 to \ex1bOU, f7 to \ex1bOV, f8 to \ex1bOW, f9 to \ex1bOX, f10 to \ex1bOY.
.PP
You might change the (shifted) function key definitions: these are the only ones
where it makes sense to select \*(OQstring.\*(CQ If you do so you can map any of
them to an arbitrary string. Do not to exceed an average length of
20 characters per key because in the kernel there are only 400 bytes
to store their definitions.
When redefining the keys, do not change the definitions of the (unshifted)
function keys, since they are used by the \fImined\fR editor.
.UU "Give up"
.PP
If you think that this is all quite complicated or you are not so sure
about really doing any of it, you can skip it for now and find out how the
default map (\fIm_usa1\fR) works for you.
If worst comes to worst, experimentally determine what all the keys do, and
paste paper stickers on the key tops giving their new functions.
.SS "The Preferences"
.PP
When
.MX
boots it copies all sorts of information from AmigaDOS such
as the mouse pointer, which will be used as a cursor under
.MX, 
border and character colors, the keymap, the memory map, etc.
To change the default settings you can
boot from the BOOT disk, hit CTRL-D before
.MX
has actually booted and then run \fIpreferences\fR from your Workbench.
.SS "Exchanging Files between AmigaDOS and \*(M0"
.PP
Just as in the other versions of
.MX
you can exchange files between AmigaDOS and
.MX .
One problem, however, is that AmigaDOS
uses a nonstandard diskette format; not just a different file system, but
also a different encoding scheme for the data. 
To overcome this problem,
we have provided a \fItransfer\fR utility to read, write and format
.MX
diskettes under AmigaDOS. For more information on \fItransfer\fR consult
the manual pages in Chap. 9.
.PP
The 720K diskettes used by 
.MX
on the Amiga conform to the industry standard for 3.5 inch diskettes, and
can be read on the Atari ST using
.MX
there.
Thus you can make 
.MX
file systems on your Amiga and then use them on an Atari ST
and vice versa.
In fact, binary programs compiled on any of these systems can be run on
any of the others without modification.
This makes it easier for you to share software with other
.MX
users.
People who do not believe in standardization are requested to read Sec. \na.3.1
again.
.SS "Making Backups of \*(M0"
.PP
Ok, how about \fIyour first good deed as a
.MX
user?\fR Boot
.MX
login, and type:
.HS
.Cx "#	cd  /"
.br
.Cx "#	diskcopy"
.HS
.I "diskcopy"
asks you to insert the source disk, insert ROOT, the first of the
disks, do so and hit return.
After a while
.I "diskcopy"
will ask you for the (formatted) destination disk, insert one of
the disks you've just formatted.
repeat this process for the others and then store the original
disks together with the original BOOT in a safe place.
You will not need them again unless you accidentally damage one of the new
copies.
.I Diskcopy
unmounts the
.I /usr
disk so you'll have to remount it when it is done.
First insert the the USR diskette, then type:
.HS
.Cx "#	/etc/mount  /dev/dd0  /usr"
.HS
You can check if
.MX
is working 100% as follows.  Type:
.HS
.Cx "#	cd  /usr/test"
.br
.Cx "#	run"
.HS
These elaborate tests take over 15 minutes.
If no error messages appear, the system is working properly.
Be sure the diskette is write enabled.
.PP
You can now edit files, compile programs, or do many other things.
The reference manuals given in Chap 9. and the extended ones in Chap 10.
tell you about the programs available and what they do.
The descriptions are for reference purposes, however.
They are not tutorials.
If you are unfamiliar with \s-2UNIX\s0, it is suggested that you first
read one of the many books available on this subject.
Any good computer bookstore will have a wide selection of them.
.HS
.SS "Boot Procedure Options"
.PP
While the default boot sequence will probably be just fine most of the time,
you can change the behavior of the
.MX
kernel with some useful options. The
.MX
kernel, fs, mm and init, packed together in
.I BOOT:minix.img ,
contain the
.MX
code. 
This data file is read in by a little utility program called
.I minix .
This is an ordinary AmigaDOS program, it finds out some things about your Amiga
(how much RAM you have, what keymap you use, if you have a
NTSC 60Hz or PAL 50Hz machine etc.), then it loads
.I minix.img ,
passes the information to it and starts it off.
For the exact usage of \fIminix\fR, see the manual pages.
.HS
.SS "Even More Details"
.PP
If you want to know more about the exact differences between the Amiga
and the IBM versions of
.MX ,
you might also read the Atari specific chapter, since the Amiga version
was derived from the Atari version, which was derived from the IBM version. 
The IBM version was not derived from anything.
Details about exactly what devices
are available, how the tty driver works, etc. can be found there.
.SE "TROUBLESHOOTING"
.PP
Sometimes things can go wrong.
If you are having trouble getting started, you should try to find
a friend's machine and try
.MX 
there.
If it works, then the problem is clearly due to incompatible hardware.
To verify that this is indeed the problem, remove (or at least disconnect)
all optional equipment from your Amiga and try again.
If this works, insert the optional equipment one device at a time,
rebooting
.MX
after each one is installed until the guilty party is located.
.PP
If problems arise after you have gained enough experience to recompile
the kernel, you might compile (parts of) the kernel with the \fB\(enDDEBUG\fR
flag as to allow extra debugging output to appear when
.MX
is running. This option is not very useful for inexperienced users, however.