home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / bsd_srcs / lib / libg++ / README.gnu < prev    next >
Encoding:
Text File  |  1991-02-18  |  11.0 KB  |  270 lines
  1. This is version 1.39.0 of libg++, the GNU C++ class library.
  2. Release date Tue Feb 19 06:43:04 1991  Doug Lea  (dl at g.oswego.edu)
  3.  
  4. * Please skim through this once BEFORE attempting to make and install libg++.
  5.  
  6. * Contents
  7.  
  8.     * g++ source files are in the ./src directory
  9.     * Some simple tests and demo programs are in ./tests
  10.     * Header files are in ./g++-include
  11.     * documentation is in ./libg++.texinfo. 
  12.     * Some miscellaneous files of possible interest are in ./etc
  13.       (These files are not officially a part of the libg++ distribution,
  14.       and are subject to arbitrary changes, deletions, etc. from release
  15.       to release.)
  16.  
  17. * Pre-installation
  18.  
  19.     * Install a version of g++ with at least as high a version
  20.       number as this version of libg++. You also need gcc installed.
  21.  
  22.     * If there is a version of the GNU as (gas) assembler that
  23.       works on your machine, get it, and install it as gcc-as,
  24.       in whatever lib directory holds gcc-cc1plus. Otherwise,
  25.       you may have to remake g++ with -DFASCIST_ASSEMBLER in CFLAGS,
  26.       and disable the -PIPE_AS flag in the libg++ Makefile.
  27.  
  28.     * With only trivial modifications (like changing file extensions,
  29.       etc.) everything (perhaps except for some demos in ./etc)
  30.       should compile and run with any 2.0 C++ compiler. Please tell me
  31.       if this is not so.
  32.  
  33. * Installation (see libg++.texinfo more more details)
  34.  
  35.     * For VMS, cd to ./vms, and read AAAREADME.TXT
  36.  
  37.     * Except for how to set the `PWD' make variable (which you must
  38.       manually change if you do not use GNU make), the Makefiles
  39.       are reported to be compatible with all flavors of `make'.
  40.  
  41.     * Check the declared indicated pathnames, etc. in the top-level Makefile
  42.  
  43.         Be sure to use USG-oriented switches if you run SystemV unix.
  44.  
  45.         If you run into problems, check through system-dependent
  46.         #defines in  g++-include/stdio.h,  g++-include/math.h
  47.         and g++-include/values.h, especially, and report any
  48.         incompatibilities or problems to bug-lib-g++@prep.ai.mit.edu.
  49.  
  50.     * Choose functionality flags.
  51.  
  52.         In the libg++ Makefile, `XTRAFLAGS' are selectable. By default,
  53.         none of these are enabled:
  54.  
  55.         -DEFAULT_filebuf, if included in XTRAFLAGS, causes standard
  56.          cin, cout, and cerr streams to bypass your libc stdio facilities.
  57.          I know of no system for which this is absolutely required. However,
  58.          if there are known bugs with your stdio implementation, or if
  59.          you wish to give up some functionality in order to be conservative,
  60.          then select this. If you use this, expect an innocuous difference
  61.          between the expected and obtained results of tFile in how the
  62.          final status of standard streams is printed.
  63.  
  64.         -DNO_GNULIB3 suppresses compilation of a dummy `main',
  65.          which calls global constructors and destructors around a
  66.          user main. Select this if you have made alternative arrangements
  67.          for doing this.
  68.  
  69.         -DCOFF_ENCAPSULATE is required for systems in which all
  70.          executables use GNU COFF encapsulation.
  71.  
  72.         -DNO_LINE_BUFFER_STREAMBUF suppresses line-buffering (automatic
  73.          flushing of output whenever a newline is encountered). Selecting
  74.          this may result in slightly smaller code, but will require
  75.          manual flushing when lines are expected to be printed right
  76.          when they are written.
  77.  
  78.         -DUSE_LIBGXX_INLINES forces inlines to be compiled even if
  79.          not compiling with optimization turned on. This is
  80.          required when compiling src files only if -O does not work 
  81.          for you.
  82.  
  83.         -DNO_LIBGXX_MALLOC suppresses compilation of libg++ malloc
  84.          routines, thus causing all malloc, free, realloc, operator
  85.          new() and operator delete() calls to go through your libc
  86.          version of malloc. Select this if your system requires a
  87.          the system version of malloc (possibly necessary on some
  88.          shared memory multiprocessors, since libg++ malloc does not
  89.          contain any concurrency control), or, perhaps, if your applications
  90.          are specially tuned for or otherwise work better with your
  91.          system malloc.
  92.  
  93.         -DMALLOC_STATS compiles statistics counting into libg++ malloc
  94.          (but also slows it down a little). Select this if you are
  95.          interested in examining the performance of libg++ malloc.
  96.          (I welcome this, and would be grateful to receive statistics
  97.          (printed via `malloc_stats()') for programs with heavy
  98.          dynamic allocation requirements.)
  99.  
  100.     * Other compilation flags are tunable, but the default versions
  101.         should normally suffice.
  102.  
  103.     * type `make all', or, step-by-step:
  104.  
  105.        `make src'          -- to compile libg++.a
  106.        `make tests'        -- to make some tests/demos of libg++.
  107.                               This will first compile tests, then run them,
  108.                               then diff the results against expected
  109.                               results. 
  110.        `make etc'          -- (optional) to compile various other things 
  111.  
  112.        `make run_etc'      -- (optional) to run tests on some of the
  113.                                 things compiled in etc.
  114.                             
  115.        `make gperf'        -- (optional) to compile Doug Schmidt's
  116.                                perfect hash function generator. 
  117.  
  118.     * Type `make install'  to install 
  119.  
  120.         libg++.a          (from src)
  121.         include files     (from g++-include)
  122.         prototype files   (from g++-include/gen)
  123.         etags             (from etc)
  124.         g++dep            (from etc)
  125.  
  126.         You may also want to install etc/c++-mode.el in your
  127.         emacs/lisp directory, probably in byte-compiled form.
  128.  
  129.     * Install the documentation
  130.  
  131.     If you are a systems administrator installing libg++ for others,
  132.     please make the documentation available to users!
  133.  
  134.     The libg++.texinfo file may be formatted as a paper document by
  135.  
  136.         * Get a copy of texinfo.tex. 
  137.             This file defines various tex macros used in libg++.texinfo
  138.             One is in the gcc release.
  139.             You can temporarily copy it into the current directory.
  140.         * Run tex on libg++.texinfo
  141.              and do whatever you normally do from there to print it.
  142.  
  143.     It may be made into an emacs info file by
  144.  
  145.         * Inside emacs, run M-x texinfo-format-buffer on libg++.texinfo.
  146.         * Save the resulting files:
  147.             libg++
  148.             libg++-1
  149.             libg++-2
  150.             ...
  151.  
  152.         * Copy these files into your emacs info directory
  153.             (normally somewhere like /usr/gnu/emacs/info).
  154.         * If you have not done so before, edit the emacs/info/dir file
  155.             to add a libg++ node, by inserting a line like
  156.         
  157.             * Libg++: (libg++).    The GNU C++ Library
  158.  
  159.             to the bottom of the file.
  160.  
  161.     * (Optional) Install, from ./etc
  162.         etags (version of etags that understands c++)
  163.         g++dep (a version of mkdep that understands c++)
  164.         c++-mode.el (a c++-mode for GNU emacs)
  165.  
  166. * General compilation notes
  167.  
  168. By default, everything is compiled with the g++/gcc -Wall flag
  169. enabled. This causes g++ to produce numerous diagnostic warnings and
  170. reminders. This is perfectly normal. Only true error messages, which
  171. cause the `makes' to halt indicate real problems. If you do not like
  172. to look at the warnings, disable the -Wall in the Makefile. -Wall is
  173. enabled because, if there are true errors, warnings leading up to
  174. them may prove helpful.
  175.  
  176. * Notes on compiling and running libg++/tests
  177.  
  178. tCurses is not automatically run through `checktests'.
  179. You must run it manually:
  180.  
  181. tCurses attempts to place one of each curses library primitive (boxes,
  182. strings, numbers...) on your screen, and asks for some input, to test
  183. curses input routines. Since there is no way to describe the output
  184. in a system- and terminal- independent way, you will have to be the 
  185. judge of whether it works acceptably.
  186.  
  187. tCurses (and the curses-based classes generally) may fail on the
  188. Sequent and perhaps other systems with unusual or old curses library
  189. implementations if you do not end input with a <linefeed> instead of
  190. the normal <carriage-return>.
  191.  
  192. It is a very good idea to also cd to the test directory and run tests
  193. manually, to see what they do. 
  194.  
  195. Compiling and running the tests consumes a fair amount of time and
  196. disk space!
  197.  
  198. Some reported diffs may be perfectly reasonable, owing to things like
  199. floating point precision differences: The expected.out file was created
  200. on a Sun4/110.
  201.  
  202.     Some tRational and tFix results depend on floating point precision
  203.     and may generate slightly different output on different machines.
  204.  
  205.     tRandom seeds some random-numbers in a way that also relies on
  206.     floating-point representations -- Your output should be numerically
  207.     similar, but probably not identical.
  208.  
  209. * changes from libg++-1.37.0
  210.  
  211.     * All files use the new g++ #pragma interface / #pragma implementation
  212.       convention, which minimies duplication of `outlined' inlines
  213.       and vtables. This also causes no inlines to be used at
  214.       all when not compiling with `-O', which speeds compilation
  215.       and simplifies debugging.
  216.  
  217.     * Many .h header file names had to be shortened so as to simulaneously
  218.       work with SYSV and with #pragma interface (since .h and .cc file
  219.       base names must match.) Sorry!
  220.  
  221.     * All genclass-able files have been moved to g++-include/gen.
  222.  
  223.     * various and sundry bug fixes, minor enhancements, and/or portability 
  224.         improvements as described in the ChangeLog. 
  225.  
  226. * Known bugs and problems
  227.  
  228.     * Support for the DecStation3100 and other MIPS-based machines is 
  229.         still uncertain.
  230.  
  231.     * The file etc/HINTS is an emacs RMAIL file that contains recent
  232.         bug-lib-g++ list mail and related messages that may be useful.
  233.  
  234. * Lots of other information is in the libg++.texinfo file. It really is
  235.   very important to actually read the documentation before using 
  236.   library classes. Examination of the demo files in the test directory
  237.   may also be useful. (Note however, that the demo files are merely
  238.   designed to test examples of each class capability,
  239.   and are not especially good examples of client functions that might
  240.   use these classes.)
  241.  
  242. * There is now a gnu libg++ mailing list (bug-lib-g++@prep.ai.mit.edu) and
  243.     associated usenet gnu news group.
  244.  
  245. * You will be performing a valuable service if you use libg++
  246.    classes and report back any comments, and suggestions, or bugs,
  247.    preferably to the bug-lib-g++ list. Your feedback is extremely 
  248.    helpful in efforts to make libg++ as useful and reliable as possible.
  249.  
  250. * See file `etc/release.log' for changes from previous versions
  251.  
  252.  
  253. * I continue to solicit
  254.  
  255.   * bug reports.
  256.   * suggestions.
  257.   * comments.
  258.   * questions about installing and using libg++
  259.   * other contributions to be incorporated into libg++.
  260.   * sample programs using libg++.
  261.  
  262.   Often, the best place to send such things is bug-lib-g++@prep.ai.mit.edu,
  263.   although direct mail to me is also welcome.
  264.  
  265. * Good luck!
  266.  
  267. Doug Lea, Computer Science Dept., SUNY Oswego, Oswego, NY, 13126 (315)341-2367
  268. email: dl@g.oswego.edu            or dl@cat.syr.edu
  269. UUCP :...cornell!devvax!oswego!dl or ...rutgers!sunybcs!oswego!dl
  270.