%
% GNO Overview
%
% $Id: intro.tex,v 1.8 1998/10/31 20:23:29 gdr-ftp Exp $
% 

\documentclass{report}
\usepackage{html}
\usepackage{hthtml}
\usepackage{makeidx}
\makeindex
\bodytext{bgcolor=#ffffff}

\begin{document}

\title{GNO Overview and Installation}
\author{Jawaid Bazyar \\ Tim Meekins \\ Devin Reade}
\date{13 October 1998}
\maketitle

\bibliographystyle{plain}
\nocite{*}

%
% These are various html links used throughout this document.
%
\newcommand{\faqhtml}[1]{\htlink{#1}
	{http://www.gno.org/~gno/FAQ.html}}
\newcommand{\faqtext}[1]{\htlink{#1}
	{ftp://ftp.gno.org/pub/apple2/gs.specific/gno/doc/faq/CURRENT}}
\newcommand{\gnodocs}[1]{\htlink{#1}
	{http://www.gno.org/~gno}}
\newcommand{\delphi}[1]{\htlink{#1}
	{http://delphi.com}}
\newcommand{\overview}[1]{\htlink{#1}
	{http://www.gno.org/~gno/intro.html}}
\newcommand{\kernel}[1]{\htlink{#1}
	{http://www.gno.org/~gno/kern.html}}
\newcommand{\gsh}[1]{\htlink{#1}
	{http://www.gno.org/~gno/gsh.html}}
\newcommand{\manpages}[1]{\htlink{#1}
	{http://www.gno.org/~gno/manindex.html}}
\parindent=0pt
\parskip=1pc

The GNO Multitasking Environment is Copyright 1991-1998 by
Procyon Enterprises Incorporated.

\begin{flushleft}
First Edition, 1991. \\
Second Edition, August 1996. \\
Third Edition, November 1997.
\end{flushleft}

The ORCA/C run-time libraries are Copyright 1987-1998 Byte Works, Inc.,
and distributed with permission.

This product includes software developed by the University of California,
Berkeley and its contributors.

GNO/ME versions 2.0 and later also include several utilities and
libraries produced by
outside authors and in the public domain. This software is included
solely as a convenience to users of GNO/ME, and is not considered part
of GNO/ME for copyright purposes.

GNO and GNO/ME are trademarks of Procyon Enterprises Incorporated.

Apple IIGS, APW, Finder, GS/OS, ProDOS, Macintosh, and HFS are registered
trademarks of Apple Computer, Inc.

AppleWorks GS is a trademark of Claris Corp.

UNIX is a registered trademark of The Open Group in the USA and other
countries.

\bf
Important Notice:
\rm
This is a fully 
copyrighted work and as such is protected under the copyright
laws of the United States of America.
While GNO is now freely available, GNO remains copyrighted and
is not to be considered in the public domain.

Procyon Enterprises Inc.
MAKES NO
WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED
COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR
ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS
NOT PERMITTED IN SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY
TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS.
THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE
TO STATE.

Procyon Enterprises, Inc. \\
P.O. Box 641 \\
Englewood, CO 80151-0641 USA \\
(303) 781-3273

\chapter{Credits}

\begin{quote}
\em
Always listen to experts. They'll tell you what can't be done, and why.
Then do it.  \bf --- Lazarus Long \rm
\end{quote}

The {\bf GNO} {\bf M}ultitasking {\bf E}nvironment for the Apple IIgs. \\
Copyright 1991-1998, Procyon Enterprises Inc. and Tim Meekins.

The following people and organizations have contributed to the GNO base
distribution; many other people have contributed stand-alone packages and
their efforts are also appreciated:

\begin{description}
% \setlength{\itemindent}{1.5cm}

\item[Kernel]
Jawaid Bazyar;
Derek Taubert.

\item[GNO Shell]
Tim Meekins;
Dave Tribby.

\item[Documentation]
Jawaid Bazyar;
Albert Chin;
Tim Meekins; 
Devin Reade;
Andrew Roughan.

\item[Utilities]
Matt Ackeret;
Leslie Barstow;
Soenke Behrens;
James Brookes;
Evan Day;
Tilghman Lesher;
Devin Reade;
Ian Schmidt;
Derek Taubert;
Greg Thompson;
Dave Tribby;
Philip Vandry.

\item[Libraries]
Jawaid Bazyar;
Soenke Behrens;
James Brookes;
Douglas Gwyn;
Tilghman Lesher;
Devin Reade;
Henry Spencer;
Derek Taubert;
Dave Tribby;
Phillip Vandry;
Mike Westerfield;
Procyon, Inc.;
The Byte Works, Inc.;
University of California, Berkeley.

% \setlength{\itemindent}{0cm}
\end{description}

The libraries contain other contributions that are necessarily anonymous,
as they are derived from code fragments for which no author information
was available.

With many thanks to:
\begin{itemize}
\item
Bill Gulstad, Rob Knauerhase,
and everyone on the gno-devel and GNOBETA Internet mailing lists.
\item 
Dave Lyons, for tolerating Jawaid's endless
questions since the beginning of time, for getting Jawaid
started in IIgs programming, and for calling GNO ``cool''.
\item
Mike Westerfield, for your
technical assistance and all your work in making great
development tools for the IIgs.
\end{itemize}

Special thanks to:
\begin{itemize}
\item
Matt Deatherage, for egging Jawaid on to
complete the project; also, for your most helpful
technical support through DEVSUPPORT --- you guys made this thing possible!
\item
Randy Hyde, for telling Jawaid it couldn't be done.
\end{itemize}

\chapter{Preface}

Computers are tools. The flexibility of a
tool determines how useful it is. Early computers were much like
the one this software was written for: the Apple IIgs. They could
only run one program at a time, and their usefulness was limited
to what the particular program the user was executing offered. In
the late 1960's, a team of researchers at AT\&T began
developing the UNIX operating system. The UNIX design was
partially based on the premise that most programs are I/O bound,
that is, most of the time the program executes is spent waiting
for user input or other I/O operations. While one program is
waiting for I/O, why not allow another program to execute? This
is what they did, and the result was one of the most successful
computer operating systems ever created.

The Apple IIgs, like the Macintosh it is
modelled after, provides very limited multitasking abilities in
the form of desk accessories (NDAs). The programs in the NDA menu
are available in whatever application you use as long as it
follows Apple's guidelines. However, there are many graphics
based programs that don't support NDAs, and in addition there is
a wealth of software that has been developed for the Byte Works'
ORCA environment. This environment is mainly text-based, and thus
makes access to NDAs impossible. As if that wasn't enough, it's
very difficult to write an NDA to allow the application to keep
running concurrently. So the benefits are lost, and we're back at
ground zero.

Enter the GNO Multitasking Environment.
What was once just dreamed about is now a reality. GNO/ME
provides an environment that is almost entirely compatible with
software developed for the ORCA environment. But GNO/ME also
provides a wealth of new abilities, lots of new ground for
developers and users alike.

Before we begin describing GNO, we'd like to
respond to those who say such a multitasking system isn't
possible on the Apple IIgs. Obviously it is: you hold it in your
hands. Some say the Apple IIgs isn't powerful enough to make
multitasking useful. We point out that the Apple IIgs is much
more powerful than the first computers UNIX was designed to run
on; they only had 64K of real memory, and were 16 bit machines.
Some ask why you'd ever need to run more than one program at
once. These are the same people who asked why we'd ever need more
than 64K of memory, or more than 140K of storage on disks (end
soapbox).

\chapter{Overview}

\section{Introduction}

The GNO Multitasking Environment provides
pre-emptive multitasking. Many programs can be executing at the
same time; each is called a ``process''. Each process is allowed to
run for a short period of time (1/20th of a second on average).
When its time runs out, the current process is set aside and
another one chosen to run next. This cycle continues until there
are no more processes left (i.e. when you exit GNO/ME). Starting
up processes to run 'in the background' is a simple matter of
adding a few characters to the shell commands.

GNO/ME provides a shell that takes full
advantage of the multitasking ability provided. The most
important feature of the shell is job control (starting,
terminating, and suspending processes). But the shell also
provides power never before seen on the Apple IIgs. The ability
to choose files by ``wildcard'' has been around for a while, but
the GNO Shell takes this to a new level with ``regular
expressions'', a very powerful yet simple programming language.
Other benefits of the GNO shell are too numerous to mention. (see
the \bf GNO Shell User's Manual \rm for details).

In addition to being compatible with the
ORCA system, GNO/ME is a very powerful programming environment.
Available to the programmer are all the calls needed to control
processes, support Inter-Process Communication, and other tools
needed in a multitasking environment.
In fact, a large portion of the libraries in GNO v2.0.6 and later
are based upon code from FreeBSD UNIX (see \hturl{http://www.freebsd.org}).
The version of FreeBSD on which the GNO libraries are based is also
available at \hturl{ftp://ftp.gno.org/cdrom/usr/src}.

GNO/ME also boasts the first completely
consistent method for accessing serial and console I/O. The IIgs
TextTools have been incredibly enhanced to provide a truly
all-encompassing interface for serial, console, and IPC
applications. Imagine being able to attach terminals to your GS,
and have a useful shell in each one. Multiuser BBSs, remote
dial-ups, UUCP or SLIP that doesn't take over your computer- the
applications are endless!

With all this talk of shell utilities, have
desktop users (users of programs like AppleWorks GS) been left
behind? Absolutely not. GNO/ME doesn't allow more than one
desktop program to run concurrently, but it DOES let you run a
desktop program with as many text applications as you like. In
other words, no functionality is lost from the IIgs by using
GNO/ME.

Finally, the GNO Multitasking Environment
comes with a large number of free utilities that bring some of
the power of a UNIX system to the Apple IIgs. Also, a number of
programming libraries are included that make it easy to port
programs from UNIX or MS-DOS systems to the Apple IIgs.

%
% Dave Tribby thinks we should add in a ``what's new in 2.0.6'' list 
% here.
%


\section{Documentation Roadmap}

There are many pieces to the GNO documentation.  The primary ones are
listed below.  They are available
at the \gnodocs{GNO Documentation Page} and via anonymous ftp from
\tt ftp.gno.org\rm.

\begin{itemize}
\item	\overview{GNO Overview and Installation Manual}.
\item	\gsh{GNO Shell User's Manual}.
\item	\kernel{GNO Kernel Reference Manual}.
\item	Online Manual Pages.
\item	\faqhtml{GNO Frequently Asked Questions (and Answers) List}.
\end{itemize}

If you are new to GNO, you should start with the Overview and Installation
Manual (this document).

The \gsh{GNO Shell User's Manual} provides information on using \bf gsh\rm, 
which is an ORCA-compatible shell.  It is the primary user interface
to GNO.

The \kernel{Kernel Reference Manual} gives detailed information about
the kernel, which is the heart of GNO.  It is intended mainly for programmers.

The ``Manual Pages'' are the traditional form of UNIX documentation.
They are normally viewed on your GS by typing ``man \it subject\rm'',
where \it subject \rm is the name of the command, library routine, file
(and so forth) for which you are trying to obtain information.
Man pages are provided for the \manpages{base distribution}, and are
usually provided by authors of third-party programs.  Type ``man man''
from within GNO for detailed instructions on how to use the man pages.

The \faqhtml{FAQ} is a list of questions and answers that have come 
up many times; you should read the FAQ before posting any GNO questions
to \delphi{Delphi} or \bf comp.sys.apple2.gno\rm.  Your question may
already be answered.

More information, including an online GNO bugs database, status charts
for ongoing development, and GNO-related links are available online
at \gnodocs{http://www.gno.org/~gno'}.  Because of the nature of this
information, much of it is available only via the WWW, and not 
anonymous ftp.

\section{Hardware Requirements}

GNO/ME will work on any Apple IIgs with at least 2 MegaBytes of
memory and a hard drive.

You should have at least 5 MegaBytes of hard disk space free for GNO
v2.0.4.

GNO version 2.0.6 is \em much \rm larger than previous versions.
Even if you are only installing v2.0.4 at this time, it is recommended
that you reserve at least one 32-megabyte ProDOS partition for
GNO-specific files.

We recommend 4 MegaBytes of Memory and an 
accellerator card, especially if you will be using GNO with many
background processes. A modem and access to an on-line service
will greatly speed access to technical assistance and new
utilities as they are made available.

\section{Obtaining GNO}

GNO is a large and complex system.  There are many pieces to it;
too many to list in detail here.  There are, however, two major
catogories of pieces.  The first is the base distribution, the
second are all the third-party ``add-ons''.  
(Some of the second category sometimes get moved into the base distribution).
Normally, one would install the base distribution, then install 
whichever third-party applications are desired.

Currently, there are available two versions of the base GNO distribution.
The first is version 2.0.4, which is the one last version released by Jawaid.
It is relatively stable and easy to install,
but has no TCP/IP support, a few known bugs, and is not getting
any kernel updates.  (Recent library updates can, to some extent, be used
with this version.)

The second available version is 2.0.6.  It is undergoing active development
and therefore includes bug fixes to v2.0.4, as well as TCP/IP support
in the kernel (it does not currently take advantage of Marinetti).
On the other hand, it is still of alpha quality;  it is difficult to 
install, has some incompatibilities with 2.0.4, and new bugs have been
introduced.  Once it has stabalized more, it will completely supercede
version 2.0.4.

Both base distributions are available via anonymous ftp.
Version 2.0.6 is also available in source form, including via anonymous cvs.
See the respective Installation chapters on downloading these files.

Third party applications are available (among other places) from 
\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/gno}.  Because this
collection has grown so large, James Brookes developed the \bf describe\rm
database (later maintained by Soenke Behrens and Devin Reade), which
provides a description and other information on the various GNO utilities.
Online interfaces to the database may be found at
\hturl{http://www.gno.org/~gno/describe/}
or
\hturl{http://www.servtech.com/public/phoenix/computers/gno/index.html}.

\section{Obtaining Assistance}

Since GNO was reclassified as freeware in the fall of 1997, 
Procyon no longer provides direct support to users, other than those
that had paid the full price for GNO prior to the reclassification.

There is, however, a group of programmers and users of GNO who are
able to render assistance on a volunteer basis.  Some of these programmers
are also actively involved in upgrading the base GNO distribution.

If you require assistance, the following two methods of contact are
preferred:
\begin{itemize}
\item
Post a message to the USENET news group, \bf comp.sys.apple2.gno\rm.
Remember that messages usually take at least a few hours to propagate
around the world.  Answers also take time to propagate.

\item
Ask a question on the Delphi Apple II Programmers' Forum.  There
are subject areas set up for GNO under ``third party technical support''.
Delphi is accessible via \hturl{http://delphi.com}.  (Delphi is
recommended for discussion of programming topics in general and
has, for the most part, taken over from Genie as the center of 
online Apple II communication.  Some packages are available free of
charge.  Visit Delphi for more details.)

Unlike USENET, on Delphi you should try to continue existing threads.
The current ones for GNO are:

	\begin{itemize}
	\item	Message 1045: GNO: System Installation and Configuration
	\item	Message 1046: GNO: References and Users' Manuals
	\item	Message 1047: GNO: Manual Pages
	\item	Message 1048: GNO: The Kernel
	\item	Message 1049: GNO: Shells
	\item	Message 1050: GNO: Libraries and System Header Files
	\item	Message 1051: GNO: Interfacing with ORCA
	\item	Message 1052: GNO: Networking and Telecommunications
	\item	Message 1053: GNO: General Discussion
	\end{itemize}

\item
Also on Delphi, there is a regularly scheduled GNO Programmers' Conference
on Monday and Thursday evenings from 10pm to midnight EST/EDT.  Devin
is usually around those evenings, although he sometimes misses the 
conference.  If you don't catch him the first time, be sure to try again
another day.
\end{itemize}

As a last resort, you can contact Devin Reade (one of the GNO
development team) at \htmailto{gdr@trenco.gno.org}.  Please don't
use this method unless absolutely necessary, as Devin is not always
available.  More importantly, asking questions in an open forum 
provides for peer review; if an answer is wrong, it can be corrected
by other developers.

Finally, for those who paid for GNO before it was reclassified, 
Jawaid can still be contacted at
\htmailto{bazyar@hypermall.com}.
Written correspondence should be directed to Procyon at:

\tt \begin{verbatim}
        Procyon, Inc.
        PO Box 641
        Englewood, CO 80151-0641 USA
        (303) 781-3273
\end{verbatim} \rm 

\section{Reporting Bugs}
\index{bugs}

In any large piece of computer software
such as the GNO/ME system, bugs are sure to turn up, no matter
how much testing is performed on the software before it goes out
the door. If you discover a bug in GNO/ME, we'd like to hear
about it. There are several things we require, however, to make
bug reports useful to us.

First of all, we need a complete
description of your computer system; how much RAM, what cards, in
what slots, what type of disk storage, etc. This information is
very important in tracking down hardware-dependent bugs. Also, we
need to know the version numbers of the software involved; the
GNO Kernel, the GNO Shell, and any utilities.

Second, we need a step-by-step description
of how to duplicate the bug. If this requires writing down
individual keystrokes, then we need it. Only in this way can we
decide whether the bug is hardware dependent or global.

Once you have collected this information, the preferred method of
submitting it is to use the online GNOBugs database at
\hturl{http://www.gno.org/~gno/bugs.html}.
Alternately, you could contact the 
GNO developers in one of the ways mentioned in the section on
\bf Obtaining Assistance\rm.

\section{User Projects}

If you're working on a project which
utilizes GNO/ME in some way, we'd like to know about it. Just
Devin by email and tell him about your project. If possible, he'll
coordinate your efforts with those of other programmers. If we
really like your project and think it may be useful to others, it
may be included on the next GNO/ME distribution!

It is, of course, good to not start work on something that is already
being worked on or already finished.  Before starting a project, you may
first wish to check the Program Status List at
\hturl{http://www.gno.org/~gno/status.bin.html}
or the Library Status List at
\hturl{http://www.gno.org/~gno/status.lib.html}.

\section{Software Piracy}

If you have illegally copied computer software from someone
and are now reading this, take a moment to reflect on what you've done.
Many computer software applications are huge projects, consuming
many man-years of effort, huge amounts of money, and a lot of grief on the
part of the developers.
For example, the Byte Works' ORCA languages and development 
environment (as of November 1997) consists of over 220,000 lines
of source code, \em not \rm including the libraries, tool 
interface files, test programs, samples, or the 5 800k disks
of source in the courses for each language.  This work represents
approximately 17 man-years of development, support, marketing,
and management.

Is it right that you're now benefiting from
developers' efforts without any just compensation to the authors?

Many programmers are born, bred, and raised in the spirit of
computing. They love to write software, and probably always
will. But if they cannot make enough money to make it
worthwhile to continue their work, then they won't; because by
worthwhile, we mean not only food on the table, but resources for
expansion and continued growth. In short,
support them and they'll support you.
 
Computer software is very inexpensive when you
consider what it allows you to do.
 
To all you who properly pay for the software you use:
Thank you.

\section{Suggested Readings}

The following are recommended readings for users:
\begin{itemize}
\item Learning UNIX \cite{gardner}
\item The UNIX Operating System \cite{christian}
\item Peter Norton's Guide to UNIX \cite{norton}
\item UNIX in a Nutshell \cite{gilly}
\item Life with UNIX --- A Guide for Everyone \cite{libes}
\item UNIX for the Impatient \cite{abrahams}
\item Learning the vi Editor \cite{lamb}
\end{itemize}

The following are recommended readings for programmers:
\begin{itemize}
\item The Design and Implementation of the 4.3 BSD UNIX Operating System \cite{leffler}
\item The UNIX Programming Environment \cite{kern_pike}
\item Advanced Programming in The UNIX Environment \cite{stevens}
\item Advanced UNIX Programming \cite{rochkind}
\item Using C on the UNIX System \cite{curry}
\item POSIX 1003.1 \cite{posix1}.  This would normally be considered
	required reading except that the POSIX standards (like most
	standards) are very expensive.  If you can obtain a copy, you
	should try to do so.
\end{itemize}

The following should be considered as required readings for programmers:
\begin{itemize}
\item The ANSI X3.159-1989 (ANSI/C) Standard \cite{ansic}.  This, however,
	is an expensive manual and beyond the financial reach of many
	hobby programmers.  A low-cost alternative is Schildt's
	Annotated ANSI/C Standard \cite{schildt}, provided that you 
	ignore Schildt's annotations.
\item The C Programming Language \cite{kern_ritchie}
\item Apple IIgs ToolBox Reference, Volume 1 \cite{tbr1}
\item Apple IIgs ToolBox Reference, Volume 2 \cite{tbr2}
\item Apple IIgs ToolBox Reference, Volume 3 \cite{tbr3}
\item GS/OS Reference \cite{gsos}
\item Apple IIgs Firmware Reference \cite{gsfirm}
\item Apple Numerics Manual \cite{numerics}
\item Programmers Reference for System 6.0 \cite{pr600}
\item Programmers Reference for System 6.0.1 \cite{pr601}
\end{itemize}

\section{Freeware Status}

The following message was distributed by Jawaid Bazyar by email and
by USENET news, in the fall of 1997:

\begin{quote}

As the man behind Procyon Enterpsises Inc., a long-time Apple IIGS
developer and one of the last commercial developers for the platform,
I regret to announce the end to sales of my first product, the GNO
Multitasking Environment (GNO/ME).

With my last distributor, EGO Systems, closing its doors, I cannot
justify the time and expense of continuing to produce the software. I
also didn't feel it was fair to the customers to continue to charge them
for the product, when I would be unable to support them in the manner
I would like, due to my intense involvement in my new ISP business.

However, instead of simply stopping sales of GNO and letting the software
wander into oblivion, I am placing GNO into ``freeware'' status, and I am
also making available all source code to the 2.0.4 version to the public
and the development community.

I will still sell printed manuals to anyone who wants one, for \$20 or
so, but this is just to cover printing and shipping costs. Purchasing
a manual will not entitle the buyer to support from me of GNO/ME.

Anyone who paid the normal \$89 price to EGO Systems (or to me directly)
for GNO will continue to receive support from me, and I will rely partly
on the help of the ``GNO-Devel'' list for assistance in this support.

Speaking of that, the GNO-Devel list is headed by Devin Reade,
and its members are programmers who have the time and devotion to
continuing to develop the GNO system. To their capable hands I leave
the software. The first task of this group is to put together a GNO
distribution based on the latest ORCA/C and ORCA/C libraries. Devin will
post followup info on csa2g and any inquiries should be directed to him
at <gdr@trenco.gno.org> for the moment.

Thank you all for your support in the past of my company and myself,
and best wishes to you all for the future!

\begin{flushleft}
Regards, \\

Jawaid Bazyar \\
President, Procyon Enterprises Inc. \\
President, Interlink Advertising Services Inc. \\
\end{flushleft}

\end{quote}

\chapter{Installation for GNO v2.0.4}

\em 
\textbf{Important Note:}
This chapter is very out-of-date.  It was written for GNO v2.0.1, and
has had only minor updates since that time.  It very much needs to
be rewritten (concurrently, of course, with updates to the actual
installation process).  However, this is unlikely to occur until
GNO v2.0.6 is released.  This chapter does not apply to installing
GNO v2.0.6.

Before attempting to install GNO v2.0.4, you are strongly encouraged to 
read this entire chapter, and then consult the 
\faqhtml{GNO FAQ} (Frequently Asked Questions list, which is also
available via \faqtext{ftp}) for those sections related to installation.

Suggestions for updating this document (without making major changes
to the GNO v2.0.4 distribution itself) are welcome.  Please email
your suggestions to Devin Reade at \htmailto{gdr@trenco.gno.org}.
\rm

GNO/ME is a very large system. Most of the
system is stored on the three disks in a compressed format. For
this reason we recommend that you read this section carefully and
use the included automated installation program to save yourself
the major headache of arranging everything. You'll need a hard
drive partition with at least 5 Megabytes free to install GNO/ME.
The entire installation process should take no longer than 10
minutes. 

If you are upgrading from GNO 1.0 to GNO
2.0, we recommend that you install GNO 2.0 on a new area of your
hard drive. This is because GNO 2.0 provides new versions of
almost all the utilities and other software provided with GNO
1.0. You can then move the parts of your old system that aren't a
part of the standard GNO 2.0 distribution over to the new
installation. 

The installer program is able to the copy
the GNO libraries for use with the ORCA languages and tools. If
you want to use your ORCA languages and tools, you should answer
the appropriate questions during the install process. ORCA
installation is covered in more detail below.

\section{Obtaining GNO v2.0.4}

The base distribution for GNO v2.0.4 is not actually available as a 
self-contained package.  Instead, it is necessary to install GNO
v2.0.1, then incrementally upgrade it to v2.0.2, v2.0.3, and finally
v2.0.4.

These packages are available via anonymous ftp from 
\tt ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base204\rm.
There is a three-disk set for GNO v2.0.1, and a 
single disk for each of the upgrades to versions 2.0.2, 2.0.3, and 2.0.4.
You should download all of these files.

There is also a custom version of ORCALib that should be installed if you
are using ORCA/C v2.0.x with GNO v2.0.4.

Remember to download these disk archives in binary mode.

\section{Installing GNO v2.0.1}

\begin{description}
\item[Step 1]

Copy the contents of \texttt{/GNO.Disk1} to the partition where you want
to install GNO/ME. The easiest way to do this is to run the IIGS
Finder, insert the \texttt{/GNO.Disk1} disk, and drag the 
\texttt{/GNO.Disk1} icon onto the icon of the drive you want to install on.
The Finder will tell you that the disks are of a different size, and
ask you if you wish to place the contents of \texttt{/GNO.Disk1}
in a folder on the hard drive partition.
Answer ``Yes'', and the Finder will copy the data.

\item[Step 2]

Open the newly created \texttt{GNO.Disk1} folder on the partition
and execute ``Kern'' by double-clicking on the \texttt{Kern} icon.
\texttt{GNO.Disk1} contains a minimal GNO system which you have
just started up. You'll see some copyright messages, and after a few
seconds the desktop will appear.

\item[Step 3]

Install will ask you questions before the installation process begins.
Questions asked by Install are boldfaced in this section.
If you're uncertain of how to answer, click on the ``Info'' button
to get more information on the question. This information is
reproduced here for ease of reference.

\begin{description}

\item[Do you have existing Byte Works (ORCA) language products?]

If you use Byteworks language products such as ORCA/C, ORCA/M,
ORCA/Pascal, and so forth and wish to use them from GNO/ME then
answer ``Yes'' to this question. Otherwise, answer ``No''.

Clicking on the ``Info'' button will display the following text:

	\begin{quote}

	If you currently use products such as ORCA/C, ORCA/Pascal,
	ORCA/M, etc., and wish to use them from GNO/ME then you should
	answer ``Yes'' to this dialog.
        

	Install will then ask you to locate the file ``ORCA.SYS16'' (the
	ORCA Shell). Usually, it will be in a directory called ``ORCA'' on
	one of your hard drive partitions. On our system, it is
	\texttt{:software:orca}.
	The location of this file determines where Install puts the
	GNO-specific ORCA/C header files and libraries (in the ORCA
	LIBRARIES directory).  If you have renamed ORCA.SYS16 to
	something else, select that instead. 

	Install uses this information to correctly set the ORCA prefixes
	and add the EXECUTABLES directory to the \$PATH variable in your
	gshrc file.  See the GNO Shell User's Manual, Appendix B, for
	more information on the ORCA prefixes.

	\end{quote}

\item[Do you want to install the modified ORCA/C 2.0 ORCALIB library?]

If you have ORCA/C 2.0 installed and you answered ``Yes'' to the
previous question, then you should answer 'Yes' now.
If you have ORCA/C 1.3 installed, or you do not have any ORCA languages or
tools, then you should answer ``No''.

Clicking ``Info'' will display the following text:

	\begin{quote}

	GNO/ME 2.0 comes with a modified version of the ORCA/C ORCALIB
	standard library. This library adds specific support for some of
        GNO's special files (pipes, terminals, etc) transparently
        and corrects other problems the standard ORCALIB has with
        GNO.
        
	This special ORCALIB is only for use with ORCA/C 2.0. It will
	NOT work with previous versions of ORCA/C.
        

	Note that all of GNO's other libraries (libgno, libbsd, libc)
	work fine with ORCA/C 1.3.

	\end{quote}

\item[Do you want to install the Multi-User package?]

If you wish to have the Multi-User package installed, answer ``Yes''.
It is recommended that new users do not install this package until they are
familiar with the system. This package is not fully discussed in the
GNO/ME manuals and may introduce many unfamiliar concepts.

Clicking ``Info'' will display the following text:

	\begin{quote}

	The ``Multi-User'' package consists of a number of
	cooperating programs, including \bf init\rm(8) and \bf login\rm(8).
	MU provides for password-protected access to the GNO Shell via the
        console or serial ports (modems and dedicated terminals).
        It also handles multiple user accounts, and a certain
        level of protection between users. 

	If you will be using a terminal with GNO, or want to be able to dial
        into GNO with a modem, you should install MU.
        
	You may wish to hold off setting up the Multi-User package until you
        learn your way around GNO a little better, as it's simple
        to set up MU later.

	\end{quote}

\end{description}

\item[Step 4]

The Installer will now proceed to arrange the GNO Multitasking
Environment on your hard drive. Initially, the contents of
\texttt{/GNO.Disk1} will be moved into the proper places on the
volume you have chosen. When asked by the Installer, you should place
\texttt{/GNO.Disk2} and \texttt{/GNO.Disk3} into the disk drive. The
contents of these disks will be extracted and decompressed into their
proper places.

\em
If the installer cannot finish it's tasks for some reason, it will
abort to the shell. At this point you should study the error messages
to determine the cause of the failure, 
\rm

\item[Step 5]

When the Installer finishes, you will be returned to the GNO prompt.
At this time you should type ``exit'' to return to Finder and delete
the \texttt{GNO.Disk1} directory, as it is no longer needed (GNO
is completely installed in a subdirectory ``\texttt{GNO}'' on the
same partition \texttt{GNO.Disk1} is on.

\end{description}

\section{Installing GNO v2.0.2 Through v2.0.4}

GNO versions 2.0.2 through 2.0.4 were distributed as sequential
updates to version 2.0.1, rather than as complete distributions.
Consequently, you should install each of the version 2.0.2,
2.0.3, and 2.0.4 distributions, \em in sequence, \rm over top of your
version 2.0.1 distribution.

You should also obtain and install the Multi-User Update.

\section{What Has Been Installed?}

\em
\textbf{Note:}  This list of directories is somewhat out of date.
You should consult the \faqhtml{GNO FAQ} (also available via
\faqtext{ftp}) for more current information.
This section will be updated, but likely only after GNO v2.0.6 is 
released.
\rm

If you examine the directory that you chose
for GNO/ME, you will find that the Installer has created several
directories. Here is a brief rundown of thier contents:


\begin{rawhtml}
<!-- cleantable-start -->
\end{rawhtml}
\begin{tabular}{ll}

\bf :gno:bin: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains the executable shell utilities included
	with the GNO/ME package.
\end{minipage} \hfill \\


\bf :gno:dev: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains device drivers. The GNO/ME package
	includes serial drivers for the IIgs' built-in modem and
	printer ports.
\end{minipage} \hfill \\

\bf :gno:etc: \rm	& 
\begin{minipage}[t]{8cm}
	Various system configuration files
\end{minipage} \hfill \\

\bf :gno:initrc \rm	& 
\begin{minipage}[t]{8cm}
	This a startup file for kern and must remain in this directory.
\end{minipage} \hfill \\

\bf :gno:kern \rm	& 
\begin{minipage}[t]{8cm}
	This is the GNO kernel. Launch this to start GNO/ME.
\end{minipage} \hfill \\

\bf :gno:lib: \rm	& 
\begin{minipage}[t]{8cm}
	This directory is provided for programming libraries that are
	used only occasionally.  Various applications may also keep
	auxilliary files here.  It is currently empty.
\end{minipage} \hfill \\

\bf :gno:tmp: \rm	& 
\begin{minipage}[t]{8cm}
	This directory is used by various utilities as location for
	their temporary files.  It is currently empty, and should
	be cleaned on periodically.
\end{minipage} \hfill \\

\bf :gno:user: \rm	& 
\begin{minipage}[t]{8cm}
	This directory is created if you installed the Multi-User package.
	It contains a user directories for users of the system.
	Currently there is only one: ``root''. 
\end{minipage} \hfill \\

\bf :gno:usr: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains UNIX System Resources (USR).
\end{minipage} \hfill \\

\bf :gno:usr:bin: \rm	& 
\begin{minipage}[t]{8cm}
	Miscellaneous utilities.
\end{minipage} \hfill \\

\bf :gno:usr:man: \rm	& 
\begin{minipage}[t]{8cm}
	This directory contains the manual pages for the 'man' utility.
	There are eight categories of information as defined by UNIX
	standards. These eight categories are presented in either
	source (man) or preformatted (cat) form.
\end{minipage} \hfill \\

\bf :gno:usr:games: \rm	& 
\begin{minipage}[t]{8cm}
	The classic ``Hunt the Wumpus'' game, and perhaps others.
\end{minipage} \hfill \\

\bf :gno:usr:sbin: \rm	& 
\begin{minipage}[t]{8cm}
	System administration utilities.
\end{minipage} \hfill \\

\end{tabular}
\begin{rawhtml}
<!-- cleantable-end -->
\end{rawhtml}

\chapter{Installation for GNO v2.0.6}

\em GNO v2.0.6 is not yet available.  These installation instructions
have been included both for the benefit of the development team and as
draft instructions for when the update is released.  Please don't ask
when v2.0.6 will be ready; we'll get it to you as soon as possible.\rm

\em These instructions should be considered as draft quality.  If you
have suggestions on or corrections to these instructions, please forward
them to Devin Reade.\rm

This chapter contains information on how to install the newest version
of GNO, which is version 2.0.6 or later.  It explains how to install
the base \em binary\rm distribution.  Installation of GNO sources such that
you are able to \em build \rm the base distribution itself are at this
time beyond the scope of this document.

At this time, unfortunately, installing GNO is fairly cumbersome.
Gsh's scripting abilities are crude at best, and for various reasons
the Apple Installer program is not sufficient,
When sh (the Bourne Shell) is finished for GNO, installation should be easier.

Information in this chapter may change
significantly from release to release, so even if you have previously
installed a version newer than v2.0.4, you should review this chapter
prior to doing a new installation.

\section{Planning Your System}

The install scripts assumes that your \em new\rm distribution will be installed
on to the two volumes \bf /gno \rm (ProDOS) and \bf /gno-hfs \rm (HFS).
It also assumes these volumes already exist and are \em empty\rm.
You may use other volume names,
but you will have to edit certain files before you run your distribution.


\begin{tabular}{ll}
boot disk (used only for installation)	& 800k \\
binary distribution (shk files)		& 4.6 MB \\
binary distribution (extracted)		& 12.1 MB \\
complete GNO source			& 15.0 MB \\
\end{tabular}


\section{Downloading and Extracting the Binary Distribution}

Your first step is of course to download the distribution.  You should
have the following NuFX archives:

\begin{itemize}

\item{\bf gnoboot.shk\rm}
This is the GNO installation bootstrap disk.  It should be extracted to
a ProDOS-formatted 800k floppy disk named ``/gno.boot'' (the name is
critical).  It does not include a copy of GS/OS and is
therefore not bootable; you will have to boot your system in the normal
fashion.

\item{\bf gno.01.shk\rm, \bf gno.02.shk\rm, ... \bf gno.16.shk\rm}
These disk archives contain the main portion of the GNO distribution.
They must be placed in a single temporary subdirectory on a hard drive,
Zip disk, or other large capacity storage device.  They should not yet be
extracted.

\item{\bf gnohfs.shk\rm}
This archive consists of files that do not conform to ProDOS naming 
conventions.  While it is possible to run GNO without any HFS partitions
at all, it is recommended that you have available to GNO a small amount
of space on an HFS partition.  If you use the \bf namespace\rm(5) facility,
it is unnecessary to dedicate an entire HFS partition to GNO.

\end{itemize}

You should now do the following steps:

\begin{comment}

If your volumes are named something else, replace the names in the cd commands
below with the appropriate name.
 
\end{comment}


\begin{enumerate}

\item
Set your DOWNLOAD\_DIR environment variable to the directory
into which you placed the above NuFX (*.shk) files.
For example, if the files gnohfs.shk, gno.01.shk, gno.02.shk 
(and so forth) were in /download, you would type:

\begin{verbatim}
	setenv DOWNLOAD_DIR /download
\end{verbatim}

\item
Assuming your distribution is to be installed onto the /gno partition,
issue the commands:

\begin{verbatim}
	cd /gno
	/gno.boot/installboot1
\end{verbatim}

This will install the majority of the GNO binaries.

\item
There are a small number of recommended files that do not follow ProDOS
naming conventions.  To install these files, issue the commands:

\begin{verbatim}
	cd /gno-hfs
	/gno.boot/installboot2
\end{verbatim}

This assumes that /gno-hfs is an HFS partition.  If you would like to 
use on your HFS partition a single subdirectory for GNO, then you could
create and cd into /some-partition/gno-hfs instead.

This step is optional.  It is possible to use the GNO binary distribution
without an HFS partition, but some information will be missing.

\item
You should now edit the file /gno/etc/namespace.  If your
files were extracted onto a volume other than /gno, you will
have to replace all the ":gno:" strings with the appropriate
path.

You may want to put /usr onto a different partition; it will
get fairly large over time.

If you have a RAM disk, you should consider having it renamed
to /tmp using renram5(8) or mktmp(8), in which case its entry
should be removed from the namespace file.
	    
See the kernel reference manual for a description of this file.

\item
If you are not short of disk space, you should create .so links
for your manual pages.  (See the mkso(8) man page for an
explanation.)  You can do this by executing the following
commands:

\begin{verbatim}
    	cd /gno/usr/man
    	mkso -v -H /gno-hfs/man mkso.data
\end{verbatim}
	    	
\item
You should now return to your program launcher (the Finder,
ProSEL-16, or whatever you used to start /gno.boot/kern) by
typing "exit" at the prompt.  To startup up your new version
of GNO, you should then launch /gno/kern.  You will then see
a "login:" prompt.  Enter "root" as the user name; you will
not yet need a password.

\end{enumerate}

\section{Custom Configuration}

\it Sorry, this information has not yet been written.\rm

\section{Obtaining Source}

Source for the base distribution is available in one of two ways:
Anonymous FTP and anonymous CVS.

You can obtain the GNO source via anonymous FTP from 
\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base206/src}.
The files in that directory hierarchy are updated daily from the
master repository.  Files that have been recently added or modified
will be listed in one or more of the 
\tt NEW.today\rm ,
\tt NEW.this.week\rm , or
\tt NEW.this.month \rm
files.

\em Please download only what you need.  Sites that attempt to download
all or large portions of the sources on a regular and frequent basis
without first requesting mirror status will be disabled. This is done
to keep a reasonable load level on Trenco.\rm

For those sites which are able to make use of CVS (Concurrent Versions
System), the GNO sources can also be obtained by anonymous CVS in 
pserver mode.  As there is as yet no CVS port to the GS, this implies
that you have another (probably UNIX) machine to which you are downloading
the sources.  Because of the size of the archive, you should also have
a reasonable speed of interconnect between your machine and \tt ftp.gno.org\rm.

The first time you obtain GNO sources via CVS, you must log in to the
repository, then check it out:

\begin{verbatim}
	cvs -d :pserver:cvs@ftp.gno.org:/usr/local/repository login
	Password: cvs
	cd /your/source/tree
	cvs -d :pserver:cvs@ftp.gno.org:/usr/local/repository checkout gno
\end{verbatim}

After this is done, you can update your sources to match the most recent
version by doing the following:

\begin{verbatim}
	cd /your/source/tree/gno
	cvs update -PAd
\end{verbatim}

Because doing updates by CVS does not use up as much bandwidth as 
does downloading the entire source tree, feel free to do cvs updates
on a regular basis.  It usually doesn't make sense to do them more
than once per day, though.

\chapter{Desk Accessories}

The following is a description of the desk
accessories that are shipped with GNO/ME.

\section{GSI NDA}

The \textit{Graphical Shell Interface New Desk Accessory}
allows you to access the shell from a window inside a
desktop application. Selecting ``GSI'' from the Apple menu opens a
window and brings up a shell in it. You can use the shell in this
window just as you would in text mode.

At this time, GSI doesn't support any
terminal emulations --- it's a ``dumb'' interface. As a result,
full screen programs like \bf less\rm(1) and \bf vi\rm(1) will not
work properly in GSI.

\section{Suspend NDA}

The Suspend New Desk Accessory allows you
to temporarily stop a desktop program and return to the text
shell. To return to the desktop program, simply type the foreground
command, ``\texttt{fg}''.

You may put desktop programs in the background
(through the ``\texttt{bg}'' command) 
at your own risk. This is not guaranteed to work for all programs,
and putting a desktop program in the background will not put the
Apple IIgs in text mode.

Also, do not run another desktop program
when one is currently suspended. The GNO kernel tries to cleanly
terminate the second program, but may not always be able to
accomplish this.

\section{GNO Snooper CDA}

The GNO Snooper CDA is a utility that is
very helpful in debugging software, and reporting system crashes.
Snooper has access to information inside the kernel that is not
generally available to processes.

When you enter the control panel and choose
``GNO Snooper'' a process list is displayed, which is
very similar to the \bf ps\rm(1) shell command, and a menu is presented
with the following options, each of which is invoked by typing it's
first letter:

\begin{description}
\item[D)etails]

Get detailed information on a process.
Snooper asks you for the process ID number of the process you
want to investigate. Snooper then dumps the state of the 65816
registers and shows various other information about the process.

\item[K)ill]

This option sends a SIGKILL to a process. Just type in the process ID
of the process you want to kill.

\item[P)rocess Group Dump]

Dumps the system process group tables,
which is very useful for debugging code which manipulates process
groups. The first table, ``pgrp'', is the process group reference
count table. This table lists how many processes (and TTYs)
belong to that process group. 
Process group ids start at 2, so the first pgrp listed is 2.

The second listing is the ttyStruct table.
This table shows to which process group each TTY belongs. The TTYs start
with .null (0), then move on to .ttyb, .ttya, .ttyco, etc.

\item[F)ile Table Dump]

Lists all open files known to GNO.
The information is presented in tuples. The first element is the
real GS/OS refNum or device driver ID. The second is the type of
file (GSOS, ttyXX, or PIPE). The third is how many references to
that file are open. This information is global, so if two
processes have .NULL opened, the refcount for .tty00 will be 2.

\end{description}

\bibliography{gno}

\parindent=20pt


\end{document}
