[Lldb-commits] [lldb] r261795 - Update the website with lots of new info about building / testing.
Zachary Turner via lldb-commits
lldb-commits at lists.llvm.org
Wed Feb 24 14:19:23 PST 2016
Author: zturner
Date: Wed Feb 24 16:19:23 2016
New Revision: 261795
URL: http://llvm.org/viewvc/llvm-project?rev=261795&view=rev
Log:
Update the website with lots of new info about building / testing.
Modified:
lldb/trunk/www/build.html
lldb/trunk/www/test.html
Modified: lldb/trunk/www/build.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/build.html?rev=261795&r1=261794&r2=261795&view=diff
==============================================================================
--- lldb/trunk/www/build.html (original)
+++ lldb/trunk/www/build.html Wed Feb 24 16:19:23 2016
@@ -55,16 +55,22 @@
<div class="postcontent">
<h2>Required Dependencies</h2>
<ul>
- <li>Visual Studio 2012 or greater</li>
- <li>Windows SDK 8.0 or higher</li>
+ <li>Visual Studio 2015 or greater</li>
+ <li>Windows SDK 8.0 or higher. In general it is best to use the latest available version.</li>
<li>
- <a href="https://www.python.org/download/releases/2.7/">Python 2.7</a>. Note that you <b>must</b>
- compile Python from source. See <a href="#WindowsPreliminaries">Preliminaries</a> for more
- information.
+ <a href="https://www.python.org/downloads/windows/">Python 3.5 or higher</a> or higher. Earlier
+ versions of Python can be made to work by compiling your own distribution from source,
+ but this workflow is unsupported and you are own your own.
</li>
<li><a href="http://martine.github.io/ninja/">Ninja build tool</a> (strongly recommended)</li>
<li><a href="http://gnuwin32.sourceforge.net/">GnuWin32</a></li>
- <li><a href="http://www.swig.org/download.html">SWIG for Windows</a></li>
+ <li><a href="http://www.swig.org/download.html">SWIG for Windows (version 3+)</a></li>
+ </ul>
+ <h2>Optional Dependencies</h2>
+ <ul>
+ <li><a href="https://github.com/Microsoft/PTVS/releases">Python Tools for Visual Studio</a>. If you
+ plan to debug test failures or even write new tests at all, PTVS is an indispensable debugging extension
+ to VS that enables full editing and debugging support for Python (including mixed native/managed debugging)</li>
</ul>
<h2 id="WindowsPreliminaries">Preliminaries</h2>
<p>
@@ -74,45 +80,13 @@
</p>
<ol>
<li><p>Install Visual Studio and the Windows SDK.</p></li>
- <li>
- <p>
- Build Python from source using the solution file supplied with the Python 2.7 source
- distribution.
- </p>
- <p>
- Because LLDB functionality is compiled into a Python extension module,
- the extension module must be compiled with the same version of Visual Studio that
- Python itself was compiled with. The binary release of Python 2.7 is compiled with
- Visual Studio 2008, so it is incompatible with linking against LLDB.
- </p>
- <p>
- Note that if you plan to do both debug and release builds of LLDB, you will need to
- compile both debug and release builds of Python. The same applies if you plan to build
- both x86 and x64 configurations of LLDB
- </p>
- </li>
- <li>
- <p>Copy <python src dir>\PC\pyconfig.h to <python src dir>\Include.</p>
- <p>
- This is necessary because pyconfig.h is a hand-maintained file which is platform specific,
- so multiple copies of this file are included with each source distribution. It appears to
- be up to the person building Python to move the correct version of pyconfig.h to the Include
- folder.
- </p>
- </li>
- <li>
- <p>
- Run lldb/scripts/install_custom_python.py so to "install" your custom build of Python to a
- canonical directory structure.
- </p>
- </li>
- <li><p>Install GnuWin32, making sure <GnuWin32 install dir>\bin is added to your PATH environment variable.</p></li>
- <li><p>Install SWIG for Windows, making sure <SWIG install dir> is added to your PATH environment variable.</p></li>
+ <li><p>Install GnuWin32, making sure <code><GnuWin32 install dir>\bin</code> is added to your <code>PATH</code> environment variable.</p></li>
+ <li><p>Install SWIG for Windows, making sure <code><SWIG install dir></code> is added to your <code>PATH</code> environment variable.</p></li>
</ol>
<h2>Building LLDB</h2>
<p>
Any command prompt from which you build LLDB should have a valid Visual Studio environment setup.
- This means you should run vcvarsall.bat or open an appropriate Visual Studio Command Prompt
+ This means you should run <code>vcvarsall.bat</code> or open an appropriate Visual Studio Command Prompt
corresponding to the version you wish to use.
</p>
<p>Finally, when you are ready to build LLDB, generate CMake with the following command line:</p>
@@ -130,9 +104,8 @@
a crash, rather than having to reproduce a failure or use a crash dump.
</li>
<li>
- <b>PYTHON_HOME</b> (Required): Path the folder you specified in the --dest argument to install_custom_python.py.
- Note that install_custom_python.py will create x86 and x64 subdirectories under this folder. PYTHON_HOME should
- refer to the correct architecture-specific folder.
+ <b>PYTHON_HOME</b> (Required): Path to the folder where the Python distribution is installed. For example,
+ C:\Python35
</li>
<li>
<b>LLDB_RELOCATABLE_PYTHON</b> (Default=0): When this is 0, LLDB will bind statically to the location specified
@@ -142,7 +115,28 @@
use its default mechanism for finding the python installation at runtime (looking for installed Pythons, or using
the PYTHONHOME environment variable if it is specified).
</li>
+ <li>
+ <b>LLDB_TEST_COMPILER</b>: The test suite needs to be able to find a copy of clang.exe that it can use to compile
+ inferior programs. Note that MSVC is not supported here, it <strong>must</strong> be a path to a clang executable.
+ Note that using a release clang.exe is strongly recommended here, as it will make the test suite run much faster.
+ This can be a path to any recent clang.exe, including one you built yourself.
+ </li>
</ul>
+ Sample command line:<br/>
+ <code>cmake -G Ninja -DLLDB_TEST_DEBUG_TEST_CRASHES=1 -DPYTHON_HOME=C:\Python35 -DLLDB_TEST_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe ..\..\llvm</code>
+ <h2>Working with both Ninja and MSVC</h2>
+ <p>
+ Compiling with <code>ninja</code> is both faster and simpler than compiling with MSVC, but chances are you still want
+ to debug LLDB with MSVC (at least until we can debug LLDB on Windows with LLDB!). One solution to this is to run
+ <code>cmake</code> twice and generate the output into two different folders. One for compiling (the <code>ninja</code>
+ folder), and one for editing / browsing / debugging (the MSVC folder).
+ </p>
+ <p>
+ To do this, simply run <code>`cmake -G Ninja <arguments>`</code> from one folder, and
+ <code>`cmake -G "Visual Studio 14 2015" <arguments>`</code> in another folder. Then you can open the .sln file
+ in Visual Studio, set <code>lldb</code> as the startup project, and use F5 to run it. You need only edit the project
+ settings to set the executable and the working directory to point to binaries inside of the <code>ninja</code> tree.
+ </p>
</div>
</div>
<div class="post" id="BuildingLldbOnMacOSX">
Modified: lldb/trunk/www/test.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/test.html?rev=261795&r1=261794&r2=261795&view=diff
==============================================================================
--- lldb/trunk/www/test.html (original)
+++ lldb/trunk/www/test.html Wed Feb 24 16:19:23 2016
@@ -26,14 +26,22 @@
source file and then uses LLDB to debug the resulting executable. The tests verify
both the LLDB command line interface and the scripting API.
</p>
-
+ </div>
+ <h1 class="postheader">Running tests</h1>
+ <div class="postcontent">
+ <h2>Running the full test suite</h2>
+ <p>
+ <strong>Windows Note</strong>: In the examples that follow, any invocations of <code>python</code>
+ should be replaced with <code>python_d</code>, the debug interpreter, when running the test
+ suite against a debug version of LLDB.
+ </p>
<p>
The easiest way to run the LLDB test suite is to use the <tt>check-lldb</tt> build
target. By default, the <tt>check-lldb</tt> target builds the test programs with
the same compiler that was used to build LLDB. To build the tests with a different
- compiler, you can set the <tt>LLDB_TEST_COMPILER</tt> CMake variable. It is possible to
+ compiler, you can set the <strong>LLDB_TEST_COMPILER</strong> CMake variable. It is possible to
customize the architecture of the test binaries and compiler used by appending -A
- and -C options respectively to the CMake variable <tt>LLDB_TEST_USER_ARGS</tt>. For
+ and -C options respectively to the CMake variable <strong>LLDB_TEST_USER_ARGS</strong>. For
example, to test LLDB against 32-bit binaries
built with a custom version of clang, do:
</p>
@@ -44,28 +52,27 @@
<p>Note that multiple -A and -C flags can be specified to <tt>LLDB_TEST_USER_ARGS</tt>.</p>
<p>Note that on NetBSD you must export <tt>LD_LIBRARY_PATH=$PWD/lib</tt> in your environment. This is due to lack of
the <tt>$ORIGIN</tt> linker feature.</p>
+ <h2>Running a specific test or set of tests</h2>
<p>
In addition to running all the LLDB test suites with the "check-lldb" CMake target above, it is possible to
run individual LLDB tests. For example, to run the test cases defined in TestInferiorCrashing.py, run:
</p>
<code>
<br />> cd $lldb/test
- <br />> python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py
+ <br />> python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py ../packages/Python/lldbsuite/test
</code>
<p>
- In addition to running a test by name, it is also possible to specify a directory path to <tt>dotest.py</tt>
- in order to run all the tests under that directory. For example, to run all the tests under the
- 'functionalities/data-formatter' directory, run:
+ If the test is not specified by name (e.g. if you leave the <code>-p</code> argument off), LLDB will run all tests in
+ that directory:
</p>
<code>
<br />> python dotest.py --executable <path-to-lldb> functionalities/data-formatter
</code>
<p>
- To dump additional information to <tt>stdout</tt> about how the test harness is driving LLDB, run
- <tt>dotest.py</tt> with the <tt>-t</tt> flag. Many more options that are available. To see a list of all of them, run:
+ Many more options that are available. To see a list of all of them, run:
</p>
<code>
- <br />> python dotest.py -h
+ > python dotest.py -h
</code>
<p>
@@ -95,7 +102,7 @@
running in parallel with a parent directory.
</p>
- <h3>Running the test-suite remotely</h3>
+ <h2>Running the test-suite remotely</h2>
<p>
Running the test-suite remotely is similar to the process of running a local test
@@ -124,6 +131,99 @@
</div>
<div class="postfooter"></div>
+ <h1 class="postheader">Debugging test failures</h1>
+ <div class="postcontent">
+ <h2>Non-Windows platforms</h2>
+ <p>
+ On non-Windows platforms, you can use the <code>-d</code> option to <code>dotest.py</code> which will cause the script to wait
+ for a while until a debugger is attached.
+ </p>
+ <h2>Windows</h2>
+ <p>
+ On Windows, it is strongly recommended to use <a href="https://github.com/Microsoft/PTVS/releases">Python Tools for Visual Studio</a>
+ for debugging test failures. It can seamlessly step between native and managed code, which is very helpful when you need to step
+ through the test itself, and then into the LLDB code that backs the operations the test is performing. A quick guide to getting
+ started with PTVS is as follows:
+ <ul>
+ <li>Install PTVS</li>
+ <li>
+ Create a Visual Studio Project for the Python code.
+ <ul>
+ <li>Go to File -> New -> Project -> Python -> From Existing Python Code.</li>
+ <li>Choose <code>llvm/tools/lldb</code> as the directory containing the Python code.</li>
+ <li>
+ When asked where to save the <code>.pyproj</code> file, choose the folder <code>llvm/tools/lldb/pyproj</code>.
+ This is a special folder that is ignored by the <code>.gitignore</code> file, since it is not checked in.
+ </li>
+ </ul>
+ </li>
+ <li>Set <code>test/dotest.py</code> as the startup file</li>
+ <li>
+ Make sure there is a Python Environment installed for your distribution. For example, if you installed Python to
+ <code>C:\Python35</code>, PTVS needs to know that this is the interpreter you want to use for running the test suite.
+ <ul>
+ <li>Go to Tools -> Options -> Python Tools -> Environment Options</li>
+ <li>Click Add Environment, and enter <code>Python 3.5 Debug</code> for the name. Fill out the values correctly.</li>
+ </ul>
+ </li>
+ <li>
+ Configure the project to use this debug interpreter.
+ <ul>
+ <li>Right click the Project node in Solution Explorer</li>
+ <li>In the <code>General</code> tab, Make sure <code>Python 3.5 Debug</code> is the selected Interpreter.</li>
+ <li>In <code>Debug/Search Paths</code>, enter the path to your <code>ninja/lib/site-packages</code> directory.</li>
+ <li>
+ In <code>Debug/Environment Variables</code>, enter<br/>
+ <code>VCINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\</code>
+ </li>
+ <li>
+ If you want to enabled mixed mode debugging, check <code>Enable native code debugging</code> (this slows down debugging,
+ so enable it only on an as-needed basis.)
+ </li>
+ </ul>
+ </li>
+ <li>
+ Set the command line for the test suite to run.
+ <ul>
+ <li>Right click the project in solution explorer and choose the <code>Debug</code> tab.</li>
+ <li>Enter the arguments to <code>dotest.py</code>. Note you must add <code>--no-multiprocess</code></li>
+ <li>
+ Example command options:
+ <code>
+ <br/># quiet mode
+ <br/>-q
+ <br />--arch=i686
+ <br /># Path to debug lldb.exe
+ <br />--executable D:/src/llvmbuild/ninja/bin/lldb.exe
+ <br /># Directory to store log files
+ <br />-s D:/src/llvmbuild/ninja/lldb-test-traces
+ <br />-u CXXFLAGS -u CFLAGS
+ <br /># If a test crashes, show JIT debugging dialog.
+ <br />--enable-crash-dialog
+ <br /># Path to release clang.exe
+ <br />-C d:\src\llvmbuild\ninja_release\bin\clang.exe
+ <br /># Path to the particular test you want to debug.
+ <br />-p TestPaths.py
+ <br /># Root of test tree
+ <br />D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test
+ <br /># Required in order to be able to debug the test.
+ <br />--no-multiprocess
+ </code>
+ </li>
+ <li>
+ As copy-pastable command line:<br/>
+ <code>
+ -q --arch=i686 --executable D:/src/llvmbuild/ninja/bin/lldb.exe -s D:/src/llvmbuild/ninja/lldb-test-traces
+ -u CXXFLAGS -u CFLAGS --enable-crash-dialog -C d:\src\llvmbuild\ninja_release\bin\clang.exe
+ -p TestPaths.py D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test --no-multiprocess
+ </code>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </p>
+ </div>
+ <div class="postfooter"></div>
</div>
</div>
</div>
More information about the lldb-commits
mailing list