GNO Patch beta 971222 ===================== This README file contains critical information for the GNO patch designated as "beta 971222". Please read it carefully. Background ---------- Since GNO changed from commercial to freeware status, the single most common class of problems reported by programmers has been incompatibilies when trying to use the GNO v2.0.4 libraries and header files with ORCA/C v2.1.x. Since the GNO v2.0.4 libraries were written to be compatible with ORCA/C v2.0.3, it is not surprising that this causes problems. Also, while development for the next full release of GNO is ongoing, it has been so for some time and it seems that many programmers are getting frusterated by what looks like vapourware. I can empathize with this, but at the same time those components that would be required for a full release are not yet ready for general distribution. Consequently, I have decided to release a limited portion of GNO v2.0.6 that (while it still contains known bugs) seems to be generally stable. This is the set of base libraries needed for most applications, and their associated header files and manual pages. I concede that it's not technically a beta level set of libraries, since they are still undergoing additions. C'est la vie. Who Should Use This Patch ------------------------- This patch is only useful to people actually doing programming for GNO. It will not help the user who is just using GNO for non-programming related tasks. Manifest -------- This patch consists of the following NuFX archives, all of which are required: README.971222 This file. hfsi.971222.shk HFS header files. incl.971222.shk ProDOS header files. libs.971222.shk Library binaries. uman.971222.shk Selected manual pages. Requirements ------------ 1. You MUST have ORCA/C v2.1.x. These headers and libraries *cannot* be used with earlier versions of ORCA/C. Attempting to do so will result in undefined behavior. If you're using an earlier version of ORCA/C, either continue to use the original GNO v2.0.4 libraries for now, or upgrade your version of ORCA/C. 2. Your GNO distribution should be set up with the directory hierarchy specified in the GNO FAQ. It is possible to use a different hierarchy, but if you do then you are on your own; don't expect much in the way of support. Compatibility ------------- This version of the libraries is believed to be compatible with both v2.0.4 and v2.0.6 GNO kernels. However, it includes kernel trap stubs that can only be called from GNO v2.0.6. If you are using v2.0.4, then you must avoid these traps, or they will crash your machine. A list of kernel traps, including which are specific to v2.0.6, can be found in the updated kernel reference at http://trenco.myrias.com/~gno Alternately, if you limit your kernel traps to the set specified in the original v2.0.4 kernel reference manual, then you should be fine. Installation ------------ 1. Install the libraries: a. These directions assume that prefix 13 is set to /lib. As per the requirements, you're on your own if it isn't. At any rate, 13/ and /usr/lib *should* be different directories. b. Move all libraries that you currently have in /lib to another directory. c. Create a temporary directory somewhere. From within this temporary directory, extract the file libs.971222.shk. d. Move the following files to the /lib directory, making sure that the they appear in the given order. See the GNO FAQ if you don't know how to verify or change the file order: libc lsaneglue orcalib sysfloat e. Move the file "libutil" to /usr/lib. f. Copy the original ORCA/C v2.1.x SYSLIB library to /lib. If you have ORCA/Pascal installed, also copy over PASLIB. Any custom libraries that you previously had in /lib should be moved to /usr/lib. The final listing of libraries in /lib, in sequence, are: libc lsaneglue orcalib paslib (if desired) sysfloat syslib g. To access your custom libraries, you will have to explicitly link them in via your link script, makefile, or occ(1) command line option. This is annoying for the occasional program, but makes linking go faster for most programs. 2. Install the ProDOS header files: a. If you have followed the requirements regarding directory hierarchies, then: - all of your ORCA header files should currently be in /lang/orca/libraries/orcacdefs - all of your (old) GNO v2.0.4 header files should be in the /usr/include hierarchy. - you should have a single file in 13/orcacdefs, that being your defaults.h file. b. Rename your old /usr/include hierarchy to /usr/include.204 or something similar. c. If for some strange reason you have a file or directory named /usr/orcacdefs, then temporarily rename it to something else. d. From within the /usr directory, extract the archive incl.971222.shk. You should get two new directories out of it, /usr/include, and /usr/orcacdefs. e. If you don't already have a 13/orcacdefs/defaults.h file, then move the file /usr/orcacdefs/defaults.h to 13/orcacdefs.h. If you already have a 13/orcacdefs/defaults.h file, then edit it and ensure that it contains all the information that is in /usr/orcacdefs/defaults.h, and that there are no conflicts. Where there are conflicts, the new defaults.h file should take precedence. Delete the /usr/orcacdefs directory. If you had an old directory of this name that you renamed in step (c), then you can now rename it back to its original form. 3. Install the HFS header files: a. A small number of GNO v2.0.6 header files do not follow ProDOS naming conventions. These are files that are expected to be present on POSIX or BSD systems, and so are included in GNO. However, in the GNO implementation, they merely "#include" a file which has been renamed to follow ProDOS naming conventions. It is recommended that if your /usr/include directory is not already on an HFS volume, that you maintain a small header file hierarchy on an HFS volume elsewhere. This is not strictly required, but if you do not do it then you may have to edit various source files in order to make them compile (and, consequently, non-portable). b. If /usr/include resides on an HFS partition, then extract the file hfsi.971222.shk from *within* the /usr/include directory. You are now done. c. If /usr/include resides on a ProDOS partition, then create the volume /HFSinclude, possibly through the /etc/namespace facility. (Don't forget that /etc/namespace will not be parsed again until you leave and restart GNO.) d. Extract the file hfsi.971222.shk from *within* the /HFSinclude directory. e. Edit your 13/orcacdefs/defaults.h file. Look for the line #pragma path "/HFSinclude" If you followed step (b), then delete this line. If you followed steps (c) and (d), and if you have used a directory *other* than "/HFSinclude" for the HFS include files then edit the pragma line to reflect that volume/directory name. 4. Install the manual pages: a. The manual pages in the archive uman.971222.shk are the basis of the /usr/man hierarchy for GNO v2.0.6, for the most part, only chapter 2 and 3 manual pages have been included in this release. It is recommened that you rename your current /usr/man directory to /usr/man204 or something similar. You must then manually create the following directories: /usr/man /usr/man/man1 /usr/man/man2 /usr/man/man3 /usr/man/man4 /usr/man/man5 /usr/man/man6 /usr/man/man7 /usr/man/man8 b. GNO v2.0.6 makes use of HFS volumes for a small number of files. Some of these files are source links to manual pages, where the link files do not follow ProDOS naming conventions. If your current /usr/man directory resides on an HFS partition, then skip this step. If it does not already reside on an HFS volume, then it is recommended that you have a second directory available as well, such as /HFS/usr.man. Assuming this is so, then you must manually create the following directories: /HFS/usr.man /HFS/usr.man/man1 /HFS/usr.man/man2 /HFS/usr.man/man3 /HFS/usr.man/man4 /HFS/usr.man/man5 /HFS/usr.man/man6 /HFS/usr.man/man7 /HFS/usr.man/man8 You can get by without using HFS volumes at all, but GNO may be a bit harder to use. For example, not having the above directories will mean that commands like man __C2GS and man 3 _exit will fail. The manual pages will still be on your system but you have to remember to call them by the proper names, such as man GSString and man 3 exit c. Next, you should extract the file uman.971222.shk from within your *new* /usr/man directory. d. Within /usr/man, you should now have eight subdirectories and the following two files: mkso mkso.data These files are used to create manual page source links. If you have a separate HFS manual page hierarchy (as explained in (c), above), then you should issue the following command, substituting for "/HFS/usr.man" the directory that you actually used: ./mkso -H /HFS/usr.man mkso.data If your /usr/man is already on an HFS volume, or if you aren't using HFS volumes at all, then issue the following command: ./mkso mkso.data This will create the source links. If you would like to see what mkso is doing, then you can use the "-v" verbose option. It must occur *before* the final file name: ./mkso -v -H /HFS/usr.man mkso.data or ./mkso -v mkso.data If You Wish to Make Submissions ------------------------------- If you have implemented routines that you believe should be in the GNO base distribution, then contact me (preferably on comp.sys.apple2.gno, by email if necessary) to discuss it. Some general guidelines for functions are: - relevent to a large number of programs - if variants of the function exist in the UNIX world, you should be using POSIX- or BSD4.4-based implementations. GNO v2.0.6 is based on BSD, and we wish to avoid SYSV implementations where such implementations conflict. - if the source is in assembly, please ensure you segment it. This is also desirable if the source is in C, but is less critical. - If you are porting a BSD implementation, please base it on the source distribution given below. The BSD 4.4 source upon which the current libraries are based is available via anonymous ftp from: ftp://trenco.myrias.com/cdrom/usr/src/lib If You Find Bugs/Problems ------------------------- If you just have questions about GNO, please see the section on "Support", below. First of all, please *do not* submit bug reports to the Byte Works unless you have verified that the problem exists when running ORCA/Shell and using standard ORCA libraries and header files. The libraries and headers here have been modified for GNO, and while this has been done with the consent of Byte Works, they are not responsible for any bugs or deficiencies which I have introduced. If you think you have found a problem, please verify the expected behavior with the new man pages. There are known problems, often listed in a "BUGS" subsection. Also see the end of the GNO FAQ for known problems that may affect your program. If you are still in the stage of tracking a problem, please discuss it on comp.sys.apple2.gno. If you have found what you believe to be a bug, please submit a *short* program exhibiting the behavior. Make sure it compiles and links without reference to custom header files or libraries. Give a good description of the problem, and what you believe the behavior *should* be. Finally, post the problem report on csa2g and cc me at the email address at the bottom of this README file. Before you do this, make sure that you read the section on "Support", below. Support ------- As this release is intended for people already knowledgable in programming, the amount of support you will receive depends a lot on the kind of problems you run into, and how you ask the questions. My general criteria is that: - good bug reports get top priority, especially if they regard critical functionality - other problems will be addressed if they don't take up too much of my time; time spent answering questions has to be balanced with development time. Questions along the lines of "I installed GNO and it doesn't work. Why?" don't tell me very much and won't get much attention. Sorry, but I'm doing this in my spare time and if you don't take the time to ask an informative question, I'm not going to take the time to give an informative answer. Be clear and concise. For people who do not have English as their primary language, I understand that your questions may not be grammatically correct, but I will do my best to figure out what you're asking and help you out. However, there seems to be an increasing number of people who *do* have English as their primary language, but can't seem to express themselves; their sentences come out as gibberish. If I don't know what you're saying, I can't help. Questions should be directed to the USENET newsgroup comp.sys.apple2.gno. *All* questions can be asked there, and I will attempt to help you out. How much help you get depends on the question (see above). Asking on comp.sys.apple2.gno also allows other developers to address your questions. I also follow the Delphi A2Pro(grammers') Forum, so feel free to ask questions there. I host a real time conference in Delphi A2Pro most Monday and Thursday nights from 10 to midnight (or later), eastern time. (Zulu -5, I believe.) Feel free to drop by and ask questions. I do not have a Genie account. In general, please do not contact me directly in email regarding this release unless it is an explicit bug report (see above). Devin Reade gdr@eddore.myrias.com 22 December 1997