DJGPP QuickSetup Guide

DJGPP is a free yet powerful 32-bit C/C++ development system for Intel
80386+ PC's. It includes ports of many GNU development utilities.

The main site is located at DJ Delorie's Home Page where the most
up-to-date information is available, including announcements, bug reports
and fixes, FAQ lists, an online topic search program, software
contributions, and more.

---------------------------------------------------------------------------

Getting Started

[*** ] If you are new to DJGPP, I suggest that you read more about it first
before downloading the entire package from ftp sites on the Internet.

[* ] First things first, so get the FAQ lists faq102.zip and faq210b.zip,
and read them carefully, especially Sections 1-3, which will help you get
started.

The current versions of DJGPP are v1.12 and v2.01. I highly recommend v2,
as has many advantages over v1, such as better ANSI-compliance, etc.

---------------------------------------------------------------------------

Obtaining the packages and installing them

[*** ] Getting the documentation and reading them is very important. Online
docs for DJGPP are in the txi*.zip package; also, each module has its own
separate manual.

[* ] The two versions of DJGPP have slightly different setups. Click on the
version number to obtain specific information on each setup.

   * v1.12

   * v2.01 (RECOMMENDED)

[* ] All files should be unpacked by 'pkunzip -d file.zip' or 'unzip
file.zip.' Maintenance files have to be installed last and in order: m1,
m2,... After unzipping a maintenance file, you need to run a batch file
that it installs before continuing with the next maintenance file.

[*** ] There is also a minimal DJGPP package described in Section 3.6 of
the FAQ list. The EZ-GCC version is about 5M compressed. Note: This is
DJGPP v1.1x! You REALLY should get v2 as it is much better.

---------------------------------------------------------------------------

Building your first DJGPP program!

For those familiar with gcc, just go right ahead and type 'gcc args...'
Remember, DJGPP is gcc for DOS. For those new to gcc and/or command-line
compilers in general, here's a quick guide to compiling, running,
debugging, and profiling your programs.

   * Compiling and linking

     I use the term compile to describe turning source code into object
     code, linking as putting together object code into an executable
     format, and building as compiling then linking.

     To build (compile and link) your files, just type 'gcc -o output
     input...' A coff binary would be produced using v1.12, and an exe file
     with v2. To run the file in v1.12, just do 'go32 output', or in v2,
     type 'output'. A coff binary produced by v1.12 can be converted to an
     executable file through 'coff2exe hello'.

     [*** ] For v2, make sure you are running under a DPMI server (QDPMI,
     Windows, OS/2, etc.) or CWSDPMI.EXE (from the csdpmi*.zip file) is in
     the current directory or path.

     Some short examples:

        o Compiling a program

          gcc -c input.c

        o Building a program whose source is contained in a single file

          gcc -o output input.c (v1.12)

          gcc -o output.exe input.c (v2)

          To run your executable, type 'go32 output' (v1.12) or
          'output.exe' (v2)

        o Building a program contained in multiple source files

          gcc -o output file1.c file2.c file3.c

          To execute, type 'go32 output' (v1.12) or 'output.exe' (v2)

          Source files could have the extensions '.c', '.cc', '.cpp', '.s',
          etc. See the FAQ list and read the docs for more information on
          how gcc handles each file extension by default.

     Libraries can be linked in using the '-l' switch. You should always
     put them last on the command line. The standard C library (libc.a) is
     linked in automatically so you don't have to specify it for most of
     your programs. If you need to link in multiple libraries, just
     remember that the correct order has to be '-lall_other_libs_first
     -lgpp -lm -lpc'.

     So for most of your programs, you do not have to specify a '-llib'
     parameter at all. If you want to link in the GNU C++ library, use
     '-lgpp'; for the streams subset of the GNU C++ library, use
     '-liostream'; for the standard math functions, use '-lm'; for
     PC-specific functions such as BIOS calls provided by DJGPP, use
     '-lpc'. (Note: '-lpc' is no longer needed in v2)

     Some short examples:

        o Libraries should be specified last on the command line

          gcc -o output input -llib1 -llib2 -llib3...

        o Linking in a standard library

          Suppose you're using C++ iostream code in your hello.cpp program

          gcc -o output input.cpp -liostream

          Look inside the 'djgpp\lib' directory. The file corresponding to
          '-liostream' is 'libiostream.a'. (or 'libiostr.a' because of
          FAT's 8.3 file name format) The standard C library, contained in
          'djgpp\lib\libc.a,' can be explicitly linked in using '-lc'. See
          a pattern? In general, 'libX.a' in 'djgpp\lib' corresponds to
          '-lX' on the command line.

          Please refer to the docs for more information on the various
          standard libraries that come with DJGPP.

          Again, the standard C library is automatically linked in by gcc
          so '-lc' is unnecessary.

        o Linking in multiple libraries

          gcc -o output input.c -lmylib1 -lgpp -lpc

          [*** ] A very important thing to remember is that DJGPP behaves
          unpredictably for different orderings of libraries given on the
          command line. If you are linking in multiple libraries, the
          correct order is '-lall_other_libs -lgpp -lm -lpc'.

     Other options that you might find useful are '-Wall' to report all
     compiler warnings, '-On' where n is the optimization level number,
     '-g' to generate debug information (necessary for debugging), etc.

     Some short examples:

        o Report all warnings

          gcc -Wall -o input input

        o Optimizing the output with O1

          gcc -O1 -o output input

        o Optimize even more with O2

          gcc -O2 -o output input

        o Generate debug info inside output

          gcc -g -o output input

        o Report all warnings, optimize, and generate debug info

          gcc -Wall -O2 -g -o output input

          In general, there is no proper ordering needed for these options
          on the command line. Just remember that all '-llib' come last,
          and they follow some order among themselves.

        o A sample command line

          gcc -Wall -O2 -g -o hello hello.c myobjfile.o myasmsrc.s
          -lacmelib -lgpp -lm

   * Debugging

     To debug programs in v1.12, type 'go32 -d [debugger-name] [program]
     [args...]'. If you installed the GNU debugger, the debugger-name is
     gdb. There are other debuggers available at the Oak site; also, note
     that there are two versions of each, dpmi and non-dpmi, so use the
     correct one depending on your programming environment. Section 12 of
     the FAQ list explains more on debugging programs.

     To debug programs in v2, type 'gdb [program.out] [args...]'. Make sure
     you built the program with the '-g' switch. [program.out] is not the
     exe but rather the coff image. Read the FAQ list and gdb docs for more
     information on using gdb.

     There's another tool that is very helpful in debugging crashed
     programs (v1.12 or v2) that produce a trace-back on the screen (GPF
     message and register dumps). Make sure the program was built with the
     '-g' switch, and the coff image and source files are in the same dir.
     Then type 'symify [program]' right after the program crashes and it'll
     show the line numbers in the source code where the program crashed.

   * Profiling

     To profile your code (v1.12 or v2), build with the '-pg' switch, run
     your program, then run 'gprof [program.out]'. [program.out] should be
     the coff image, rather than exe. Note that for v1.12, gprof does not
     work under DPMI. Read the FAQ list and gprof docs for more information
     on this.

---------------------------------------------------------------------------

Miscellaneous stuff

If you want to test whether your installation went smoothly, you can get
the djtst*.zip file from the same place you got DJGPP from. Run the batch
file and it will automatically do the compilation, linking, and testing.

People ask about IDE's, too. GNU Emacs has been ported to DOS, you might
want to try that. I've also seen some nice enhanced editors/IDE's, try
Aurora, Multi-Edit, or Boxer editor. I often use DOS Edit, with batch and
make files. =)

