Required Dependencies
- - Visual Studio 2012 or greater
- - Windows SDK 8.0 or higher
+ - Visual Studio 2015 or greater
+ - Windows SDK 8.0 or higher. In general it is best to use the latest available version.
-
- Python 2.7. Note that you must
- compile Python from source. See Preliminaries for more
- information.
+ Python 3.5 or higher 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.
- Ninja build tool (strongly recommended)
- GnuWin32
- - SWIG for Windows
+ - SWIG for Windows (version 3+)
+
+
Optional Dependencies
+
+ - Python Tools for Visual Studio. 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)
Preliminaries
@@ -74,38 +80,6 @@
Install Visual Studio and the Windows SDK.
-
-
- Build Python from source using the solution file supplied with the Python 2.7 source
- distribution.
-
-
- 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.
-
-
- 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
-
-
- -
-
Copy <python src dir>\PC\pyconfig.h to <python src dir>\Include.
-
- 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.
-
-
- -
-
- Run lldb/scripts/install_custom_python.py so to "install" your custom build of Python to a
- canonical directory structure.
-
-
Install GnuWin32, making sure <GnuWin32 install dir>\bin is added to your PATH environment variable.
Install SWIG for Windows, making sure <SWIG install dir> is added to your PATH environment variable.
@@ -130,9 +104,8 @@
a crash, rather than having to reproduce a failure or use a crash dump.
- PYTHON_HOME (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.
+ PYTHON_HOME (Required): Path to the folder where the Python distribution is installed. For example,
+ C:\Python35
LLDB_RELOCATABLE_PYTHON (Default=0): When this is 0, LLDB will bind statically to the location specified
@@ -142,7 +115,16 @@
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).
+
+ LLDB_TEST_COMPILER: 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 must 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.
+
+ Sample command line:
+
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
+
Index: www/test.html
===================================================================
--- www/test.html
+++ www/test.html
@@ -26,14 +26,17 @@
source file and then uses LLDB to debug the resulting executable. The tests verify
both the LLDB command line interface and the scripting API.
-
+
+
+
+
Running the full test suite
The easiest way to run the LLDB test suite is to use the check-lldb build
target. By default, the check-lldb 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 LLDB_TEST_COMPILER CMake variable. It is possible to
+ compiler, you can set the LLDB_TEST_COMPILER 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 LLDB_TEST_USER_ARGS. For
+ and -C options respectively to the CMake variable LLDB_TEST_USER_ARGS. For
example, to test LLDB against 32-bit binaries
built with a custom version of clang, do:
@@ -44,28 +47,27 @@
Note that multiple -A and -C flags can be specified to LLDB_TEST_USER_ARGS.
Note that on NetBSD you must export LD_LIBRARY_PATH=$PWD/lib in your environment. This is due to lack of
the $ORIGIN linker feature.
+
Running a specific test or set of tests
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:
> cd $lldb/test
-
> python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py
+
> python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py ../packages/Python/lldbsuite/test
- In addition to running a test by name, it is also possible to specify a directory path to dotest.py
- 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 -p argument off), LLDB will run all tests in
+ that directory:
> python dotest.py --executable <path-to-lldb> functionalities/data-formatter
- To dump additional information to stdout about how the test harness is driving LLDB, run
- dotest.py with the -t 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:
-
> python dotest.py -h
+ > python dotest.py -h
@@ -95,7 +97,7 @@
running in parallel with a parent directory.
-
Running the test-suite remotely
+
Running the test-suite remotely
Running the test-suite remotely is similar to the process of running a local test
@@ -124,6 +126,99 @@
+
Non-Windows platforms
+
+ On non-Windows platforms, you can use the -d option to dotest.py which will cause the script to wait
+ for a while until a debugger is attached.
+
+
Windows
+
+ On Windows, it is strongly recommended to use Python Tools for Visual Studio
+ 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:
+
+ - Install PTVS
+ -
+ Create a Visual Studio Project for the Python code.
+
+ - Go to File -> New -> Project -> Python -> From Existing Python Code.
+ - Choose
llvm/tools/lldb as the directory containing the Python code.
+ -
+ When asked where to save the
.pyproj file, choose the folder llvm/tools/lldb/pyproj.
+ This is a special folder that is ignored by the .gitignore file, since it is not checked in.
+
+
+
+ -
+ Make sure there is a Python Environment installed for your distribution. For example, if you installed Python to
+
C:\Python35, PTVS needs to know that this is the interpreter you want to use for running the test suite.
+
+ - Go to Tools -> Options -> Python Tools -> Environment Options
+ - Click Add Environment, and enter
Python 3.5 Debug for the name. Fill out the values correctly.
+
+
+ - Set
test/dotest.py as the startup file
+ -
+ Configure the project to use this debug interpreter.
+
+ - Right click the Project node in Solution Explorer
+ - In the
General tab, Make sure Python 3.5 Debug is the selected Interpreter.
+ - In
Debug/Search Paths, enter the path to your ninja/lib/site-packages directory.
+ -
+ In
Debug/Environment Variables, enter
+ VCINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\
+
+ -
+ If you want to enabled mixed mode debugging, check
Enable native code debugging (this slows down debugging,
+ so enable it only on an as-needed basis.)
+
+
+
+ -
+ Set the command line for the test suite to run.
+
+ - Right click the project in solution explorer and choose the
Debug tab.
+ - Enter the arguments to
dotest.py. Note you must add --no-multiprocess
+ -
+ Example command options:
+
+
# quiet mode
+
-q
+
--arch=i686
+
# Path to debug lldb.exe
+
--executable D:/src/llvmbuild/ninja/bin/lldb.exe
+
# Directory to store log files
+
-s D:/src/llvmbuild/ninja/lldb-test-traces
+
-u CXXFLAGS -u CFLAGS
+
# If a test crashes, show JIT debugging dialog.
+
--enable-crash-dialog
+
# Path to release clang.exe
+
-C d:\src\llvmbuild\ninja_release\bin\clang.exe
+
# Path to the particular test you want to debug.
+
-p TestPaths.py
+
# Root of test tree
+
D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test
+
# Required in order to be able to debug the test.
+
--no-multiprocess
+
+
+ -
+ As copy-pastable command line:
+
+ -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
+
+
+
+
+
+
+