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