2010-03-20 Maciej Stachowiak <mjs@apple.com>
[WebKit.git] / WebKitSite / building / debug.html
1 <?php
2     $title = "Debugging WebKit";
3     include("../header.inc");
4 ?>
6 <div class="mac-instructions">
7 <h2>Debugging on Mac OS X</h2>
8 <ol>
9 <li><p>Open a project</p>
10 <p>Each WebKit component -- JavaScriptCore, WebCore, and WebKit -- contains its own Xcode project. Open the project belonging to the component you want to debug.</p>
11 </li>
12 <li><p>Set the project's build products location</p>
13 <p>To find the WebKit you built, Xcode needs to know the build products location that <code>build-webkit</code> used. You can set the build products location from the project's Info window.</p>
14 <img src="info-tab.png">
15 </li>
16 <li><p>Set the project's active build configuration</p>
17 <p>Xcode also needs to know the build configuration you used. You can set the active build configuration from the project's Build window.</p>
18 <img src="build-window.png">
19 </li>
20 <li><p>Add a custom executable to the project</p>
21 <p>Choose any WebKit application you want to use for debugging. To use Safari, select /Applications/Safari.app.</p>
22 <img src="custom-executable.png">
23 </li>
24 <li><p>Set the project's active executable</p>
25 <p>You can set the active executable from the project's Build window. Choose the executable you just added.</p>
26 </li>
27 <li><p>Close and re-open the project</p>
28 <p>This will force Xcode to discover generated source files, which output to your build products location, allowing you to set breakpoints in them.</p>
29 </li>
30 <li><p>Launch the debugger</p>
31 <p>In the Debugger window, click the "Debug" button.</p>
32 <img src="debug.png">
33 </li>
34 <li><p>See the <a href="http://developer.apple.com/documentation/DeveloperTools/Conceptual/XcodeDebugging/index.html">Xcode Debugging Guide</a> for more information on using Xcode to debug software on Mac OS X.</p>
35 </li>
36 </ol>
37 </div>
38 <div class="windows-instructions">
39 <h2>Debugging on Windows</h2>
40 <p>To launch Safari in the Visual Studio or Visual C++ Express debugger, simply run:</p>
41 <p class="code">debug-safari</p>
42 <p>This command will launch the Visual Studio debugging environment, and attach to Safari connected to the debug build of WebKit.dll.  There are a few things to keep in mind:</p>
43 <ul>
44 <li>The instance of Safari is not running yet.  You must press the F5 key (or the 'Run' button) to see anything happen.</li>
45 <li>If you want to set any breakpoints, you must navigate to the particular source file you wish to investigate using the "File|Open" menu.</li>
46 <li><p>If you want to see the helpful output debug messages, you should edit the debug settings for the Safari solution (i.e., the pseudo-project created when the debugger attached to Safari):</p>
47 <img src="debug_vs2005.jpg">
48 <p>You should consider including the command-line switch '<span class="code">/console</span>'.  This causes Safari to run with an open DOS shell in which output messages, created with the <span class="code">LOG</span> macro, appear.</p>
49 <img src="console_vs2005.jpg"></li>
50 </ul>
51 <p>Alternatively, you can build, run, and debug WebKit from inside Visual Studio by opening the solution file:</p>
52 <ol>
53 <li>Launch Visual Studio.</li>
54 <li>Select the 'File' menu, then 'Open' > 'Project / Solution...'. Select the WebKit/win/WebKit.vcproj/WebKit.sln file and click 'Open'.</li>
55 <li>Right-click on 'Solution "WebKit"' in the Solution Explorer and select 'Properties'. Under 'Common Properties' > 'Startup Project', 'Single Startup Project' should be set to 'WebKit'.</li>
56 <li>Right-click on the 'WebKit' project in the Solution Explorer and select 'Properties'. Under 'Configuration Properties' > 'Debugging', make sure 'Command' and 'Working Directory' are set as shown above.</li>
57 <li>To build, select the 'Build' menu, then 'Build Solution'. To run, select the 'Debug' menu, then 'Start Debugging'.</li>
58 </ol>
59 <p>It is also recommended that you follow <a href="http://developer.apple.com/internet/safari/windows_symbols_agree.html">the instructions to configure Visual Studio to use Apple's Safari for Windows symbol server</a>. This will give Visual Studio the information it needs to provide reliable backtraces when pausing in the debugger or when a crash occurs.</p>
60 </div>
62 <?php
63     include("../footer.inc");
64 ?>