🚀 go-pugleaf

OK, folks, here's the next draft of the manual I'm working on.
I expanded it to describe how to get, install, and use the GNU
C and C++ compiler, the debugger, make, and info (the hypertext
document reader).

I rewrote a lot of it based on suggestions I got.  As always,
I'm open to suggestions.  Also, please take a look at Appendix 3 --
I would like to get some volunteers who'd be willing to mail 
people the whole set of archives even if you don't feel like doing
it unless people are willing to pay you more than shipping and
packaging.

Also, if anyone has the full references for OS/2 programming books
from Van Norstrand-Reinhold, I would be grateful if you would e-mail
me the information.


A long post follows:

======================== cut here ========================


A USER'S MANUAL FOR THE FREE GNU C AND C++ SOFTWARE-DEVELOPMENT
SYSTEM FOR OS/2 V2.0

by Brooke P. Anderson, 7/23/92

Brooke Anderson
1155 E. Del Mar #312
Pasadena, CA  91106
(818) 577-7555
GEnie address:  BROOKE
Internet address:  brooke@hope.caltech.edu

TABLE OF CONTENTS

1.0 Introduction
2.0 How to get it
3.0 How to install it
     3.1 Zoo210e.exe and uz42_16e.zoo
     3.2 Wholeinf.zoo
     3.3 Gnumk362.zoo
     3.4 Gnudev.zoo and emxdev.zoo
     3.5 Emxgdb.zoo and emxgpp.zoo
     3.6 The final steps
4.0 How to use it
     4.1 Using info
     4.2 Using the compiler
     4.3 Using the debugger
     4.4 Using make
5.0 Where to get more information
6.0 Conclusions

Appendix 1:  Optional packages
Appendix 2:  Frequently asked questions
Appendix 3:  Sources of distribution

1.0 INTRODUCTION

This document describes the free GNU C and C++
software-development system for OS/2 v2.0.  It tells you how to
acquire all the necessary software, how to install it, how to
start using it, and where to look for more information.

