213 lines
9.1 KiB
Plaintext
213 lines
9.1 KiB
Plaintext
The collector has at various times been compiled under Windows 95 & later, NT,
|
|
and XP, with the original Microsoft SDK, with Visual C++ 2.0, 4.0, and 6, with
|
|
the GNU win32 tools, with Borland 4.5, with Watcom C, and recently
|
|
with the Digital Mars compiler. It is likely that some of these have been
|
|
broken in the meantime. Patches are appreciated.
|
|
|
|
For historical reasons,
|
|
the collector test program "gctest" is linked as a GUI application,
|
|
but does not open any windows. Its output normally appears in the file
|
|
"gctest.gc.log". It may be started from the file manager. The hour glass
|
|
cursor may appear as long as it's running. If it is started from the
|
|
command line, it will usually run in the background. Wait a few
|
|
minutes (a few seconds on a modern machine) before you check the output.
|
|
You should see either a failure indication or a "Collector appears to
|
|
work" message.
|
|
|
|
A toy editor (cord/de.exe) based on cords (heavyweight
|
|
strings represented as trees) has been ported and is included.
|
|
It runs fine under either win32 or win32S. It serves as an example
|
|
of a true Windows application, except that it was written by a
|
|
nonexpert Windows programmer. (There are some peculiarities
|
|
in the way files are displayed. The <cr> is displayed explicitly
|
|
for standard DOS text files. As in the UNIX version, control
|
|
characters are displayed explicitly, but in this case as red text.
|
|
This may be suboptimal for some tastes and/or sets of default
|
|
window colors.)
|
|
|
|
In general -DREDIRECT_MALLOC is unlikely to work unless the
|
|
application is completely statically linked.
|
|
|
|
The collector normally allocates memory from the OS with VirtualAlloc.
|
|
This appears to cause problems under Windows NT and Windows 2000 (but
|
|
not Windows 95/98) if the memory is later passed to CreateDIBitmap.
|
|
To work around this problem, build the collector with -DUSE_GLOBAL_ALLOC.
|
|
This is currently incompatible with -DUSE_MUNMAP. (Thanks to Jonathan
|
|
Clark for tracking this down. There's some chance this may be fixed
|
|
since we now separate heap sections with an unused page.)
|
|
|
|
[Threads and incremental collection are discussed near the end, below.]
|
|
|
|
Microsoft Tools
|
|
---------------
|
|
For Microsoft development tools, rename NT_MAKEFILE as
|
|
MAKEFILE. (Make sure that the CPU environment variable is defined
|
|
to be i386.) In order to use the gc_cpp.h C++ interface, all
|
|
client code should include gc_cpp.h.
|
|
|
|
[See above for gctest.]
|
|
|
|
If you would prefer a VC++ .NET project file, ask Hans Boehm. One has
|
|
been contributed, but it seems to contain some absolute paths etc., so
|
|
it can presumably only be a starting point, and is not in the standard
|
|
distribution. It is unclear (to me, Hans Boehm) whether it is feasible to
|
|
change that.
|
|
|
|
Clients may need to define GC_NOT_DLL before including gc.h, if the
|
|
collector was built as a static library.
|
|
|
|
GNU Tools
|
|
---------
|
|
The collector should be buildable under Cygwin with the
|
|
"./configure; make check" machinery.
|
|
|
|
MinGW builds (including for x86_64) are available both directly (on a Windows
|
|
host) and via cross-compilation, e.g.
|
|
"./configure --host=i686-pc-mingw32; make check"
|
|
|
|
To build the collector as a DLL, pass "--enable-shared --disable-static" to
|
|
configure (this will instruct make to compile with -D GC_DLL).
|
|
|
|
Parallel marker is enabled by default; it could be disabled by
|
|
"--disable-parallel-mark" option.
|
|
|
|
Memory unmapping could be turned off by "--disable-munmap" option.
|
|
|
|
Borland Tools
|
|
-------------
|
|
[Rarely tested.]
|
|
For Borland tools, use BCC_MAKEFILE. Note that
|
|
Borland's compiler defaults to 1 byte alignment in structures (-a1),
|
|
whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
|
|
The garbage collector in its default configuration EXPECTS AT
|
|
LEAST 4 BYTE ALIGNMENT. Thus the BORLAND DEFAULT MUST
|
|
BE OVERRIDDEN. (In my opinion, it should usually be anyway.
|
|
I expect that -a1 introduces major performance penalties on a
|
|
486 or Pentium.) Note that this changes structure layouts. (As a last
|
|
resort, gcconfig.h can be changed to allow 1 byte alignment. But
|
|
this has significant negative performance implications.)
|
|
The Makefile is set up to assume Borland 4.5. If you have another
|
|
version, change the line near the top.
|
|
|
|
Digital Mars compiler
|
|
---------------------
|
|
|
|
Same as MS Visual C++ but might require
|
|
-DAO_OLD_STYLE_INTERLOCKED_COMPARE_EXCHANGE option to compile with the
|
|
parallel marker enabled.
|
|
|
|
Watcom compiler
|
|
---------------
|
|
|
|
Ivan V. Demakov's README for the Watcom port:
|
|
|
|
The collector has been compiled with Watcom C 10.6 and 11.0.
|
|
It runs under win32, win32s, and even under msdos with dos4gw
|
|
dos-extender. It should also run under OS/2, though this isn't
|
|
tested. Under win32 the collector can be built either as dll
|
|
or as static library.
|
|
|
|
Note that all compilations were done under Windows 95 or NT.
|
|
For unknown reason compiling under Windows 3.11 for NT (one
|
|
attempt has been made) leads to broken executables.
|
|
|
|
Incremental collection is not supported.
|
|
|
|
cord is not ported.
|
|
|
|
Before compiling you may need to edit WCC_MAKEFILE to set target
|
|
platform, library type (dynamic or static), calling conventions, and
|
|
optimization options.
|
|
|
|
To compile the collector and testing programs use the command:
|
|
wmake -f WCC_MAKEFILE
|
|
|
|
All programs using gc should be compiled with 4-byte alignment.
|
|
For further explanations on this see comments about Borland.
|
|
|
|
If the gc is compiled as dll, the macro "GC_DLL" should be defined before
|
|
including "gc.h" (for example, with -DGC_DLL compiler option). It's
|
|
important, otherwise resulting programs will not run.
|
|
|
|
|
|
Special note for OpenWatcom users: the C (unlike the C++) compiler (of the
|
|
latest stable release, not sure for older ones) doesn't force pointer global
|
|
variables (i.e. not struct fields, not sure for locals) to be aligned unless
|
|
optimizing for speed (e.g., "-ot" option is set); the "-zp" option (or align
|
|
pragma) only controls alignment for structs; I don't know whether it's a bug or
|
|
a feature (see an old report of same kind -
|
|
http://bugzilla.openwatcom.org/show_bug.cgi?id=664), so You are warned.
|
|
|
|
|
|
Incremental Collection
|
|
----------------------
|
|
There is some support for incremental collection. By default, the
|
|
collector chooses between explicit page protection, and GetWriteWatch-based
|
|
write tracking automatically, depending on the platform.
|
|
|
|
The former is slow and interacts poorly with a debugger.
|
|
Pages are protected. Protection faults are caught by a handler
|
|
installed at the bottom of the handler
|
|
stack. Whenever possible, I recommend adding a call to
|
|
GC_enable_incremental at the last possible moment, after most
|
|
debugging is complete. No system
|
|
calls are wrapped by the collector itself. It may be necessary
|
|
to wrap ReadFile calls that use a buffer in the heap, so that the
|
|
call does not encounter a protection fault while it's running.
|
|
(As usual, none of this is an issue unless GC_enable_incremental
|
|
is called.)
|
|
|
|
Note that incremental collection is disabled with -DSMALL_CONFIG.
|
|
|
|
Threads
|
|
-------
|
|
|
|
This version of the collector by default handles threads similarly
|
|
to other platforms. James Clark's code which tracks threads attached
|
|
to the collector DLL still exists, but requires that both
|
|
- the collector is built in a DLL with GC_DLL defined, and
|
|
- GC_use_threads_discovery() is called before GC initialization, which
|
|
in turn must happen before creating additional threads.
|
|
We generally recommend avoiding this if possible, since it seems to
|
|
be less than 100% reliable.
|
|
|
|
Use gc.mak instead of NT_MAKEFILE to build a version that supports
|
|
both kinds of thread tracking. To build the garbage collector
|
|
test with VC++ from the command line, use
|
|
|
|
nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
|
|
|
|
This requires that the subdirectory gctest\Release exist.
|
|
The test program and DLL will reside in the Release directory.
|
|
|
|
This version currently supports incremental collection only if it is
|
|
enabled before any additional threads are created.
|
|
|
|
Since 6.3alpha2, threads are also better supported in static library builds
|
|
with Microsoft tools (e.g., NT_MAKEFILE) and with the GNU
|
|
tools. The collector must be built with GC_THREADS defined (this is the
|
|
default in NT_MAKEFILE, ./configure and CMakeLists.txt).
|
|
|
|
For the normal, non-dll-based thread tracking to work properly,
|
|
threads should be created with GC_CreateThread or GC_beginthreadex,
|
|
and exit normally or call GC_endthreadex or GC_ExitThread. (For Cygwin, the
|
|
standard pthread_create/exit calls could be used instead.) As in the pthread
|
|
case, including gc.h will redefine CreateThread, _beginthreadex,
|
|
_endthreadex, and ExitThread to call the GC_ versions instead.
|
|
|
|
Note that, as usual, GC_CreateThread tends to introduce resource leaks (in the
|
|
C runtime) that are avoided by GC_beginthreadex. There is currently no
|
|
equivalent of _beginthread, and it should not be used.
|
|
|
|
GC_INIT should be called from the main thread before other GC calls.
|
|
|
|
We strongly advise against using the TerminateThread() win32 API call,
|
|
especially with the garbage collector. Any use is likely to provoke a
|
|
crash in the GC, since it makes it impossible for the collector to
|
|
correctly track threads.
|
|
|
|
To build the collector for MinGW pthreads-win32 (or other non-Cygwin pthreads
|
|
implementation for Windows), use Makefile.direct and explicitly set
|
|
GC_WIN32_PTHREADS (or pass --enable-threads=pthreads to configure).
|
|
Use -DPTW32_STATIC_LIB for the static threads library.
|