source: proiecte/swift/trunk/lib/hoard-371/doc/src/documentation/content/xdocs/using.xml @ 176

Last change on this file since 176 was 176, checked in by (none), 14 years ago
  • imported repo from "guagal"
File size: 3.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
3<document> 
4  <header> 
5    <title>Using Hoard</title> 
6  </header>
7
8<body>
9
10<p>
11Using Hoard is easy. On UNIX-based platforms, all you have to do is set one environment variable. You do not need to change any source code, recompile or relink your application. On Windows, you actually have even greater flexibility.
12</p>
13
14
15<section>
16  <title>UNIX</title>
17  <p>
18In UNIX, you can use the LD_PRELOAD variable to use
19Hoard instead of the system allocator for any program not linked with
20the "static option" (that's most programs). Below are settings for
21Linux and Solaris.
22  </p>
23  <section>
24    <title>Linux</title>
25    <source>
26LD_PRELOAD="/path/libhoard.so:/usr/lib/libdl.so"
27    </source>
28  </section>
29  <section>
30    <title>Solaris</title>
31    <p>
32    Depending on whether you are using the GNU-compiled version (as
33    produced by compile) or the Sun
34    Workshop-compiled versions (produced by
35    compile-sunw), your settings will be slightly
36    different.
37    </p>
38
39    <table>
40        <tr>
41              <td>Version</td>
42              <td>Setting</td>
43        </tr>
44        <tr>
45              <td>GNU</td>
46              <td>
47                <source>
48LD_PRELOAD="/path/libhoard.so:/usr/lib/libdl.so"
49                </source>
50              </td>
51           </tr>
52           <tr>
53              <td>Sun (<em>32-bits</em>)</td>
54              <td>
55                 <source>
56LD_PRELOAD="/path/libhoard_32.so:/usr/lib/libCrun.so.1:/usr/lib/libdl.so"
57                  </source>
58              </td>
59           </tr>
60           <tr>
61              <td>Sun (<em>64-bits</em>)</td>
62              <td>
63                 <source>
64LD_PRELOAD="/path/libhoard_64.so:/usr/lib/64/libCrun.so.1:/usr/lib/64/libdl.so"
65                  </source>
66              </td>
67           </tr>
68     </table>
69
70       <p>
71For some security-sensitive applications, Solaris requires you place
72libraries used in LD_PRELOAD into the /usr/lib/secure directory. In that event,
73after copying these libraries into /usr/lib/secure, set
74LD_PRELOAD by omitting the absolute locations of the libraries, as follows:
75       </p>
76       <source>
77LD_PRELOAD="libhoard.so:libCrun.so.1:libdl.so"
78       </source>
79
80</section>
81</section>
82
83<section>
84  <title>Windows</title>
85  <p>
86  There are two ways to use Hoard on Windows.
87  </p>
88  <ol>
89  <li>
90    Using winhoard
91    <p>
92The first and best method is to use winhoard. Winhoard replaces
93malloc/new calls from your program and any DLLs it might use (leaving
94HeapAlloc calls intact).
95</p>
96
97<p>
98To use the Winhoard version, link your executable with
99usewinhoard.obj and
100winhoard.lib, and then use
101winhoard.dll:
102</p>
103
104<source>
105cl /Ox /MD myprogram.cpp usewinhoard.obj winhoard.lib
106</source>
107
108  </li>
109  <li>
110    Using libhoard
111    <p>
112
113The other method is to link directly with the libhoard DLL. This
114approach is simple, but only suitable for small applications, since it
115will not affect malloc calls in any other DLL you might load. To use
116this option, you should put the following into your source code as the
117very first lines:
118</p>
119
120<source>
121#if defined(USE_HOARD)
122#pragma comment(lib, "libhoard.lib")
123#endif
124</source>
125
126<p>
127This stanza should be in the first part of a header file included by
128all of your code. It ensures that Hoard loads before any other library
129(you will need libhoard.lib in your path). When
130you execute your program, as long as libhoard.dll
131is in your path, your program will run with Hoard instead of the
132system allocator. Note that you must compile your program with the
133/MD flag, as in:
134</p>
135
136<source>
137cl /MD /G6 /Ox /DUSE_HOARD=1 myprogram.cpp
138</source>
139
140<p>
141Hoard will not work if you use another switch (like
142/MT) to compile your program.
143    </p>
144  </li>
145  </ol>
146</section>
147
148
149
150</body>
151
152</document>
Note: See TracBrowser for help on using the repository browser.