| 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 |
Copyright (c) 2009-2021 Ivan Maidanski |
| 6 |
|
| 7 |
THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED |
| 8 |
OR IMPLIED. ANY USE IS AT YOUR OWN RISK. |
| 9 |
|
| 10 |
Permission is hereby granted to use or copy this program |
| 11 |
for any purpose, provided the above notices are retained on all copies. |
| 12 |
Permission to modify the code and to distribute modified code is granted, |
| 13 |
provided the above notices are retained, and a notice that the code was |
| 14 |
modified is included with the above copyright notice. |
| 15 |
|
| 16 |
A few files have other copyright holders. A few of the files needed |
| 17 |
to use the GNU-style build procedure come with a modified GPL license |
| 18 |
that appears not to significantly restrict use of the collector, though |
| 19 |
use of those files for a purpose other than building the collector may |
| 20 |
require the resulting code to be covered by the GPL. |
| 21 |
|
| 22 |
For more details and the names of other contributors, see the README.md, |
| 23 |
doc/README.*, AUTHORS and include/gc.h files. These files describe typical |
| 24 |
use of the collector on a machine that is already supported. |
| 25 |
|
| 26 |
For the version number, see README.md or include/gc_version.h files. |
| 27 |
|
| 28 |
INSTALLATION: |
| 29 |
Under UN*X, Linux: |
| 30 |
Alternative 1 (the old way): type "make -f Makefile.direct check". |
| 31 |
Link against gc.a. |
| 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 doc/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 check". |
| 40 |
(Under Windows, this assumes you have Microsoft command-line tools |
| 41 |
installed, and suitably configured.) |
| 42 |
Read the machine specific README.XXX in the doc directory if one exists. |
| 43 |
|
| 44 |
If you need thread support, you should define GC_THREADS as described in |
| 45 |
doc/README.macros (configure defines this implicitly unless --disable-threads |
| 46 |
option is given). |
| 47 |
|
| 48 |
If you wish to use the cord (structured string) library with the stand-alone |
| 49 |
Makefile.direct, type "make -f Makefile.direct cords". (You may need to |
| 50 |
override CC specified in the Makefile. The CORD_printf implementation in |
| 51 |
cordprnt.c is known to be less than perfectly portable. The rest of the |
| 52 |
package should still work.) See include/cord.h for the API. |
| 53 |
|
| 54 |
If you wish to use the collector from C++, type "make c++", or use |
| 55 |
--enable-cplusplus with the configure script. With Makefile.direct, |
| 56 |
"make c++" creates gccpp.a and gctba.a files (you should link with either |
| 57 |
gccpp.a or gctba.a). With the alternate (preferred) build process, this |
| 58 |
generates libgccpp.a and libgctba.a, and/or libgccpp.so and libgctba.so. |
| 59 |
See include/gc_cpp.h and doc/gcinterface.md. |
| 60 |
|
| 61 |
TYPICAL USE: |
| 62 |
Include "gc.h" from the include subdirectory. Link against the |
| 63 |
appropriate library ("gc.a" under UN*X). Replace calls to malloc |
| 64 |
by calls to GC_MALLOC, and calls to realloc by calls to GC_REALLOC. |
| 65 |
If the object is known to never contain pointers, use GC_MALLOC_ATOMIC |
| 66 |
instead of GC_MALLOC. |
| 67 |
|
| 68 |
Define GC_DEBUG before including gc.h for additional checking. |
| 69 |
|
| 70 |
More documentation on the collector interface can be found in README.md, |
| 71 |
doc/gcinterface.md, include/gc.h, and other files in the doc directory. |
| 72 |
|
| 73 |
WARNINGS: |
| 74 |
|
| 75 |
Do not store the only pointer to an object in memory allocated |
| 76 |
with system malloc, since the collector usually does not scan |
| 77 |
memory allocated in this way. |
| 78 |
|
| 79 |
Use with threads may be supported on your system, but requires the collector |
| 80 |
to be built with thread support. See Makefile.am or Makefile.direct. |
| 81 |
The collector does not guarantee to scan thread-local storage (e.g. of the |
| 82 |
kind accessed with pthread_getspecific()). The collector does scan |
| 83 |
thread stacks though, so generally the best solution is to ensure that |
| 84 |
any pointers stored in thread-local storage are also stored on the |
| 85 |
thread's stack for the duration of their lifetime. |