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,45 +80,13 @@
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.
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.
Building LLDB
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 vcvarsall.bat or open an appropriate Visual Studio Command Prompt
corresponding to the version you wish to use.
Finally, when you are ready to build LLDB, generate CMake with the following command line:
@@ -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,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).
+
+ 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
+
Working with both Ninja and MSVC
+
+ Compiling with ninja 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
+ cmake twice and generate the output into two different folders. One for compiling (the ninja
+ folder), and one for editing / browsing / debugging (the MSVC folder).
+
+
+ To do this, simply run `cmake -G Ninja <arguments>` from one folder, and
+ `cmake -G "Visual Studio 14 2015" <arguments>` in another folder. Then you can open the .sln file
+ in Visual Studio, set lldb 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 ninja tree.
+
Index: www/test.html
===================================================================
--- www/test.html
+++ 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.
-
+
+
+
+
Running the full test suite
+
+ Windows Note: In the examples that follow, any invocations of python
+ should be replaced with python_d, the debug interpreter, when running the test
+ suite against a debug version of LLDB.
+
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 +52,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 +102,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 +131,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.
+
+
+
+ - Set
test/dotest.py as the startup file
+ -
+ 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.
+
+
+ -
+ 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
+
+
+
+
+
+
+