home *** CD-ROM | disk | FTP | other *** search
- Newsgroups: comp.os.os2.programmer
- Path: sparky!uunet!usc!elroy.jpl.nasa.gov!nntp-server.caltech.edu!brooke
- From: brooke@cco.caltech.edu (Brooke Paul Anderson)
- Subject: Next draft of the GNU C/C++/make/info user's manual
- Message-ID: <1992Jul24.051541.4023@cco.caltech.edu>
- Sender: news@cco.caltech.edu
- Nntp-Posting-Host: kanga
- Organization: California Institute of Technology, Pasadena
- Date: Fri, 24 Jul 1992 05:15:41 GMT
- Lines: 555
-
-
- 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)
-