The GNU software-development system includes a C and C++
compiler, a debugger, an assembler, a make utility (for
automating the compilation of programs made of many source
files), and a hypertext reader (for reading the documentation). 
The compiler generates full 32-bit, optimized code, and it
supports many OS/2 API calls, so you software developers out
there can use it for PM programming, manipulating semaphores,
manipulating threads, using named pipes, etc.  Optional packages
include emacs (a programmer's editor), a package for using IBM's
OS/2 tool kit, and full source code for all the programs and
libraries in the system.

GNU software is originally developed by the Free Software
Foundation, an organization which produces a lot of free software
for UNIX.  After the Free Software Foundation releases the UNIX
versions, people often port them to many other operation systems
(such as OS/2).  Despite the fact that the software is free, the
UNIX community considers it a standard and often prefers it over
other products because of its high quality.  The compilers, for
example, produce well-optimized code; and emacs is one of the two
most popular editors for UNIX.

Sometimes, there is more than one port of a GNU program.  For
OS/2, for example, there are two different ports of the GNU C
compiler.  This document discusses only one of them (the EMX
port) since the EMX port provides faster floating point routines
and since it works with a debugger.

IMPORTANT:  Not all of the archives described in this document
extract correctly onto FAT file systems, file systems which are
still strangled by the egregious 8.3 file-naming convention.  If
you are still using FAT, you will have to work around some
problems.  For example, the wholeinf.zoo archive, described
below, will not extract or operate properly on FAT.  I think
everything else is FAT compatible, but I haven't checked.  I
recommend that you allocate at least part of your file system for
HPFS and thus leave behind another of the many grim limitations
of MS-DOS.  

2.0 HOW TO GET IT

The full software-development system (and the various optional
packages described in Appendix 1) are available from a variety of
sources.  If you have access to Internet, you can get the files
from the main anonymous-ftp site for OS/2, ftp-os2.nmsu.edu. 
Much of them are also available on GEnie, and they might be
available on CompuServe and many other on-line services.  Also,
see Appendix 3 for a list of people who are willing to distribute
the whole system through regular mail.

You need to obtain the files "gnudev.zoo" (which contains the
compiler and some auxiliary programs), "emxdev.zoo" (which
contains more auxiliary programs), "emxgpp.zoo" (which contains
the libraries the compiler needs for C++ programs), "emxgdb.zoo"
(which contains the latest port of the debugger), "gnumk362.zoo"
(which contains make), and "wholeinf.zoo" (which contains the
hypertext reader and all the documentation for the compiler, the
debugger, and make).  See Appendix 1 for a description of what
you need for the optional packages.

The above files might be available as ZIP archives instead of ZOO
archives, but that is not a problem as both zip and zoo are
available free for OS/2.  You can get them from the same place
you get the other archives.  You need the files "zoo210e.exe"
(which contains zoo) and "uz42_16e.zoo" (which contains unzip).

The sizes of the various files are as follows:  zoo210e.exe
(120k), uz42_16e.zoo (84k), gnumk362.zoo (259k), gnudev.zoo
(846k), emxdev.zoo (227k), emxgdb.zoo (251k), emxgpp.zoo (1232k),
and wholeinf.zoo (544k).

On ftp-os2.nmsu.edu, zoo210e.exe and uz42_16e.zoo are in
pub/os2/all/archivers; gnumk362.zoo is in
pub/os2/2.0/programming; and the rest of the files are in
pub/os2/2.0/programming/emx-0.8d.  On GEnie, all the archives are
(or soon will be) in the OS/2 library (library 13) of the IBMPC
round table.

3.0 HOW TO INSTALL IT

The following subsections describe how to install the various
pieces of the GNU C and C++ software-development system.  Go
through the procedures step by step as described -- the order is
important.  Don't feel compelled to read through any of the
readme files or other documentation spit out during the
unarchiving process -- I think you will have a much easier time
if you go through this document beforehand.

3.1 ZOO210E.EXE AND UZ42_16E.ZOO

If you don't already have zoo or unzip, you will need to install
them.  zoo210e.exe is a self-extracting archive.  Simply move it
to a convenient directory and type "zoo210e".  Add the name of
the directory zoo is in to the path variable in your config.sys
file, and reboot.  (On my machine, zoo.exe is in c:\apps\zoo, so
I appended "c:\apps\zoo;" to the "SET PATH" statement in
config.sys.)  Now, to unarchive uz42_16e.zoo, you simply move it
to another convenient directory and type "zoo e uz42_16e".  Add
the name of the directory unzip is in to your path as well, and
again reboot.  Now, you can unarchive any ZOO archive by typing
"zoo e filename", and you can unarchive any ZIP archive by typing
"unzip filename", where "filename.zoo" or "filename.zip" is the
name of the archive.

3.2 WHOLEINF.ZOO

Copy wholeinf.zoo to any convenient directory and unarchive it. 
It will disgorge a program called "info.exe" (the hypertext
reader), several auxiliary files, and a bunch of documentation
files for itself, the compiler, the debugger, and make.

3.3 GNUMK362.ZOO

Copy gnumk362.zoo to any convenient directory and unarchive it. 
The archive will disgorge several files, including two more
archives:  source.zoo and info.zoo.  You can delete info.zoo, as
its contents are duplicated in wholeinf.zoo.  You can keep
source.zoo if you want the source code to make, but it is not
necessary to keep it.

Add the name of the directory make is in to your path statement
in config.sys.  (I have make in c:\apps\make, so I appended
"c:\apps\make;" to the "SET PATH" statement in my config.sys.)

3.4 GNUDEV.ZOO AND EMXDEV.ZOO

These archives create the directory ".\emx" and a bunch of
directories under that.  Thus, unarchive the files from the
directory in which you want this emx directory.  (In other words,
if you unarchive gnudev.zoo in the directory "\compiler", the
process will create \compiler\emx, \compiler\emx\bin,
\compiler\emx\lib, and many other such directories.)

3.5 EMXGDB.ZOO AND EMXGPP.ZOO

As with the above two archives, unarchive emxgdb.zoo and
emxgpp.zoo in the directory on top of the emx directory.  In
other words, if the emx directory is \compiler\emx, move
emxgdp.zoo and emxgpp.zoo to \compiler and unarchive them.

IMPORTANT:  These two archives contain newer versions of some of
the files contained in gnudev.zoo and emxdev.zoo.  If zoo or
unzip ask you if you want to replace existing files (i.e.,
overwrite files already on disk), answer "yes".  Make sure that
you do not skip the unarchiving of any files in emxgdb.zoo and
emxgpp.zoo.

3.6 THE FINAL STEPS

Now, you need to modify your config.sys file.  The examples below
are from my config.sys file, and I have the emx directory
installed under c:\apps.  Thus, my system has the directories
"c:\apps\emx\dll", "c:\apps\emx\lib", "c:\apps\emx\include", and
so on -- you will need to modify the following examples so that
the directories are specified correctly.  

First, you need to specify in your libpath the location of
emx.dll.  In my config.sys, I have

LIBPATH=.;C:\OS2\DLL;C:\OS2\MDOS;C:\;C:\OS2\APPS\DLL;c:\apps\emx\dll;

Second, you need to set a few environmental variables so that the
compiler knows where to find various files:

set C_INCLUDE_PATH=c:/apps/emx/include
set LIBRARY_PATH=c:/apps/emx/lib
set CPLUS_INCLUDE_PATH=C:/apps/emx/include.cpp;C:/apps/emx/include

Note:  you need to use forward slashes ("/") and not backward
slashes ("\") in the previous three lines.

Now, reboot your machine so that these definitions take effect. 
Then go into the emx\lib\misc directory and type "make", and
finally go into the emx\lib\math directory and type "make". 
These last two actions update some libraries, and you must make
sure you rebooted the machine once before executing the make
commands.

This completes the installation process.

4.0 HOW TO USE IT

Now, you are ready to use info (the hypertext reader), to compile
programs, to debug programs, and to use make.  The next
subsections discuss each of these actions in turn.

4.1 USING INFO

Go into the directory in which info.exe resides.  Type "info". 
You are now looking at a screen that has some information on the
top half (information such as "Typing 'd' returns here, 'q'
quits, '?' lists all info commands, 'h' gives a primer for
first-timers . . .") and a list of subjects near the bottom
(subjects such as "Info", "Gcc", "Gdb", "Make", and "Gdbint").  

Go ahead and type "h" for a tutorial.  The most basic functions
to remember are:  type "q" to quit, type "?" to get a list of
commands, hit the space bar or PgDn key to go down a page, press
the Del key or the PgUp key to go up a page, press "n" to go to
the next node (think of a node as being a collection of one or
more pages dealing with a single topic), press "p" to go to the
previous node, use the up and down arrow keys to highlight
choices of new nodes to jump to, and press enter to jump to the
highlighted node.

Just play around with it a little while, and you will get the
hang of it.  Type "d" to get back to the main directory, use the
down arrow to highlight "Gcc", press enter, press the down arrow
to highlight "Contributors", press enter, scan through the pages
of text by hitting the PgDn key a couple of times, type "?" to
see a list of commands, type "p" a couple of times, etc.

There is one bug that I found in this package.  If you use "s" to
search and if you type a phrase that info cannot find, it
crashes.  This is a fairly major bug, so I suspect it will get
fixed sometime soon.

4.2 USING THE COMPILER

To compile a C source file called "myprog.c", type "gcc -o
myprog.exe myprog.c".  The -o switch tells gcc that it should
call the resulting executable "myprog.exe".  To compile the C++
source file "myprog.cc", type "gcc -o myprog.exe myprog.cc
-lgpp".  C++ source files should have the extension ".cc".  The
-lgpp switch tells gcc to link the C++ libraries.  You can also
tell gcc to optimize your code by using the -O switch.  There are
two levels of optimization (-O and -O2, the highest being -O2). 
Thus, for the fastest-executing code (at the expense of time to
compile and of size of the executable), you would type "gcc -O2
-o myprog.exe myprog.c" for myprog.c and "gcc -O2 -o myprog.exe
myprog.cc -lgpp" for myprog.cc.

Note that specifying "-o myprog.exe" is important.  If you don't
specify ".exe" as the suffix of the output file name, the
compiler will generate a UNIX-style executable which will not run
under OS/2 even if you subsequently rename the file so that it
has a .exe extension.

4.3 USING THE DEBUGGER

To debug a program, you need to compile it with the -g switch: 
"gcc -g -o myprog.exe myprog.c" for myprog.c and likewise for
myprog.cc.  After compilation, you then type "gdb myprog.exe" to
start the debugger.  Type "h" at the debugger prompt to get a
list of help topics.  gdb supports all sorts of breakpoints
(including conditional ones), and you can watch variables, set
variables to different values, etc.  For example, to get help on
running programs from within the gdb, you can type "help
running".  That will give you a list of commands such as run,
kill, step, etc.  You can get help on individual commands by
typing, for example, "help step".

The following is a sample compile and debug session.  Go into the
emx\test directory and type "gcc -g -o hello.exe hello.cc -lgpp"
to compile hello.cc.  Type "hello" to run it, to see if the
compiler is functioning.  The program will print "Hello, world!"
on the screen.  Now type "gdb hello.exe" to start gdb.  At the
prompt "(gdb)", type "list main" to list the function "main". 
Then type "break 5" to cause execution to stop at line 5 in the
main function.  Type "run" to start execution -- it will stop at
line 5.  Type "print argc" to see the value of the variable
"argc".  Type "step" to run line 5 then halt execution at the
next line.  Type "quit" to quit.  To list a function (main, say)
that is longer than a screenful, type "list main"; then type
"list" again to list the next screenful of main.

4.4 USING MAKE

Assume you have a program made of the following source files: 
"myprog1.c" and "myprog2.c".  You might manually compile these
files by typing "gcc -o myprog.exe myprog1.c myprog2.c".  Of
course, if you change only one of the files, typing such a
command causes the recompiling of both source files.  During
development, this could be tiresome if the files take a long time
to compile.  A better way would be to type "gcc -c myprog1.c"
which compiles myprog1.c into the object file "myprog1.o" (the -c
switch tells gcc to make an object file), then to type "gcc -c
myprog2.c" to generate myprog2.o, and finally to type "gcc -o
myprog.exe myprog1.o myprog2.o".  This way, if you change only
myprog1.c, you can recompile it and relink it with myprog2.o to
create myprog.exe (skipping the "gcc -c myprog2.c" step).  This
will be much faster if the source files take a long time to
compile (or if you have a lot of source files).

Of course, doing all this typing is tiresome, too.  Also, if
myprog1.c happens to depend on myprog1.h, and you change
myprog1.h, you must recompile myprog1.c.  Thus, you have to keep
track of all the file dependencies in order to know, after
changing one header file, which other files need to be
recompiled.

Fortunately, make takes care of all of this automatically.  All
you have to do is create one text file that describes the various
dependencies and the various steps to compile the program.  You
name the text file "Makefile".  From then on, whenever you type
"make", make examines the Makefile, looks for files which have
changed since the last compile, recompiles any files which depend
on the changed files, and relinks everything into an executable.

For example, suppose that myprog.exe is made from myprog1.c and
myprog2.c, that myprog1.c contains the lines "#include
"myprog1.c"" and "#include "mainhead.h"", and that myprog2.c
includes myprog2.h and mainhead.h.  The Makefile describing all
of this is

myprog.exe: myprog1.o myprog2.o
     gcc -o myprog.exe myprog1.o myprog2.o

myprog1.o: myprog1.c myprog1.h mainhead.h
     gcc -c myprog1.c

myprog2.o: myprog2.c myprog2.h mainhead.h
     gcc -c myprog2.c

The first line shows that myprog.exe depends on myprog1.o and
myprog2.o.  If either of those has changed since the last time
make was invoked, make will relink them to create myprog.exe by
giving the command under the first line.  The fourth line shows
that myprog1.o depends on myprog1.c, myprog1.h, and mainhead.h. 
If any of these three files have changed since the last time make
was run, make will recompile myprog1.o by issuing the command on
line five.  It will also realize that myprog.o has changed, that
myprog.exe depends on myprog.o, and will relink myprog.exe.  If
mainhead.h is changed, make will recompile and relink everything
since myprog1.o needs to be changed, myprog2.o needs to be
changed, and thus myprog.exe needs to be changed.

The example above shows the general form of a Makefile.  You give
a target (like "myprog.exe" or "myprog1.o") followed by a colon,
followed by a space, followed by a space-delimited list of files
the target depends on.  The next line specifies the action to be
taken when any of the dependencies change:  the first character
MUST be a tab (not just a bunch of spaces used for indentation);
then you type the command make should issue.  A Makefile is just
a list of such targets, dependencies, and actions.

5.0 WHERE TO GET MORE INFORMATION

Unfortunately, the GNU C and C++ software-development system does
not come with extensive, easy-to-use documentation like that you
would get with, for example, Borland C++.  The info files (the
ones you see when you use the hypertext reader) do not contain
information on all the usual C library functions (like printf,
calloc, fopen, sin, etc.).  develop.doc (in the emx\doc
directory) does contain a partial list of library functions,
including a list of headers you need to include, what the
functions do, and what parameters they accept -- but it is not
complete.  Moreover, some of the installation instructions are
sketchy (which is why I wrote this document).

Nevertheless, since the C compiler is ANSI C compliant (or at
least close to it) and since the C++ compiler is very close to
AT&T C++ 2.0, you can use just about any ANSI C and AT&T C++ 2.0
reference manuals.  I use the ones I got with an old version of
Borland Turbo C++.  If you don't have such manuals, you should be
able to find something suitable in a bookstore.  

Keep in mind that, even if you already have books on C and C++,
you need an ANSI C language reference manual that contains a
complete list of all the functions available in ANSI C (like
printf, calloc, sin, time, etc.) including descriptions of the
prototypes for the functions (like "double sin(double)" and
"time_t time(time_t *)") and descriptions of which headers you
need to include in order to use the functions (sin requires
math.h and time requires time.h, for example).  I recommend C:  A
Reference Manual, by S. P. Harbison and G. L. Steele, Jr.
(Prentice-Hall, 1991).  This book contains all the necessary
information on library functions.

For those of you developing applications that use the PM or that
use special OS/2 functions, the system DOES support many of the
OS/2 API functions, including ones for semaphores, PM
programming, named pipes, threads, etc.  See develop.doc (in the
emx\doc directory) for a list of the supported functions.  The
documentation does not contain a manual on how to use these API
calls -- you need an OS/2 programming book for that.  [Check out
the new series of books published by Van Norstrand-Reinhold --
the series includes several books on using the API.  I will add
specific titles and authors' names when I find out more
information.  Does anyone have other recommendations for OS/2
programming books?]

Also, way back when you were unarchiving, you might have been
itching to examine the various readme files and other
documentation.  Now is the time to do that to your heart's
content.  Browse through "readme.gpp" and "readme.gdb" (both in
the emx directory); "readme.doc", "install.doc", "user.doc", and
"develop.doc" (all in the emx/doc directory); and the information
available from the hypertext reader.

6.0 CONCLUSIONS

I wrote this to help people get started with a free -- yet
powerful -- 32-bit C and C++ software-development system for
OS/2.  For the price of a couple of books, you have a full C and
C++ programming system.  For the additional price of an OS/2
programming book, you have a bargain-basement SDK.

If you find errors in this document, or if you have suggestions
for its improvement, please let me know.  My GEnie address is
"BROOKE", and my Internet address is "brooke@hope.caltech.edu".

APPENDIX 1:  OPTIONAL PACKAGES

There are a few optional packages you can get for this
software-development system, packages which are not necessary but
which can nevertheless be important.

The first is emacs, the GNU programmer's editor.  As mentioned
earlier, this is one of the two most popular editors for UNIX,
and it is very popular on many other operating systems as well. 
An interesting feature of GNU emacs for OS/2 is that you can use
it to interact both with the info files (the ones used by the
hypertext reader) and with the debugger.  This latter ability
provides fully-interactive debugging, similar to what MicroSoft's
CodeView or Borland's integrated development environment offers. 
To use emacs, you need the files "emacs.doc" and "emacsbin.zoo". 
The source code is available in "emacssrc.zoo" and
"emacspat.zoo".  On ftp-os2.nmsu.edu, these files are available
in pub/os2/2.0/gnu/emacs.

The second is a package that allows you to use IBM's OS/2 tool
kit.  You still have to buy the tool kit from IBM, but it is
probably cheaper than buying their entire software-development
kit.  With this package and IBM's tool kit, you have full use of
all OS/2 API functions.  This package is available in the file
"icc2gcc.zoo".  On ftp-os2.nmsu.edu, this file is available in
pub/os2/2.0/programming/emx-0.8d.

The third package contains full source code to all the programs
and libraries that come with the software-development system. 
The source (and the full collection of auxiliary programs) for
the hypertext reader is in the file "gnuinfo.zoo", available on
ftp-os2.nmsu.edu in the pub/os2/2.0/gnu directory.  The source
for make comes in gnumk362.zoo, and the names of the archives for
all the other sources in the system are given in readme.doc. 
(readme.doc is in the emx\doc directory.)  The latter archives
are available on ftp-os2.nmsu.edu in
pub/os2/2.0/programming/emx-0.8d.

APPENDIX 2:  FREQUENTLY ASKED QUESTIONS

This is such a common question concerning gcc that I figured I
should answer it from the start:  "What's wrong with printf?" 
People find that printf doesn't immediately echo to the screen;
the string is held in a buffer and dumped later, usually long
after the printf statement is executed.  This is not really a bug
-- ANSI C does not specify that printf should flush the I/O
buffer (since it is probably more efficient on mainframe systems
with terminals to flush the I/O buffer only by large chunks at a
time).  So, to get a printf to work like you are probably
accustomed to, put an fflush(stdout) after any printf you want
immediately displayed.

APPENDIX 3:  SOURCES OF DISTRIBUTION

This document already described some places from which you can
get the necessary archives:  ftp-os2.nmsu.edu, GEnie, and perhaps
CompuServe and other on-line servies.  However, some people don't
have access to these sites, don't have modems fast enough to
download MBytes of data in a reasonable amount of time, or can't
afford the charges which they might incur by downloading from
on-line services.  For these people, I am including the following
list of people willing to distribute the whole system through
regular mail.

If you would like to get on this list, just send me your name, a
description of how people can contact you, and how much money you
want for the service (such as "cost of disks and shipping",
"disks + shipping + $30", or whatever you want to charge).  It
would be helpful to have a list of five to ten people so that
people can try another source if they can't contact one of them.

Folks, please consider what price would be sufficient for you to
provide this service.  Even if you don't want to do it unless
someone pays you $30, it might be helpful.  You might feel uneasy
about charging money, but someone who can't get the system any
other way might be VERY glad that you provide the service at all. 

Here's the list so far.  Keep in mind that people might change
their prices, cease distributing the software, move, etc., so
contact them first to find out details.

Brooke Anderson
1155 E. Del Mar #312
Pasadena, CA  91106
(818) 577-7555
GEnie address:  BROOKE
Internet address:  brooke@hope.caltech.edu
Cost:  disks + shipping + $5 (subject to change if I get swamped)