src/mm/boehm-gc/README.QUICK

   1 Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
   2 Copyright (c) 1991-1995 by Xerox Corporation.  All rights reserved.
   3 Copyright (c) 1996-1999 by Silicon Graphics.  All rights reserved.
   4 Copyright (c) 1999-2001 by Hewlett-Packard. All rights reserved.
   5
   6 THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
   7 OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
   8
   9 Permission is hereby granted to use or copy this program
  10 for any purpose,  provided the above notices are retained on all copies.
  11 Permission to modify the code and to distribute modified code is granted,
  12 provided the above notices are retained, and a notice that the code was
  13 modified is included with the above copyright notice.
  14
  15 A few files have other copyright holders. A few of the files needed
  16 to use the GNU-style build procedure come with a modified GPL license
  17 that appears not to significantly restrict use of the collector, though
  18 use of those files for a purpose other than building the collector may
  19 require the resulting code to be covered by the GPL.
  20
  21 For more details and the names of other contributors, see the
  22 doc/README* files and include/gc.h.  This file describes typical use of
  23 the collector on a machine that is already supported.
  24
  25 For the version number, see doc/README or version.h.
  26
  27 INSTALLATION:
  28 Under UN*X, Linux:
  29 Alternative 1 (the old way): type "make test" in this directory.
  30         Link against gc.a.  With the most recent GC distributions
  31         you may have to copy Makefile.direct to Makefile first.
  32
  33 Alternative 2 (the new way): type
  34         "./configure --prefix=<dir>; make; make check; make install".
  35         Link against <dir>/lib/libgc.a or <dir>/lib/libgc.so.
  36         See README.autoconf for details
  37
  38 Under Windows 95, 98, Me, NT, or 2000:
  39 copy the appropriate makefile to MAKEFILE, read it, and type "nmake test".
  40 (Under Windows, this assumes you have Microsoft command-line tools
  41 installed, and suitably configured.)
  42 Read the machine specific README in the doc directory if one exists.
  43
  44 If you need thread support, you will need to follow the special
  45 platform-dependent instructions (win32), or define GC_THREADS
  46 as described in Makefile (Makefile.direct), or possibly use
  47 --enable-threads=posix when running the configure script.
  48
  49 If you wish to use the cord (structured string) library with the stand-alone
  50 Makefile.direct, type "make cords", after copying to "Makefile".
  51 (This requires an ANSI C compiler.  You may
  52 need to redefine CC in the Makefile. The CORD_printf implementation in
  53 cordprnt.c is known to be less than perfectly portable.  The rest of the
  54 package should still work.)
  55
  56 If you wish to use the collector from C++, type "make c++", or use
  57 --enable-cplusplus with the configure script.   With Makefile.direct,
  58 hese add further files to gc.a and to the include subdirectory.  With the
  59 alternat build process,this generates libgccpp.
  60 See cord/cord.h and include/gc_cpp.h.
  61
  62 TYPICAL USE:
  63 Include "gc.h" from the include subdirectory.  Link against the
  64 appropriate library ("gc.a" under UN*X).  Replace calls to malloc
  65 by calls to GC_MALLOC, and calls to realloc by calls to GC_REALLOC.
  66 If the object is known to never contain pointers, use GC_MALLOC_ATOMIC
  67 instead of GC_MALLOC.
  68
  69 Define GC_DEBUG before including gc.h for additional checking.
  70
  71 More documentation on the collector interface can be found at
  72 http://www.hpl.hp.com/personal/Hans_Boehm/gc/gcinterface.html,
  73 in doc/README and other files in the doc directory, and in include/gc.h .
  74
  75 WARNINGS:
  76
  77 Do not store the only pointer to an object in memory allocated
  78 with system malloc, since the collector usually does not scan
  79 memory allocated in this way.
  80
  81 Use with threads may be supported on your system, but requires the
  82 collector to be built with thread support.  See Makefile.  The collector
  83 does not guarantee to scan thread-local storage (e.g. of the kind
  84 accessed with pthread_getspecific()).  The collector does scan
  85 thread stacks though, so generally the best solution is to ensure that
  86 any pointers stored in thread-local storage are also stored on the
  87 thread's stack for the duration of their lifetime.
  88