home *** CD-ROM | disk | FTP | other *** search
/ Sams Teach Yourself C in 21 Days (6th Edition) / STYC216E.ISO / mac / DJGPP / v2 / readme.1st < prev   
Text File  |  2001-01-25  |  20KB  |  507 lines
  1.  
  2.                ######         #   #####   ######   ######
  3.                #     #        #  #     #  #     #  #     #
  4.                #     #        #  #        #     #  #     #
  5.                #     #        #  #  ####  ######   ######
  6.                #     #  #     #  #     #  #        #
  7.                #     #  #     #  #     #  #        #
  8.                ######    #####    #####   #        #
  9.  
  10.                               DJ Delorie
  11.  
  12.  
  13.           This is the README.1ST file for DJGPP Version 2.03
  14.  
  15. ************************************************************************
  16. *  This file contains information on obtaining, installing, and using  *
  17. *  DJGPP.  Please read it *completely* before asking for help.         *
  18. ************************************************************************
  19.  
  20. DJGPP is a non-proprietary environment for developing 32-bit protected
  21. mode software in C/C++ under MS-DOS.  The DJGPP home page on the WWW
  22. is:
  23.     http://www.delorie.com/djgpp/
  24.  
  25. Status and other information (online docs, FAQ, mail archives) are
  26. made available through the DJGPP web pages.  Discussion of DJGPP and
  27. questions about its usage or features are through the djgpp news group
  28. (post to comp.os.msdos.djgpp) and djgpp mailing list (send your
  29. messages to <djgpp@delorie.com>, subscribe through
  30. <listserv@delorie.com>).  Look on the web page for information on the
  31. latest versions of various DJGPP packages.
  32.  
  33. Version information is in manifest/*.ver within each zip.  Contents
  34. are in manifest/*.mft in each zip.
  35.  
  36. There are also alternate (and usually better) tutorials on getting,
  37. setting up, and using djgpp available on the World Wide Web:
  38.  
  39.     http://www.delorie.com/djgpp/doc/
  40.  
  41.  
  42.  
  43. THE DISTRIBUTION
  44. ****************
  45.  
  46. The DJGPP distribution is broken into a few subdirectories, by
  47. content.  Each subdirectory has a file called 00_index.txt that
  48. contains descriptions of each of the files in that directory.
  49.  
  50. The 'b' zips include the binaries and on-line documentation.  At the
  51. time of writing this file, the various packages are:
  52.  
  53. FAQ      A short file which points you to other documents you should
  54.            read (including the full FAQ list).
  55.  
  56. v2/
  57. unzip32  A free program to unzip the archive (like PKUNZIP) 
  58. djdev203 DJGPP V2 Development Kit and Runtime
  59. djlsr203 DJGPP V2 Base Library Sources
  60. djtst203 DJGPP V2 Test Programs (for testing the C library)
  61. djcrx203 DJGPP V2 Cross-to-DOS Compiler Support Files (from djlsr/djdev)
  62. djtzn203 DJGPP V2 Timezone Files
  63. djtzs203 DJGPP V2 Timezone Sources
  64. faq*b    The full FAQ list in various formats (Info, ASCII, HTML...)
  65. faq*s    The Texinfo sources of the FAQ and tools to generate all the
  66.           different formats of the FAQ
  67. frfaq*   DJGPP FAQ en Francais
  68.  
  69. v2apps/
  70. (various applications built with/for DJGPP, like RHIDE and TeX)
  71.  
  72. v2gnu/
  73. (ports of various FSF/GNU programs to DJGPP, like gcc and binutils)
  74.  
  75. v2tk/
  76. (various toolkits for use with DJGPP, like Allegro and libsocket)
  77.  
  78. v2misc/
  79. csdpmi* CWSDPMI, Charles Sandmann's free DPMI server binaries and docs
  80. mlp*    ML's Executable File Packer Binaries ("djp")
  81. pmode*  PMODE stub for djgpp V2
  82. wmemu*  WM's alternative 387 emulator binaries for DJGPP V2
  83. (and other miscellaneous things to use with DJGPP)
  84.  
  85.  
  86.  
  87. GETTING STARTED
  88. ***************
  89.  
  90. The info below is the minimum new users should know to get them up and
  91. running with DJGPP.  Please read the DJGPP documentation and the FAQ
  92. list for further details.  New users are encouraged to read the FAQ
  93. list in its entirety.
  94.  
  95.  
  96.  
  97. What to download
  98. ----------------
  99.  
  100. See http://www.delorie.com/djgpp/zip-picker.html for a form-based
  101. guide to what to download.  In general, download the binary
  102. distributions only; most people don't need the source distributions.
  103.  
  104. To build C programs, you'll need djdev203.zip, gcc*b.zip, and
  105. bnu*b.zip.  For C++, also get gpp*b.zip.
  106.  
  107. To read the online manuals, get txi*b.zip and run "info".  If you don't
  108. have a DPMI server installed, you'll need csdpmi*b.zip.  (Windows, QDPMI,
  109. 386Max, NWDOS, OpenDOS, OS/2, Win/NT and Linux DOSEmu all provide DPMI
  110. services, so you don't need CWSDPMI in those environments.)  For more
  111. details, download faq*b.zip (the full FAQ list) and read Chapter 4,
  112. "Where and What to Download".
  113.  
  114.  
  115. Installation
  116. ------------
  117.  
  118. 1. Create a directory for DJGPP, say C:\DJGPP.  (WARNING: do NOT
  119.    install DJGPP in a directory C:\DEV, D:\DEV, etc., or in any of their
  120.    subdirectories: it will not work!  See the FAQ for more details.)
  121.  
  122.    If you have version 1.x installed, it's best to delete the contents
  123.    of its `bin/' subdirectory or move it to another directory (not on
  124.    your PATH), and delete everything else from that installation.
  125.    (Some of the problems reported by users of DJGPP v2 were caused by
  126.    inadvertently mixing it with old v1.x programs.)  The only program
  127.    from v1.x that you should keep is `go32.exe'.
  128.  
  129. 2. Unzip all the zip files from that directory, preserving the
  130.    directory structure.  For example:
  131.  
  132.     pkunzip -d djdev203
  133.   or
  134.     unzip32 djdev203
  135.  
  136.    On Windows 9X, use an unzip program which supports long file names.
  137.    Latest versions of InfoZip's UnZip and PKUnZip, as well as WinZip,
  138.    all support long file names.  unzip32.exe, available from the DJGPP
  139.    sites, also supports long file names.  One way to make sure you have
  140.    preserved long file names is to look for a file include/sys/sysmacros.h:
  141.    if you see only sysmacro.h instead, your unzip program does NOT
  142.    support long filenames, and you need to find another one.
  143.  
  144. 3. After unzipping all the zip files, set the DJGPP environment
  145.    variable to point to the file DJGPP.ENV in the main DJGPP
  146.    installation directory and add its BIN subdirectory to your PATH.
  147.  
  148.    The exact way how these variables should be set depends on your
  149.    operating system:
  150.  
  151.    * For Windows 98 systems:
  152.  
  153.      - Click START;
  154.      - Choose Programs->Accessories->System Tools->System Information;
  155.      - Click Tools in the menu-bar, then choose "System Configuration";
  156.      - Use the tab provided there for editing your AUTOEXEC.BAT as
  157.        explained below.
  158.  
  159.    * For Windows NT systems:
  160.  
  161.      - Right-click "My Computer", then select "Properties";
  162.      - Click the "Environment" tab;
  163.      - Edit the PATH system variable to add the DJGPP bin subdirectory;
  164.      - Add a new variable DJGPP and set its value to the full path
  165.        name of the DJGPP.ENV file as explained below.
  166.  
  167.    * For all other systems (DOS, Windows 3.X and Windows 95): use any
  168.      text editor, e.g. the standard EDIT, to edit the file
  169.      AUTOEXEC.BAT in the root directory of the boot drive (usually,
  170.      C:).
  171.  
  172.    No matter which method you use, assuming your DJGPP installation is
  173.    rooted at C:\DJGPP, the values of the two environment variables
  174.    DJGPP and PATH should be set like this:
  175.  
  176.     set DJGPP=C:\DJGPP\DJGPP.ENV
  177.     set PATH=C:\DJGPP\BIN;%PATH%
  178.  
  179. 4. Reboot.  This makes sure the two lines you added to autoexec.bat
  180.    will take effect.  (On Windows NT and Windows 2000, the changes
  181.    take effect immediately, so you don't need to reboot there, but
  182.    you do have to close and reopen the DOS box windows.)
  183.  
  184. 5. Run the go32-v2.exe program without arguments:
  185.  
  186.     go32-v2
  187.  
  188.    It should report how much DPMI memory and swap space can DJGPP use
  189.    on your system, like this:
  190.  
  191.     DPMI memory available: 8020 Kb
  192.     DPMI swap space available: 39413 Kb
  193.  
  194.    The actual numbers will vary according to amount of RAM installed
  195.    on your system, the available disk space and the DPMI server.  If
  196.    the sum of the two numbers reported by go32-v2 is less than 4MB,
  197.    read section 3.9 of the FAQ, "How to configure your system for
  198.    DJGPP".  (If you have more than that, but want to get the optimal
  199.    performance from your system, read that section anyway.)
  200.  
  201.  
  202. Compilation
  203. -----------
  204.  
  205. GCC is a command-line compiler which you invoke from the DOS command
  206. line.  To compile and link a single-file C program, use a command like
  207. this:
  208.  
  209.     gcc myfile.c -o myfile.exe -lm
  210.  
  211. The -lm links in the lib/libm.a library (trig math) if needed.  (Link
  212. order is significant, so if you need libm.a, always put `-lm' at the
  213. end of the command line.)
  214.  
  215. To compile a C or C++ source file into an object file, use this
  216. command line:
  217.  
  218.     gcc -c -Wall myfile.c  (for C source)
  219.   or
  220.     gcc -c -Wall myfile.cc (for C++ source)
  221.  
  222. This produces the object file myfile.o.  The `-Wall' switch turns on
  223. many useful warning messages which are especially beneficial for new
  224. users of GCC.  (Other C++ extensions, like .cpp, are also supported,
  225. see section 8.4 of the FAQ, "How does GCC recognize the source
  226. language", for details.)
  227.  
  228. To link several C object files into an executable program, use a
  229. command line such as this:
  230.  
  231.     gcc -o myprog.exe mymain.o mysub1.o mysub2.o
  232.  
  233. This produces `myprog.exe' which can be run from the DOS prompt.
  234.  
  235. To link a C++ program, use gxx instead of gcc, like this:
  236.  
  237.     gxx -o myprog.exe mymain.o mysub1.o mysub2.o
  238.  
  239. This will automatically search the C++ libraries, so you won't need to
  240. mention them on the command line.
  241.  
  242. You can also combine the compilation and link steps, like this:
  243.  
  244.     gcc -Wall -o myprog.exe mymain.c mysub1.c mysub2.c
  245.  
  246. Further info about the plethora of GCC switches can be found in the
  247. GCC on-line documentation.  To begin reading it, install the Texinfo
  248. package (txi*b.zip, see the ``On-line docs'' section below) and type
  249. this:
  250.  
  251.     info gcc invoking
  252.  
  253.  
  254.  
  255. Development environment (aka IDE)
  256. ---------------------------------
  257.  
  258. Currently, DJGPP doesn't come with an integrated environment of its
  259. own.  You are free to choose any editor that can launch DOS programs
  260. and catch their output, to act as an IDE.  Many people who work with
  261. DJGPP use a DOS port of GNU Emacs (it's available in the v2gnu
  262. subdirectory) which can be compiled with DJGPP.  Emacs is a very
  263. powerful editor (for example, it has a built-in Info reader, so you
  264. can read DJGPP documentation without leaving the editor), but many
  265. other free editors can serve as an IDE.  The only task that these
  266. editors (including Emacs) cannot do is to run a debugger in a
  267. full-screen session.
  268.  
  269. A DJGPP-specific IDE called RHIDE has recently been released and is
  270. now available to all DJGPP users.  It features a Turbo C-style
  271. interface, auto-indentation, color syntax highlighting, automatic
  272. invocation of the DJGPP compiler, automatic Makefile generation, and
  273. easy access to the DJGPP online documentation.  RHIDE also
  274. incorporates integrated and/or standalone debugging using the same
  275. functionality as the GNU Debugger (gdb).  Since RHIDE is brand new,
  276. there are still revisions and bugfixes being made; visit
  277. http://www.tu-chemnitz.de/~sho/rho/rhide.html for the latest
  278. information and updates.
  279.  
  280.  
  281.  
  282. Debugging
  283. ---------
  284.  
  285. To debug a program, you must first compile its source files with the
  286. `-g'switch:
  287.  
  288.     gcc -c -Wall -g mymain.c
  289.     gcc -c -Wall -g mysub1.c
  290.     gcc -c -Wall -g mysub2.c
  291.  
  292. and then link with `-g' as well:
  293.  
  294.     gcc -g -o myprog.exe mymain.o mysub1.o mysub2.o
  295.  
  296. (Note that beginning with v2.01 of DJGPP, it is no longer necessary to
  297. compile to a raw COFF output by omitting the `.exe' from the filename
  298. in order to debug programs.  The debuggers distributed with v2.01 and
  299. later are capable of reading an executable as well as the raw COFF.
  300. If you don't understand what this means, don't worry about it.)
  301.  
  302. Then run your program under the debugger:
  303.  
  304.     fsdb myprog.exe
  305. or
  306.     gdb myprog.exe
  307. or
  308.     edebug32 myprog.exe
  309.  
  310. (You will have to get gdb*b.zip if you want to debug with GDB.)
  311. FSDB has a help screen; press F1 to read it.  GDB comes with Info
  312. docs (see below) which can be read with info.exe.  Edebug32 is a
  313. seldom-used alternative debugger; type 'h' to get help.
  314.  
  315.  
  316.  
  317. On-line docs
  318. ------------
  319.  
  320. Most of the on-line documentation is organized in a special hypertext
  321. format used by the GNU project.  Each package comes with its own docs,
  322. in files with the .iNN extension which are unzipped into the info/
  323. subdirectory of your main DJGPP installation directory.  To browse
  324. these docs, get and unzip the file txi*b.zip, then run info.exe.  If
  325. you don't know how to use Info, read the next section.
  326.  
  327.  
  328.  
  329. Reading the documentation, or A Crash Course in Info
  330. ----------------------------------------------------
  331.  
  332. The following is not supposed to be a complete guide to using Info,
  333. but just a starting point, so you could move around the docs and
  334. search it efficiently for specific subjects.
  335.  
  336. To invoke Info to read a manual, type "info" followed by the manual
  337. name.  For example:
  338.  
  339.   - type "info libc" to read the C library docs;
  340.   - type "info libc alphabetical printf" to read the documentation
  341.     of library function `printf';
  342.   - type "info gcc" to read the manual for GCC, the GNU C compiler;
  343.   - type "info faq" to read the DJGPP FAQ list;
  344.   - type "info make" to read the manual for the Make utility;
  345.   - type "info" to get a menu of all the manuals.
  346.  
  347. To exit Info, press `q' (for Quit).
  348.  
  349. Once inside Info, you can move around with the usual cursor motion
  350. keys: Up-arrow, Down-arrow, PageDown, PageUp, etc.  
  351.  
  352. To read the entire manual in an orderly fashion, press SPACE every
  353. time you've completed reading a screenful.  This will take you through
  354. the entire sequence of chapters and sections of a manual.
  355.  
  356. Menus are marked by a line that says "* Menu:".  Each line below the
  357. menu marker that begins with a "* " is a menu item.  To choose a menu
  358. item, position the cursor at the beginning of a line, right under the
  359. asterisk `*', and press [Enter].
  360.  
  361. Hypertext links are marked by "* Note".  To follow the reference,
  362. position the cursor at the asterisk, then press [Enter].  To get back
  363. from the excursion, press `l' (that's a lower-case letter ell, not the
  364. digit one), for "Last".
  365.  
  366. To quickly search for a particular subject in the index of a manual,
  367. press `i' (for Index), type the subject, then press [Enter].  You can
  368. type only part of the subject name and press TAB, to see whether the
  369. index includes any entries that begin with what you typed.  TAB causes
  370. Info to try to complete what you typed using the available index
  371. entries.  If Info beeps at you or flashes the screen colors when you
  372. press TAB, it means that there are no index entries which begin with
  373. what you typed; delete what you have typed (using the BackSpace key)
  374. and try a different name for what you were looking for.  If there are
  375. some index entries that begin with what you typed, Info will complete
  376. it.  If the completed entry looks like what you are looking for, press
  377. [Enter] to go to the section of the manual that discusses it; if not,
  378. press TAB again to see all the possible completions.  If any of the
  379. completions seem right, type enough text to make it unique and press
  380. [Enter].  If none of the completions seem appropriate, delete what you
  381. typed and try a different subject name.
  382.  
  383. For example, suppose you get the infamous message "ld.exe: cannot open
  384. -lstdcxx: No such file or directory" and you want to check what the
  385. FAQ has to say about that.  You start Info ("info faq"), then press
  386. `i' and type "c a n TAB" (without the blanks).  The first TAB just
  387. capitalizes "can" into "Can", so you know there are some index entries
  388. which begin with "Can", and type TAB again.  Now you will see a list
  389. of potential completions.  Alas, none of them seems to be relevant for
  390. this problem, so you use BackSpace to delete "Can" and then type
  391. "-lstd" followed by TAB.  Now Info has only one choice so it completes
  392. your search and this time it's exactly what you are looking for!
  393. Finally, press [Enter] to go to that node and read what the FAQ has to
  394. say about this subject.
  395.  
  396. If you prefer to look up the subject in the index yourself, page
  397. through the top-level menu of the manual until you find a menu entry
  398. that says something like "* Concept Index" or "* Command Index" or
  399. just "* Index", press [Enter] to go to the index, then browse it for
  400. any pertinent entries.  An index is just a huge menu sorted in
  401. alphabetical order, so find an entry you are looking for, position the
  402. cursor at the beginning of its line, and press [Enter] to go to the
  403. relevant section.
  404.  
  405. The library reference doesn't have an index, so search for functions
  406. either in the alphabetical list or in the functional categories.  For
  407. example, library function `mktime' is in the "Time Functions"
  408. category, `random' is in the "Random Number Functions" category, etc.
  409.  
  410. Sometimes the index search won't help you (because the indices cannot
  411. list everything).  In this case, press `s' (for Search), type the text
  412. you want to find, and then press [Enter].  Info will search the entire
  413. manual for this string and position you at the first occurrence.  To
  414. search for the next occurrence, press `s' and [Enter] again: Info will
  415. repeat the search.
  416.  
  417. Finally, if you don't know in what manual to look for some subject,
  418. you can use the "--apropos" switch to cause Info to look for that
  419. subject in the indices of every installed manual.  For example,
  420. suppose you have heard that DJGPP programs support file-name
  421. wildcards, but you don't know in which manual to look for their
  422. description.  The following command will ask Info to print all the
  423. sections in every manual whose indices mention the string "wildcard":
  424.  
  425.     info --apropos=wildcard
  426.  
  427. This will run for a while, and then print lines like these:
  428.  
  429.     "(kb)Features" -- Wildcards
  430.     "(kb)Changes in 2.01" -- wildcards
  431.     "(djgppfaq)Filename globbing" -- Filename wildcards expansion
  432.  
  433. The text inside the quotes is the name of the manual and the section
  434. where the subject "wildcard" is discussed.  To invoke Info in order to
  435. read the first entry above, type this:
  436.  
  437.     info --node="(kb)Features"
  438.  
  439. Info has many more commands and options.  To find out, from the
  440. command line type "info info".  To find out even more, type
  441. "info info-standalone".
  442.  
  443.  
  444.  
  445. Compatibility with V2.00
  446. ------------------------
  447.  
  448. If you are upgrading from version 2.00 of DJGPP, you should completely
  449. reinstall all the packages you need to use.  Because of the different
  450. methods used by versions 2.01 and later to handle long command lines
  451. (and long filenames under Win95), mixing V2.00 programs with those
  452. from later versions can cause very subtle and difficult to debug
  453. problems.  See the FAQ section 16.6 for more information.
  454.  
  455.  
  456.  
  457. Compatibility with V1.x
  458. -----------------------
  459.  
  460. Existing binaries compiled under DJGPP V1.x can be used for
  461. applications for which there is no v2.x version.  V1 programs cannot
  462. run V2 programs (but v2 programs *can* run v1 programs), so don't try,
  463. say, using v1.x Make to run v2.x compiler.
  464.  
  465.  
  466.  
  467.  
  468. --- COPYRIGHT ---
  469.  
  470. DJGPP V2 is Copyright (C) 1989-1999 by DJ Delorie.  Some parts of
  471. libc.a are Copyright (C) Regents of the University of California at
  472. Berkeley.
  473.  
  474. GNU software (gcc, make, libg++, etc) is Copyright by the Free
  475. Software Foundation.
  476.  
  477. DJGPP V2's copyright allows it to be used to produce commercial
  478. applications.  However, if you include code or libraries that are not
  479. part of djgpp (like gnu's libg++) then you must comply with their
  480. copyrights.  See Chapter 19 of the FAQ for more details.
  481.  
  482. There was a discussion a while ago on the DJGPP news group about the
  483. copyright of some of libc's functions.  This copyright required that you
  484. mentioned the "University of California, Berkeley" in your
  485. distribution even if it only consisted of binaries, i.e. a compiled
  486. program.  However, the Berkeley license has been changed in July
  487. 1999, and you don't need to mention their copyright in your
  488. distribution anymore.
  489.  
  490. The functions and files in libc that have the Berkeley copyright are
  491. listed here:
  492.  
  493. from libc/ansi/time/ctime.c: asctime ctime gmtime localtime mktime
  494.     tzset tzsetwall
  495.  
  496. from libc/compat/stdlib/random.c: initstate random setstate srandom
  497.  
  498. ==============================================================================
  499.  
  500.  
  501. Enjoy!
  502.  
  503.  
  504. DJ Delorie
  505. dj@delorie.com
  506. http://www.delorie.com/
  507.