There's a neat Borland-like IDE for DJGPP called RHIDE. Get it from
http://www.tu-chemnitz.de/~rho/rhide.html.

Some more little tips: if your first program doesn't seem to want to
compile/link, try doing 'set > myenv.txt' at the prompt, and examine the
myenv.txt file. See if your environment variables are properly set, as
described here.

DJGPP might complain 'Out of virtual memory' in an OS/2 DOS box; it has
happened to me before. Just right click to get to the DOS box properties,
and increase (DPMI) memory OS/2 gives it. Mine is set to 'ENABLED' at 32MB.

Redirecting stdout doesn't work very well under a plain DOS shell. Try
using a smarter shell such as 4DOS. There's also another solution to this
problem using the redir program, search for it in the mail archives.

---------------------------------------------------------------------------

Where to get help on DJGPP

First, read the FAQ list; try to see if what you're looking for is already
there.

There are online docs in DJGPP; they are in the txi*.zip package. If you
installed it, just type 'info' to get into the top help node, or 'info
[topic...]' to go directly to a particular topic. Use the Tab, space-bar,
Return , 'n', 'p', 'u' keys, etc. to navigate between pages and topics.
Press 'q' to quit.

There is also a DJGPP newsgroup on Usenet and a DJGPP mailing list. (I
think mail goes through the newsgroup so you don't need to subsribe to
both.) The newsgroup name is 'comp.os.msdos.djgpp'; to subsribe to the
mailing list, send mail to listserv@delorie.com, with no subject and write
'add [your e-mail address] djgpp' in the body. If you only want
announcements, write 'add [your e-mail address] djgpp-announce.'

Another way to get more information on something is to search the
mail-archives at the Turnbull site or DJ's homepage. I find many useful
articles there.

---------------------------------------------------------------------------

Other DJGPP programs and libraries

   * There are a number of contributed programs in the djgpp dir at Simtel
     sites. Try browsing through the simtelnet. The index file lists all
     the files with their short descriptions.
   * The djgpp2 dir at x2ftp.oulu.fi also contains libs, mostly for
     graphics/game programming. The index file lists all the files with
     their short descriptions.

---------------------------------------------------------------------------
Many thanks to DJ Delorie, Eli Zaretskii, Charles Sandmann and the rest of
the DJGPP team!

10/31/96 icbm on EFNET IRC #c and #gamecode.

Mail me corrections/suggestions/complaints/crap at avly@castle.net

Copyright  1995-96 avly@castle.net All Rights Reserved

All trademarks mentioned are of their respective companies.

Standard Disclaimer

There are absolutely no guarantees, expressed or implied, on anything that
you find in this document. I cannot be held responsible for anything that
results from the use or misuse of this document.
