gnu/lib/libg++/README.gnu

   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