diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/LuaJIT-1.1.7/jitdoc/luajit_debug.html | 273 |
1 files changed, 0 insertions, 273 deletions
diff --git a/libraries/LuaJIT-1.1.7/jitdoc/luajit_debug.html b/libraries/LuaJIT-1.1.7/jitdoc/luajit_debug.html deleted file mode 100644 index 95d5565..0000000 --- a/libraries/LuaJIT-1.1.7/jitdoc/luajit_debug.html +++ /dev/null | |||
@@ -1,273 +0,0 @@ | |||
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> | ||
2 | <html> | ||
3 | <head> | ||
4 | <title>Debugging LuaJIT</title> | ||
5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
6 | <meta name="Author" content="Mike Pall"> | ||
7 | <meta name="Copyright" content="Copyright (C) 2005-2011, Mike Pall"> | ||
8 | <meta name="Language" content="en"> | ||
9 | <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> | ||
10 | <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> | ||
11 | </head> | ||
12 | <body> | ||
13 | <div id="site"> | ||
14 | <a href="http://luajit.org/"><span>Lua<span id="logo">JIT</span></span></a> | ||
15 | </div> | ||
16 | <div id="head"> | ||
17 | <h1>Debugging LuaJIT</h1> | ||
18 | </div> | ||
19 | <div id="nav"> | ||
20 | <ul><li> | ||
21 | <a href="index.html">Index</a> | ||
22 | </li><li> | ||
23 | <a href="luajit.html">LuaJIT</a> | ||
24 | <ul><li> | ||
25 | <a href="luajit_features.html">Features</a> | ||
26 | </li><li> | ||
27 | <a href="luajit_install.html">Installation</a> | ||
28 | </li><li> | ||
29 | <a href="luajit_run.html">Running</a> | ||
30 | </li><li> | ||
31 | <a href="luajit_api.html">API Extensions</a> | ||
32 | </li><li> | ||
33 | <a href="luajit_intro.html">Introduction</a> | ||
34 | </li><li> | ||
35 | <a href="luajit_performance.html">Performance</a> | ||
36 | </li><li> | ||
37 | <a class="current" href="luajit_debug.html">Debugging</a> | ||
38 | </li><li> | ||
39 | <a href="luajit_changes.html">Changes</a> | ||
40 | </li></ul> | ||
41 | </li><li> | ||
42 | <a href="coco.html">Coco</a> | ||
43 | <ul><li> | ||
44 | <a href="coco_portability.html">Portability</a> | ||
45 | </li><li> | ||
46 | <a href="coco_api.html">API Extensions</a> | ||
47 | </li><li> | ||
48 | <a href="coco_changes.html">Changes</a> | ||
49 | </li></ul> | ||
50 | </li><li> | ||
51 | <a href="dynasm.html">DynASM</a> | ||
52 | <ul><li> | ||
53 | <a href="dynasm_features.html">Features</a> | ||
54 | </li><li> | ||
55 | <a href="dynasm_examples.html">Examples</a> | ||
56 | </li></ul> | ||
57 | </li><li> | ||
58 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
59 | </li></ul> | ||
60 | </div> | ||
61 | <div id="main"> | ||
62 | <p> | ||
63 | LuaJIT is a rather complex application. There will undoubtedly | ||
64 | be bugs lurking in there. You have been warned. :-) | ||
65 | </p> | ||
66 | <p> | ||
67 | If you came here looking for information on how to debug | ||
68 | <em>your application</em> (and not LuaJIT itself) then please | ||
69 | check out <a href="luajit_api.html#jit_debug"><tt>jit.debug()</tt></a> | ||
70 | and the <a href="luajit_run.html#j_debug"><tt>-j debug</tt></a> | ||
71 | command line option. | ||
72 | </p> | ||
73 | <p> | ||
74 | But if you suspect a problem with LuaJIT itself, then try | ||
75 | any of the following suggestions (in order). | ||
76 | </p> | ||
77 | |||
78 | <h2>Is LuaJIT the Problem?</h2> | ||
79 | <p> | ||
80 | Try to run your application in several different ways: | ||
81 | </p> | ||
82 | <ul> | ||
83 | <li><tt>luajit app.lua</tt></li> | ||
84 | <li><tt>luajit -O1 app.lua</tt></li> | ||
85 | <li><tt>luajit -O app.lua</tt></li> | ||
86 | <li><tt>luajit -j off app.lua</tt></li> | ||
87 | <li><tt>lua app.lua</tt> (i.e. with standard Lua)</li> | ||
88 | </ul> | ||
89 | <p> | ||
90 | If the behaviour is the <em>same</em> as with standard Lua then ... | ||
91 | well ... that's what LuaJIT is about: doing the same things, | ||
92 | just faster. Even bugs fly faster. :-) | ||
93 | </p> | ||
94 | <p> | ||
95 | So this is most likely a bug in your application then. It may be easier | ||
96 | to debug this with plain Lua — the remainder of this page | ||
97 | is probably not helpful for you. | ||
98 | </p> | ||
99 | <p> | ||
100 | But if the behaviour is <em>different</em>, there is some likelihood | ||
101 | that you caught a bug in LuaJIT. Oh dear ... | ||
102 | </p> | ||
103 | <p> | ||
104 | Ok, so don't just give up. Please read on and help the community | ||
105 | by finding the bug. Thank you! | ||
106 | </p> | ||
107 | |||
108 | <h2>Get the Latest Version</h2> | ||
109 | <p> | ||
110 | Number one on your list of things to check is the | ||
111 | <a href="http://luajit.org/luajit_changes.html"><span class="ext">»</span> Online Change History</a>. | ||
112 | </p> | ||
113 | <p> | ||
114 | Please check if a newer version is available. Maybe the bug | ||
115 | you have encountered has been fixed already. Always download the | ||
116 | latest version and try it with your application before continuing. | ||
117 | </p> | ||
118 | |||
119 | <h2>Reproduce the Bug</h2> | ||
120 | <p> | ||
121 | First try to make the bug reproducible. Try to isolate the module | ||
122 | and the function the bug occurs in: | ||
123 | </p> | ||
124 | <p> | ||
125 | Either selectively turn off compilation for some modules with<br> | ||
126 | <tt> jit.off(true, true)</tt><br> | ||
127 | until the bug disappears ... | ||
128 | </p> | ||
129 | <p> | ||
130 | And/or turn the whole JIT engine off and selectively compile | ||
131 | functions with<br> | ||
132 | <tt> jit.compile(func)</tt><br> | ||
133 | until it reappears. | ||
134 | </p> | ||
135 | <p> | ||
136 | If you have isolated the point where it happens, it's most helpful | ||
137 | to reduce the affected Lua code to a short code snippet that | ||
138 | still shows the problem. You may need to <tt>print()</tt> some | ||
139 | variables until you can pinpoint the exact spot where it happens. | ||
140 | </p> | ||
141 | <p> | ||
142 | If you've got a <em>reproducible</em> and <em>short</em> test | ||
143 | you can either send it directly to me or the mailing list | ||
144 | (see the <a href="contact.html">Contact Information</a>) | ||
145 | or you can try to debug this a bit further. | ||
146 | </p> | ||
147 | <p> | ||
148 | Well — if you are brave enough. :-) | ||
149 | </p> | ||
150 | |||
151 | <h2>Look at the Generated Code</h2> | ||
152 | <p> | ||
153 | You may want to have a look at the output of <tt>-j dumphints</tt> | ||
154 | first. Try to change things around until you can see which hint | ||
155 | or which instruction is the cause of the bug. If you suspect | ||
156 | an optimizer bug then have a look at the backend (<tt>*.das[ch]</tt>) | ||
157 | and check how the hint is encoded. | ||
158 | </p> | ||
159 | <p> | ||
160 | Otherwise have a look at <tt>-j dump</tt> and see whether | ||
161 | you can spot the problem around the affected instruction. | ||
162 | It's helpful to have a good knowledge of assembler, though | ||
163 | (sorry). | ||
164 | </p> | ||
165 | |||
166 | <h2>Locate a Crash</h2> | ||
167 | <p> | ||
168 | If you get a crash, you should compile LuaJIT with debugging | ||
169 | turned on: | ||
170 | </p> | ||
171 | <p> | ||
172 | Add <tt>-g</tt> to <tt>CFLAGS</tt> and <tt>MYLDFLAGS</tt> | ||
173 | or whatever is needed to turn on debugging. For Windows you | ||
174 | need both an executable and a DLL built with debugging. | ||
175 | </p> | ||
176 | <p> | ||
177 | Then start LuaJIT with your debugger. Run it with | ||
178 | <tt>-j dump=test.dump</tt>. | ||
179 | </p> | ||
180 | <p> | ||
181 | Have a look at the backtrace and compare it with the generated | ||
182 | dump file to find out exactly where it crashes. I'm sorry, but | ||
183 | symbols or instructions for JIT compiled functions are not | ||
184 | displayed in your debugger (this is really hard to solve). | ||
185 | </p> | ||
186 | |||
187 | <h2>Turn on Assertions</h2> | ||
188 | <p> | ||
189 | Another way to debug LuaJIT is to turn on assertions. | ||
190 | They can be turned on only for the JIT engine by adding | ||
191 | <tt>-DLUAJIT_ASSERT</tt> to <tt>JITCFLAGS</tt> in <tt>src/Makefile</tt>. | ||
192 | Then recompile with <tt>make clean</tt> and <tt>make</tt>. | ||
193 | </p> | ||
194 | <p> | ||
195 | Add these two lines to <tt>src/luaconf.h</tt> to turn on all assertions in the Lua core:<br> | ||
196 | <tt> #include <assert.h></tt><br> | ||
197 | <tt> #define lua_assert(x) assert(x)</tt><br> | ||
198 | This turns on the JIT engine assertions, too. | ||
199 | Recompile and see whether any assertions trigger. | ||
200 | Don't forget to turn off the (slow) assertions when you're done! | ||
201 | </p> | ||
202 | |||
203 | <h2>Use Valgrind</h2> | ||
204 | <p> | ||
205 | A tremendously useful (and free) tool for runtime code analysis | ||
206 | is <a href="http://valgrind.org/"><span class="ext">»</span> Valgrind</a>. Regularly | ||
207 | run your applications with <tt>valgrind --memcheck</tt> and | ||
208 | your life will be better. | ||
209 | </p> | ||
210 | <p> | ||
211 | To run LuaJIT under Valgrind you <em>must</em> add | ||
212 | <tt>-DUSE_VALGRIND</tt> to <tt>MYCFLAGS</tt> | ||
213 | and recompile LuaJIT. You will get random errors if you don't! | ||
214 | Valgrind 3.x or later is required. Earlier versions | ||
215 | do not work well with newly allocated C stacks. | ||
216 | </p> | ||
217 | <p> | ||
218 | An executable built with this option runs fine without Valgrind | ||
219 | and without a performance loss. But it needs the Valgrind header | ||
220 | files for compilation (which is why it's not enabled by default). | ||
221 | </p> | ||
222 | <p> | ||
223 | It's helpful to compile LuaJIT with debugging turned on, too | ||
224 | (see above). | ||
225 | </p> | ||
226 | <p> | ||
227 | If Valgrind spots many invalid memory accesses that involve | ||
228 | memory allocation/free functions you've probably found a bug | ||
229 | related to garbage collection. Some object reference must have | ||
230 | gone astray. | ||
231 | </p> | ||
232 | <p> | ||
233 | Try to find out which object is disappearing. You can force | ||
234 | eager garbage collection with repeated calls to | ||
235 | <tt>collectgarbage()</tt> or by setting a very low threshold | ||
236 | with <tt>collectgarbage("setpause", 1)</tt>. | ||
237 | </p> | ||
238 | |||
239 | <h2>Don't Despair</h2> | ||
240 | <p> | ||
241 | If all of this doesn't help to find the bug, please send | ||
242 | a summary of your findings to the mailing list. Describe as much | ||
243 | of the circumstances you think are relevant. | ||
244 | </p> | ||
245 | <p> | ||
246 | Please <em>don't</em> send your whole application to me | ||
247 | (without asking first) and especially not to the mailing list. | ||
248 | Code snippets should preferrably be less than 50 lines and | ||
249 | up to the point. | ||
250 | </p> | ||
251 | <p> | ||
252 | All bug reports are helpful, even if no immediate solution | ||
253 | is available. Often enough someone else finds the same bug | ||
254 | in a different setting and together with your bug report | ||
255 | this may help to track it down. | ||
256 | </p> | ||
257 | <p> | ||
258 | Finally I have to say a <strong>BIG THANK YOU</strong> | ||
259 | to everyone who has helped to make LuaJIT better by finding | ||
260 | and fixing bugs! | ||
261 | </p> | ||
262 | <br class="flush"> | ||
263 | </div> | ||
264 | <div id="foot"> | ||
265 | <hr class="hide"> | ||
266 | Copyright © 2005-2011 Mike Pall | ||
267 | <span class="noprint"> | ||
268 | · | ||
269 | <a href="contact.html">Contact</a> | ||
270 | </span> | ||
271 | </div> | ||
272 | </body> | ||
273 | </html> | ||