Path: news.uiowa.edu!news.physics.uiowa.edu!math.ohio-state.edu!howland.reston.ans.net!nntp.crl.com!decwrl!tribune.usask.ca!rover.ucs.ualberta.ca!Myrias.AB.CA!eddore.myrias.com!eddore.myrias.com!not-for-mail From: gdr@eddore.myrias.com (Devin Reade) Newsgroups: comp.sys.apple2.gno Subject: Re: info on porting to GNO needed Date: 4 Feb 1996 18:47:58 -0700 Organization: Myrias Research Corporation Lines: 189 Message-ID: <4f3nke$384@eddore.myrias.com> References: NNTP-Posting-Host: eddore.myrias.com In article , Paul Schultz wrote: >I thought I would compile a list of common considerations a >programmer needs to take into account when porting C source >code to GNO. If I get something cohesive enough, I thought it >could be included in a future edition of the GNO FAQ. (Or, it >could be a FAQ of its own!) > >At any rate, please post your tricks, suggestions, etc... here! As requested ... * * Here is a list of tips for porting programs to the IIgs under GNO. * Some are GNO specific and some are Orca/C specific. * * Those that show a version number like [v2.0.3] indicate a reported * compiler bug that is being avoided. These checks may disappear * from this list in the future. The others are not likely to do * so. * * If you have additions to or comments on this list, please forward * them to Devin Reade, . * #define SOAPBOX 1. Make sure you have an up-to-date compiler and libraries. 2. Get a copy of Soenke Behrens' Orca/C bug list. Read it, understand it, and keep it at the back of your mind when porting/writing code. It doesn't matter that your code is correct; if Orca/C bites the big one it can waste your time. The bug list can be found at "http://194.72.60.96/www/thesonkpage/obugs.htm". 3. Make sure you have the proper documentation on hand for what you are trying to do. This may include but is not limited to: GNO kernel and shell reference GNO manual pages (particularily sections 2, 3, 4, and 7) Orca/C manual and, if you have it, the Orca/M manual. Toolbox ref vol 1,2,3 Programmer's Ref for 6.0, 6.0.1 IIgs Firmware reference IIgs Hardware reference GS/OS reference ANSI/ISO 9899 Standard (defines ANSI/C). This is an expensive document, but you get a cheap copy by buying Schildt, Herbert _The_Annotated_ANSI_C_Standard_, McGraw-Hill, ISBN 0-07-881952-0. The book is set up so that the standard is printed on the "left" pages and the annotations are on the "right" pages. MAKE SURE YOU USE ONLY THE LEFT PAGES; the annotations have just enough errors in them to be dangerous. IEEE Std 1003.1-1988 (or later) -- The POSIX standard. Apple Numerics Manual (optional) For those docs that have updates (such as the Programmers' ref as an update for the Toolbox refs), write in the older versions a note for each updated routine the fact that it _is_ updated and in which manual the update is located. #undef SOAPBOX * * Ok, now for some specifics. Before you try compiling your programs, * make the following changes: * 4. Change invocations of fork(2) to use the GNO syntax/semantics. You may find GNO's fork2(2) to be of use. 5. Prototype _everything_ and compile with the occ -w flag or #pragma lint -1. This is a biggie. If you have not done so, this may require prototyping your standard header files. It's a lot of work but well worth it. Document your changes to the standard header files for future reference. Make sure you get the prototyping of those files _right_. 6. [v2.0.3] Look for all instances of "unsigned" (by itself) and change them to "unsigned int". 7. [v2.0.3] Check for declarations of static structs. Comment-out the "static" keyword. Hopefully this doesn't break your code. 8. [v2.0.3] Check for multiple struct assignments and make them single ones. For example struct sd a, b; a = b = { "this", "that", NULL }; becomes struct sd a, b; b = { "this", "that", NULL }; a = b; 9. [v2.0.3] Find all instances of the ()?: construct and ensure that 0 (instead of NULL) is not being assigned to a pointer. This will crash your machine, hard, at run or exit time. 10. Ensure that calls to open(2) with the O_CREAT bit set have three args. Failure to do so can result in stack trashing. 12. Check chmod(2) and creat(2) calls for permission bits; GNO's semantics is different from Unix. Also watch for use of the st_mode field in stat(2) calls. 13. Check for open(2) calls on expected devices. Be suspicious of any device name starting with "/dev/". 14. When using open/read/write/close instead of the stdio counterparts, watch for use of absolute numbers for file descriptors, typically the numbers 0, 1, and 2. These should be changed to the macros STDIN_FILENO, STDOUT_FILENO, and STDERR_FILENO. 15. Also when using read/write system calls, watch for assumptions that the newline character is '\n'; under GNO it's '\r'. * * Now we finally get around to compiling the program: * 16. Except as noted below, use the occ flags -w and -G25. If you call "cmpl" directly instead of through occ, this means #pragma lint -1 #pragma debug 25 18. For source files that contain fork(2), fork2(2), or definitions (not declarations or use) of variable argument functions, use -O8 and no -g or -G flag (in addition to -w). This translates to: #pragma lint -1 #pragma debug 0 #pragma optimize 8 When you are done debugging your program, you can increase the optimization level. Just don't decrease it. * * Debugging your program * * This is a personal topic; everybody has his own method of doing it, * and I offer no explicit methodology. Here are some pointers, though * (no pun intended). * 19. Don't try using Splat! on a program that does a fork(2) or fork2(2) system call. *crash* 20. If you're using Splat! on a program that changes it's current working directory, feed your source files through splatprep(1), or you won't be able to see the code you're executing. This util can also help with Splat! showing lines off-by-one when stepping code. The latter is a problem with Orca/C v2.0.3, not Splat!. * * Documentation * #define SOAPBOX 21. Write a man page! It should be in nroff or aroff source. I discourage shipping just a preformatted manual page because they lose their good look once you are using a terminal thats not 24x80 in dimension. If you have too much documentation for a man page, make a marginal man page to point the user to the full manual. 22. Write a describe(1) database entry for your program. Try to use the ".desc" suffix for the file name. Include it in your source and update the online database (which can be found at "http://webzone1.co.uk/www/thesonkpage/describe.htr"). 23. Give the program an rVersion resource fork. If you don't want to write a rez source file, then use setvers(1). Feel free to copy and modify a rez source file from any of my distributions. 24. For shell programs (type exe), make an invocation with the -V flag give version information and the -h flag give help information (if possible). 25. Legalities. Tell people what the distribution limitations are. Give proper attributions. This may include Byteworks, Procyon, UCB, GNU, etc. 26. Tell people how to contact you for bug reports. #undef SOAPBOX