🚀 go-pugleaf

Howdy, folks.  I've typed up a short document to help people get and
use the GNU C and C++ compilers and debugger for OS/2.  It includes
information on what you need, how to get it, how to install it, how
to get it running, how to compile your first program, how to debug
your first program, and what other information you might need.

This is a first draft, and I would appreciate comments (like "this
is useful" or "this stinks -- don't bother").  I would also like
suggestions for ANSI C reference manuals, C++ books, and OS/2 API
books -- see the document for more details on what I'd like to
include.

My goal in writing this is to produce a little manual so that
even novices can get the GNU package up and running.  This is because
I've found the package to be very nice so far -- I find it works fine
for the type of programming I do, all for FREE!

At any rate, here it is (it's a long post):

--------------------- cut here ------------------------

THE GNU C AND C++ COMPILERS AND DEBUGGERS FOR OS/2

by Brooke P. Anderson, 7/21/92
("BROOKE" on GEnie, "brooke@hope.caltech.edu" on Internet)

TABLE OF CONTENTS

1.  The purpose of this document
2.  What's GNU?
3.  The GNU compilers for OS/2 v2.0
4.  Installing and running the EMX port
5.  Books that help you use it
6.  Conclusions
7.  Addendum ("What's wrong with printf?")

THE PURPOSE OF THIS DOCUMENT

This document describes the free GNU C and C++ compilers and
debuggers for OS/2 v2.0.  It concentrates on the EMX port (for
reasons described below), giving information on what you need,
how to get the package up and running, and how to get more
information.  The EMX port includes a full 32-bit compiler (which
handles both C and C++), a debugger, an assembler, and some other
utilities.  The compiler does support 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.

WHAT'S GNU?

GNU produces a lot of free software for UNIX machines.  The
software is mostly for software development and includes gcc (a C
compiler), gdb (a symbolic debugger), g++ (a C++ compiler), make,
bison (a yacc analogue), and emacs (a text editor).  These
programs are standards in the UNIX community, often preferred
over other products even though they are free.  The compilers,
for example, produce well-optimized code; and emacs is one of the
two most popular editors for UNIX.

Because the GNU software is free, it is often ported to other
operating systems.  Luckily for us OS/2 users, much of the GNU
software has been ported to OS/2 v2.0.  You can get it from the
main anonymous-ftp site for OS/2, ftp-os2.nmsu.edu; and a fair
amount of it is making its way to GEnie.  It probably also exists
to a certain extent on CompuServe and many other on-line
services.

THE GNU COMPILERS FOR OS/2 V2.0

For OS/2 v2.0, there are actually two ports of gcc and g++. 
Eberhard Mattes and Kai Uwe Rommel provide one port -- I will
call it the "EMX port."  (Kai Uwe Rommel ported g++, and Eberhard
Mattes ported gcc and the rest.)  I'm not sure who provides the
other port -- I will call it the "other port" [grin].  Both the
EMX port and the other port contain version 2.1 of gcc.  The
differences are that the EMX port provides gdb while the other
port has no debugger, that the other port uses LINK386 instead of
the GNU linker, and that the other port is much slower (by
roughly a factor of two) for various floating point calculations
compared to the EMX port.  Since the EMX port is faster in
floating point and has a debugger, I will concentrate on it.

INSTALLING AND RUNNING THE EMX PORT

To get the EMX port up and running, you need the files
"gnudev.zip" (which contains gcc, an old port of gdb, libraries,
and some other programs), "emxdev.zip" (which contains necessary
auxiliary programs), "emxgpp.zip" (which contains the files
necessary to run C++, including some new libraries), and
"emxgdb.zip" (which contains the latest port of gdb).  

Technical documentation for gcc and gdb is available in the form
of info files, files specially formatted so that they can be used
like hypertext.  You can read these files with a normal text
editor, but you will notice occasional formatting commands
embedded in the text.  gccinfox.zip contains the info files for
gcc, and gdbinfox.zip contains the info files for gdb. 
gccdoc.zip contains the same information as gccinfox.zip except
all of the info files have been concatenated into one large file
which is more suitable for people using only a normal text
editor.  There is likewise a gdbdoc.zip file.

Source code for gdb, gcc, g++, and the libraries is available,
too.  See the files "readme.doc" and "readme.gpp" described below
for details.  The source code is not necessary for running the
EMX port.

To summarize, you need gccdev.zip, emxdev.zip, emxgdb.zip,
emxgpp.zip, gccdoc.zip (or gccinfox.zip), and gdbdoc.zip (or
gdbinfox.zip).

Note that the above files might be available as ZOO archives
instead of ZIP archives (for example, as "gccdoc.zoo" instead of
"gccdoc.zip").  This 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 EMX archives.

Uncompress the files from the directory in which you want your
EMX directory.  In other words, if you are in the directory
"\programming", the unarchiving process will create the directory
"\programming\emx" and a lot of subdirectories under that.  

IMPORTANT:  Uncompress gnudev.zip and emxdev.zip first, then
uncompress the others.  emxgpp.zip and emxgdb.zip need to be
uncompressed later as they contain some files that overwrite
earlier versions in gnudev.zip and emxdev.zip.  Make sure that
these newer versions are not skipped; make sure you do unarchive
them and replace the older versions.  ZIP will ask you if you
want to overwrite the older files -- you should answer "yes". 
ZOO might automatically skip over the newer files rather than
overwrite the older versions.  If this happens, you have to note
which files ZOO skipped, delete the older versions, and then
unarchive again.  This is a bug in ZOO for OS/2.

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 gcc
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 foward slashes ("/") and not backward
slashes ("\") in the previous three lines.

Finally, go into the emx\lib\misc directory and type "make". 
This updates some libraries.

After you do all of this, reboot your system (so that the changes
to your config.sys take effect).  Now, you are ready to compile
and debug programs.  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.

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 your EMX
port 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 again. 
Type "quit" to quit.  To list a function (myfunc, say) that is
longer than a screenful, type "list myfunc"; then type "list" to
list the next screenful of myfunc.

The full EMX package contains utilities for creating programs
that run under both OS/2 and DOS (it contains a free DOS
extender).  Since I'm thoroughly uninterested in DOS, I won't go
into any more detail on that.

The EMX port 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.

For more detailed information on the EMX port, read the files
"readme.doc", "install.doc", "readme.gpp", "readme.gdb",
"user.doc", and "develop.doc".  These files are in the emx and
emx\doc directories.  For detailed descriptions of gcc (for all
the various compiler switches) and gdb (for all the various
debugging options), see the info files available in gccinfox.zip
and gdbinfox.zip or in gccdoc.zip and gdbdoc.zip (as described
above).

BOOKS THAT HELP YOU USE IT

The EMX package does not come with extensive documentation like
that you would get with, for example, Borland C++.  gccinfox.zip
(and gccdoc.zip) do not contain information on all the usual C
library functions (like printf, calloc, fopen, sin, etc.). 
develop.doc 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.  Nevertheless, since gcc is ANSI C compliant (or at
least close to it) and since g++ 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.  What you want (besides a
description of the C and C++ languages) is a description of
library functions, including a list of the headers you need to
include to use each function.  For example, you want to be able
to look in the book for a description of sin, find the
appropriate page that tells you the prototype is "double
sin(double)", that you need to include the header "math.h", etc.

Here are some suitable books:

Harbison and Steele, C:  A Reference Manual.  This book contains
all the necessary information on library functions.

[Can people give me some more recommendations for books to put
here?]

For those of you developing applications that use the PM or that
use special OS/2 API functions (such as those for semaphores,
threads, pipes, etc.), you will likewise need to get a book that
discusses the various functions available.  

[Again, can people give me some recommendations here?  Is the
Petzold book still good for OS/2 v2.0?]

CONCLUSIONS

I wrote this to help people get started with a free -- yet
powerful -- 32-bit C and C++ compiler and debugger 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.  "BROOKE" is my GEnie
address; "brooke@hope.caltech.edu" is my Internet address.

ADDENDUM

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.