From 71e01a032521acd0cdcff4307eb4e091b058b78f Mon Sep 17 00:00:00 2001 From: Devin Reade Date: Tue, 4 Sep 2012 23:40:31 -0600 Subject: [PATCH] added the Intro and Installation manual --- etc/const.mk | 2 + etc/rules-tex.mk | 2 +- refs/GNUmakefile | 2 +- refs/intro/.gitignore | 10 + refs/intro/GNUmakefile | 19 + refs/intro/intro.bib | 231 ++++++ refs/intro/intro.tex | 1596 ++++++++++++++++++++++++++++++++++++++++ 7 files changed, 1860 insertions(+), 2 deletions(-) create mode 100644 refs/intro/.gitignore create mode 100644 refs/intro/GNUmakefile create mode 100644 refs/intro/intro.bib create mode 100644 refs/intro/intro.tex diff --git a/etc/const.mk b/etc/const.mk index 86a533d..218477c 100644 --- a/etc/const.mk +++ b/etc/const.mk @@ -83,6 +83,8 @@ TEX_GARBAGE = \ $(TEX_SRC_BASENAME).out \ $(TEX_SRC_BASENAME).dvi +BIBTEX_GARBAGE = $(TEX_SRC_BASENAME).bbl $(TEX_SRC_BASENAME).blg + # Various latex-related paths DVIPS = dvips DVIPDF = dvipdfm diff --git a/etc/rules-tex.mk b/etc/rules-tex.mk index 7d313aa..660de0f 100644 --- a/etc/rules-tex.mk +++ b/etc/rules-tex.mk @@ -24,7 +24,7 @@ tex_pdf_ltr: webHome $(TEX_PDF_LTR) tex_pdf_a4: webHome $(TEX_PDF_A4) clean:: - /bin/rm -f $(TEX_GARBAGE) + /bin/rm -f $(TEX_GARBAGE) $(BIBTEX_GARBAGE) $(WEB_HOME)/%.ltr.ps: %.dvi $(DVIPS) -tletter $(DVIPS_FLAGS) -o $@ $< diff --git a/refs/GNUmakefile b/refs/GNUmakefile index 8b26857..31e59fa 100644 --- a/refs/GNUmakefile +++ b/refs/GNUmakefile @@ -3,7 +3,7 @@ # SRCROOT = .. WEB_HOME_BASE = refs -SUBPROJECTS = kernel gsh +SUBPROJECTS = intro kernel gsh include $(SRCROOT)/etc/const-priv.mk include $(SRCROOT)/etc/const.mk diff --git a/refs/intro/.gitignore b/refs/intro/.gitignore new file mode 100644 index 0000000..c762009 --- /dev/null +++ b/refs/intro/.gitignore @@ -0,0 +1,10 @@ +*.aux +*.dvi +*.idx +*.ilg +*.ind +*.log +*.out +*.toc +*.bbl +*.blg diff --git a/refs/intro/GNUmakefile b/refs/intro/GNUmakefile new file mode 100644 index 0000000..da05ea0 --- /dev/null +++ b/refs/intro/GNUmakefile @@ -0,0 +1,19 @@ +# +# Kernel Reference Manual +# +SRCROOT = ../.. +WEB_HOME_BASE = refs/intro +SUBPROJECTS = + +TEX_SRC_BASENAME = intro +TEX_TITLE = GNO Overview and Installation Manual + +include $(SRCROOT)/etc/const-priv.mk +include $(SRCROOT)/etc/const.mk +include $(SRCROOT)/etc/const-tex.mk +-include $(SRCROOT)/etc/const-local.mk + +include $(SRCROOT)/etc/rules.mk +include $(SRCROOT)/etc/rules-tex.mk + +buildLocal:: texBuild diff --git a/refs/intro/intro.bib b/refs/intro/intro.bib new file mode 100644 index 0000000..1cce209 --- /dev/null +++ b/refs/intro/intro.bib @@ -0,0 +1,231 @@ +@book{abrahams, +author = "Paul Abrahams and Bruce Larson", +title = "UNIX for the Impatient", +publisher = "Addison Wesley", +year = 1992, +note = "ISBN: 0-201-55703-7\\ +\textsl{Highly recommended.} +A new, comprehensive, in-depth reference to UNIX. ``a handbook +you can use both as a manual to learn UNIX and as a ready +reference for fast answers to specific UNIX questions.''" +} + +@book{ansic, +author = "ANSI X3.159 Committee", +title = "ANSI X3.159-1989: Programming Language -- C", +publisher = "American National Standards Institute", +year = 1989 +} + +@book{tbr1, +author = "Apple Computer", +title = "Apple IIgs ToolBox Reference, Volume 1", +publisher = "Addison-Wesley", +year = 1988, +note = "ISBN 0-201-17746-3\\ +This book is now published by the Byte Works." +} + +@book{tbr2, +author = "Apple Computer", +title = "Apple IIgs ToolBox Reference, Volume 2", +publisher = "Addison-Wesley", +year = 1988, +note = "ISBN 0-201-17747-1\\ +This book is now published by the Byte Works." +} + +@book{tbr3, +author = "Apple Computer", +title = "Apple IIgs ToolBox Reference, Volume 3", +publisher = "Addison-Wesley", +year = 1990, +note = "ISBN 0-201-55019-9\\ +This book is now published by the Byte Works." +} + +@book{gsos, +author = "Apple Computer", +title = "GS/OS Reference", +publisher = "Addison-Wesley", +year = 1990, +note = "ISBN 0-201-55020-2" +} + +@book{gsfirm, +author = "Apple Computer", +title = "Apple IIgs Firmware Reference", +publisher = "Addison-Wesley", +year = 1987, +note = "ISBN 0-201-17744-7" +} + +@book{numerics, +author = "Apple Computer", +title = "Apple Numerics Manual", +publisher = "Addison-Wesley", +year = 1988, +edition = "Second", +note = "ISBN 0-201-17738-2" +} + +@book{christian, +author = "Kaare Christian", +title = "The UNIX Operating System", +publisher = "Wiley", +year = 1988, +edition = "Second", +note = "ISBN: 0-471-84781-X\\ +A classic overview of UNIX commands. Good in coverage." +} + +@book{curry, +author = "David Curry", +title = "Using C on the UNIX System", +publisher = "O'Reilly", +year = 1990, +note = "ISBN: 0-937175-23-4\\ +This book is directed to (would-be) system programmers." +} + +@book{gardner, +author = "James Gardner", +title = "Learning UNIX", +publisher = "Sams", +year = 1991, +note = "ISBN: 0-672-30001-X\\ +Comes with disks containing an MSDOS simulation of UNIX. +A good tutorial or reference book for those without constant +access to UNIX." +} + +@book{gilly, +author = "Daniel Gilly", +title = "UNIX in a Nutshell", +publisher = "O'Reilly", +year = 1992, +edition = "Second", +note = "ISBN: 1-56592-001-5\\ +\textsl{Highly recommended.} +An excellent desktop reference to almost all UNIX commands ``a +complete reference containing all commands and options, plus +generous descriptions and examples that put the commands in +context.''" +} + +@book{posix1, +author = "ISO/ANSI", +title = "POSIX 1003.1: System Application Program Interface", +publisher = "ISO/ANSI", +year = 1996, +edition = "Second", +note = "ISO/IEC 9945-1, ANSI/IEEE Std 1003.1" +} + +@book{kern_pike, +author = "Brian Kernighan and Rob Pike", +title = "The UNIX Programming Environment", +publisher = "Prentice-Hall", +year = 1984, +note = "ISBN: 0-13-937681-X\\ +A true classic on UNIX programming." +} + +@book{kern_ritchie, + author = "Brian Kernighan and Dennis Ritchie", + title = "The C Programming Language", + edition = "Second", + publisher = "Prentice Hall", + year = 1988, + note = "ISBN 0-13-110362-8" +} + +@book{lamb, +author = "Linda Lamb", +title = "Learning the vi Editor", +publisher = "O'Reilly", +year = 1990, +note = "ISBN: 0-937175-67-6\\ +A very good guide to vi and ex commands. With a quick reference card." +} + +@book{leffler, +author = "Samuel Leffler, et al", +title = "The Design and Implementation of the 4.3 BSD UNIX Operating System", +publisher = "Addison-Wesley", +year = 1990, +note = "ISBN: 0-201-06196-1\\ +An authoritative description of +the design of BSD UNIX. ``It covers the internal structure of +the 4.3BSD system and the concepts, data structures, and +algorithms used in implementing the system facilities.''" +} + +@book{libes, +author = "Don Libes and Sandy Ressler", +title = "Life with UNIX --- A Guide for Everyone", +publisher = "Prentice Hall", +year = 1990, +note = "ISBN: 0-13-536657-7\\ +\textsl{Highly recommended.} +An ``everything you want to know about UNIX'' book. It includes info you +might not find elsewhere. ``This book is the +'other' book about UNIX, a study in reading between the +lines - which is very much what learning UNIX is like.''" +} + +@book{norton, +author = "Peter Norton and Harley Hahn", +title = "Peter Norton's Guide to UNIX", +publisher = "Bantam Computer", +year = 1991, +note = "ISBN: 0-553-35260-1\\ +Good coverage. A good introduction for beginners (especially those +accustomed to DOS)." +} + +@book{rochkind, +author = "Marc Rochkind", +title = "Advanced UNIX Programming", +publisher = "Prentice Hall", +year = 1985, +note = "ISBN: 0-13-011818-4\\ +A superb book covering all system calls in detail." +} + +@book{schildt, +author = "Herbert Schildt", +title = "The Annotated ANSI C Standard", +publisher = "McGraw Hill", +year = 1990, +note = "ISBN: 0-07-881952-0\\ +This book should only be used if the annotations (the right-hand +pages) are ignored, as they contain many errors." +} + +@book{stevens, +author = "Richard Stevens", +title = "Advanced Programming in The UNIX Environment", +publisher = "Addison-Wesley", +year = 1992, +note = "ISBN: 0-201-56317-7\\ +\textsl{Highly recommended.} +A going-to-be classic on how programs work under UNIX. The source +codes and errata list are obtainable by anonymous ftp from +ftp.uu.net (in /published/books)." +} + +@book{pr600, +author = "Mike Westerfield", +title = "Programmers Reference for System 6.0", +publisher = "Byte Works, Inc", +year = 1992 +} + +@book{pr601, +author = "Mike Westerfield", +title = "Programmers Reference for System 6.0.1", +publisher = "Byte Works, Inc", +year = 1993 +} + diff --git a/refs/intro/intro.tex b/refs/intro/intro.tex new file mode 100644 index 0000000..6f20434 --- /dev/null +++ b/refs/intro/intro.tex @@ -0,0 +1,1596 @@ +% +% GNO Overview +% +% $Id: intro.tex,v 1.17 2012/08/25 21:53:25 gdr Exp $ +% + +\documentclass{report} +\usepackage{html} +\usepackage{hthtml} +\usepackage{makeidx} +\makeindex +\bodytext{ + bgcolor=#ffffff + textcolor=#000000 + linkcolor=#0000FF + vlinkcolor=#001177 + alinkcolor=#001177 + } + +\begin{document} + +\title{GNO Overview and Installation} +\author{Jawaid Bazyar, Tim Meekins, Devin Reade} +\date{November 1997} +\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/index.html}} +\newcommand{\manpages}[1]{\htlink{#1} + {http://www.gno.org/~gno/manindex.html}} +\parindent=0pt +\parskip=1pc + +The GNO Multitasking Environment is Copyright 1991-1999 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-1999 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-1999, 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 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:} +GNO v2.0.4 is no longer supported. New installations should be using +v2.0.6 or later. +\rm + +\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 since v2.0.4 +has been superceded. That notwithstanding, if you have suggestions +for updating this document (without making major changes +to the GNO v2.0.4 distribution itself), please email +your suggestions to Devin Reade. + +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. +\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} + +\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} + +\end{rawhtml} + +\chapter{Installation for GNO v2.0.6} + +\em +\textbf{Important Note:} +Before attempting to install GNO v2.0.6, 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. +\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 or AppleShare). +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. + +If you installing over an existing v2.0.6 or later distribution, ensure +that you read the section on \bf Planning for Future Upgrades\rm. + +You will need \it at least \rm the following amount of disk space. +It is recommended that you dedicate an entire 32Meg ProDOS partition to +GNO. + +\begin{tabular}{ll} +boot disk (used only for installation) & 800k \\ +binary distribution (shk files) & 5.3 MB \\ +binary distribution (extracted) & 12.0 MB \\ +complete GNO source (optional) & 15.0 MB \\ +\end{tabular} + +Before you start, you should also ensure that your system meets the +minimum hardware requirements, as documented in \bf Overview\rm. + +In order to install GNO, you will need some way to download the NuFX +archive files to your GS. You will also need GS-ShrinkIt, which is available +from +\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/archivers/gshk11.bsc}. + +Part of the GNO installation still requires use of a text editor. The +GNO boot disk ships with \bf vi\rm installed; +if you do not know how to use \bf vi\rm (or you need a refresher), see +\hturl{http://www.jaws.umn.edu/~tobkin/vi} +for a good tutorial and quick reference guide. + +\section{Upgrading from GNO v2.0.4 or Earlier} + +If you already have an existing GNO installation running v2.0.4 or +earlier, then there is no automated upgrade mechanism. Instead, upgrades +must be done manually. + +Before doing such an upgrade, ensure that you have a backup of your +existing system. + +Although it is more disk space intensive, you should upgrade from your +existing v2.0.4 system by first installing the current distribution into +an otherwise unused directory hierarchy (a ``from scratch'' install). +You should then review each component of your old distribution and move +any necessary files into the new hierarchy. It is \em strongly \rm +recommended that you make maximal use of the \bf /usr/local \rm hierarchy +so that future upgrades are easier. See the section in this Guide on +\bf Planning for Future Upgrades \rm for details. + +This method of upgrade is tedious, but in the end it makes for a cleaner +GNO distribution and easier future upgrades. + +\section{Downloading and Extracting the Binary Distribution} + +If you have not yet read the section on \it Planning Your System\rm, +please do so now. + +Your first step is of course to download the distribution. +The distribution is available from +\hturl{ftp://ftp.gno.org/pub/apple2/gs.specific/gno/base}. +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, Appleshare volume, 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. +It should be placed into the same directory as were the files +{\bf gno.01.shk\rm, \bf gno.02.shk\rm, ... \bf gno.16.shk\rm}. +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. +Note that Appleshare volumes may be used in lieu of HFS volumes. + +\end{itemize} + +Using the Finder or a similar program, ensure that you have an empty ProDOS +partition \bf /gno \rm, and an HFS or AppleShare partition online. The +former \em may \rm be named something else, but note the instructions +below for handling this situation. The latter is assumed to be called +\bf /gno-hfs \rm (modify the following instructions accordingly), and +need not be otherwise empty. The two subdirectories \bf HFSinclude \rm +and \bf man \rm will be created on \bf /gno-hfs \rm during the installation +process. + +Next, using GS-ShrinkIt or a similar program, extract the contents of the +file gnoboot.shk onto an 800k floppy named \bf gno.boot\rm. +The name of the floppy is critical. While you may use a hard drive +partition for \bf gno.boot\rm, this is likely a waste of hard drive space +since \bf gno.boot\rm will only be used while installing GNO, not while +running it. + +People have also reported that they were able to use a RAM disk for +\bf gno.boot\rm without problems (thanks to Kirk Mitchell for first +reporting this). + +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} + +% We would like to be using bold face type for some parts of this, but +% it appears that the current version of tex2html can't handle boldface +% within an enumerated list. + +\item +From your program launcher (typically the Finder), run the program +/gno.boot/kern. +This is the GNO kernel. It will come up in +single user mode and you will be logged in as root running a +gsh +shell session. + +Note that the boot disk currently uses the version 2.0.4 GNO kernel; this +is a temporary measure due to a bug with using newer kernels in single user +mode. When GNO is installed on your hard drive, you will have a newer +kernel. + +\item +As per the instructions shown on the boot screen, you should now read the +file /gno.boot/README.install. The contents of that file, however, are +identical to the numerated instructions below; you need only read one or +the other set. + +%% README.install-start +\item +Set your DOWNLOAD\_DIR environment variable to the directory +into which you placed the base distribution NuFX archive files +(gnoboot.shk, gnohfs.shk, gno.01.shk, and so forth). For +example, if the NuFX files were in /download, you would type: + +\begin{verbatim} + setenv DOWNLOAD_DIR /download +\end{verbatim} + +Ensure that you use slashes (``/'') rather than colons (``:'') as the +pathname delimiter. Do not use a trailing slash. + +\item +Install the majority of the GNO base distribution files by +changing directory into your destination directory and running +the installboot1 script. Assuming that you will be installing +to the partition /gno, the commands would be: + +\begin{verbatim} + cd /gno + /gno.boot/installboot1 +\end{verbatim} + +This step takes quite a while, even with an accelerated IIgs. +Have patience. + +\item +There are a small number of recommended files that do not follow +ProDOS naming conventions. If you wish to install these files, +make sure that you have an HFS or Appleshare disk online. Change +directories to that disk (or subdirectory) and run installboot2. +Assuming that the HFS disk is /gno-hfs, the commands are: + +\begin{verbatim} + cd /gno-hfs + /gno.boot/installboot2 +\end{verbatim} + +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. Similarily, you will have to replace ``:gno-hfs:'' if +that is not the name of your HFS (or Appleshare) partition +where you ran the installboot2 script. Note that you cannot +currently use pathnames in the namespace file that contain spaces. + +The gno.boot disk includes the vi utility to do these edits. +You can also edit the namespace file with any other text editor +of your choosing, as long as it is done before you try to run +your new GNO distribution. + +A vi tutorial and quick reference guide may be found at +\hturl{http://www.jaws.umn.edu/~tobkin/vi}. + +\begin{comment} +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. + +\end{comment} +For a description of the namespace file, see the kernel +reference manual, or the namespace(5) manual page at +\hturl{http://www.gno.org/~gno/man/man5/namespace.5.html} + +\item +During the extraction process, the following files were placed +into the /gno/System directory: + +\begin{verbatim} + /gno/System/Desk.Accs/GNOSnooperII + /gno/System/Desk.Accs/SuspDA + /gno/System/Desk.Accs/TMTerm + /gno/System/Drivers/FilePort + /gno/System/Drivers/FilePort.Data + /gno/System/Drivers/NullPort + /gno/System/System.Setup/GNOBug + /gno/System/System.Setup/SIM +\end{verbatim} + +It is recommended that these files be copied into the relevent +directories in the System folder of your boot partition. The +GNOBug PIF is only required if you have GSBug installed. If +you install GNOBug you should afterward sort the System.Setup +directory so that GNOBug appears before GSBug (the latter of +which is commonly called ``debug.init''). + +\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} + +If you installed GNO somewhere other than /gno and /gno-hfs, then +edit the above lines accordingly. If you did not install files +onto an HFS (or Appleshare) partition at all, then execute the +following commands instead: + +\begin{verbatim} + cd /gno/usr/man + mkso -v mkso.data +\end{verbatim} + +\item +You can 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. + +%% README.install-end + +\end{enumerate} + +\section{Planning for Future Upgrades} + +\it The information in this section is currently under review; please +forward any additions, deletions, or corrections to Devin Reade.\rm + +One of the concerns for a system that is as large and as complex as GNO +is how to keep it updated without losing any custom configuration that +been added locally since the last installation. This section attempts to +document how to minimize such conflicts and, where the conflicts can't +be avoided, where they are likely to occur. + +In the context of updating GNO, there are three main sets of files. The +first one is anything that is in the \bf /usr/local \rm hierarchy. The +subdirectories and files under \bf /usr/local \rm are intended strictly +for site-specific customization. The GNO base distribution does not, +and never will, add or modify files within \bf /usr/local\rm. (It may, +however, ensure that certain subdirectories exist.) For this reason, +it is recommended that any files (such as programs, configuration files, +or manual pages) that you wish to have on your system but are not part +of the GNO base distribution are placed within the \bf /usr/local \rm +hierarchy. If you wish to have this customation available to another +GNO installation, it would then be sufficient to copy the \bf /usr/local \rm +hierarchy in its entirety. + +\em +NOTE: There is a single (temporary) exception to the comments above. The +current GNO base distribution will copy in the file +\textbf{/usr/local/lib/startup.mk} +which is used by the program dmake, and which is a duplicate of +\textbf{/usr/lib/startup.mk}. +When dmake gets updated to properly use +\textbf{/usr/lib/startup.mk} +as it's configuration file, then +\textbf{/usr/local/lib/startup.mk} +will no longer be created by the GNO base install scripts. If you have +customized +\textbf{/usr/local/lib/startup.mk} +for your site, you first save your startup.mk file elsewhere, then merge +those customizations into the new startup.mk. +\rm + +The second set of files are those which have been written such that they +(or their configuration files) have pathnames which are hardcoded, and +therefore must reside outside of the \bf /usr/local \rm hierarchy. Some +of these programs can be forced into the first set described above by +setting appropriate environment variables; see the program's documentation +for details. For the remainder, you should keep track of which programs +you have installed, and where they (or their configuration or data files) +reside. Unless there is a name conflict with files in the GNO base +distribution, these files won't be overwritten or deleted during a GNO +update, but they obviously will not be copied in when doing a ``from scratch'' +installation. + +The third set of files are those are created while installing the GNO +base distribution, but which almost certainly have been modified in +any existing GNO site. +These are all configuration files of one sort or another. +(If you are doing a fresh install, you can ignore +this set.) If you are using the GNO ``from scratch'' installation scripts +rather than the update scripts +(\em not yet available\rm) +then you \em must \rm ensure that you have backups of these files so +that you can restore them after the install scripts have completed. You +should not merely copy your old versions over the new ones; instead +compare the old files to the new to verify if there have been features +added which should be propagated to your old customized files. + +The files which are known to be in the third set are listed here: + +\begin{verbatim} + /etc/glogin + /etc/group + /etc/hosts + /etc/inittab + /etc/motd + /etc/networks + /etc/namespace + /etc/passwd + /etc/rchost + /etc/syslog.conf + /etc/whereis.conf + /home/root/gshrc + /lib/orcacdefs/defaults.h + /var/adm/newuser/newid + /var/adm/newuser/skel/glogin + /var/adm/newuser/skel/gshrc +\end{verbatim} + +If you find that you have to modify any files outside of the \bf /usr/local \rm +(or \bf /home\rm ) hierarchy, you should record which files have been so +modified, together with a brief description of the necessary changes. + +\section{Custom Configuration} + +\it The information in this section is currently under review; please +forward any additions, deletions, or corrections to Devin Reade.\rm + +This section describes the configuration changes that are commonly done +on newly installed systems. + +If you have not already read the section on \bf Planning for Future +Upgrades \rm, you should do so now. + +\subsection{Passwords} + +If you ever expect to connect your IIgs to a network (including the internet) +it is recommended that you password protect all of your GNO user IDs. +This is done with the +\htlink{passwd}{http://www.gno.org/~gno/man/man1/passwd.1}(1) +command; see the manual page for details. + +Because there is no inherent security features in the Apple IIgs in general +(or GNO in particular), password protecting accounts on a stand-alone +machine does not gain any real level of security; if someone has physical +access to your IIgs, then they can get anything off of it that they want +to. On the other hand, password protecting your accounts can't hurt, and +it is an excellent habit to get into. (Rather, \em not \rm password +protecting accounts is a very poor habit to get into.) + +\subsection{Configuring the Namespace Facility} + +\em This section is yet to be written. \rm + +\subsection{Configuring Host and Network} + +\em This section is yet to be written. \rm + +\subsection{Configuring the System Logger} + +\em This section is yet to be written. \rm + +\subsection{Configuring the Shell} + +\em This section is yet to be written. +Talk briefly on /etc/glogin, \$HOME/glogin, and \$HOME/gshrc. +Leave real docs for the gsh manual. +\rm + +\subsection{Message of the Day} + +\em This section is yet to be written. \rm + +\subsection{Adding Groups} + +\em This section is yet to be written. \rm + +\subsection{Adding Users} + +\em This section is yet to be written. \rm + +\subsection{Configuring Documentation Programs} + +\em This section is yet to be written. +Discuss /etc/whereis.conf, MANPATH, etc. +\rm + +\subsection{Configuring Outbound SLIP} + +\em This section is yet to be written. \rm + +\subsection{Configuring Inbound Serial Connections} + +\em This section is yet to be 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/base/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{intro} + +\parindent=20pt + + +\end{document}