Update the website with lots of new info about building / testing.
git-svn-id: https://llvm.org/svn/llvm-project/lldb/trunk@261795 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Zachary Turner
Родитель
d55f10ccfe
Коммит
05b1f71480
|
|
@ -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">
|
||||
|
|
|
|||
122
www/test.html
122
www/test.html
|
|
@ -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>
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче