[clang] clang: improve lit testing docs (PR #178244)
Henry Kleynhans via cfe-commits
cfe-commits at lists.llvm.org
Tue Jan 27 09:51:26 PST 2026
https://github.com/hkleynhans updated https://github.com/llvm/llvm-project/pull/178244
>From dd569b91cf1337efd08210ee970111a20e492d07 Mon Sep 17 00:00:00 2001
From: Henry Kleynhans <henry.kleynhans at gmail.com>
Date: Tue, 27 Jan 2026 16:07:58 +0000
Subject: [PATCH 1/2] clang: improve lit testing docs
The LLVM Integrated Tester now generates an "easy to use" script to run
clang tests. It is no longer needed to pass all of the commandline
arguments to it. This PR simplifies the documentation a little by
removing the unneeded commandline arguments and adding a link to the lit
man page.
---
clang/www/hacking.html | 77 ++++++++++++++++++++----------------------
1 file changed, 37 insertions(+), 40 deletions(-)
diff --git a/clang/www/hacking.html b/clang/www/hacking.html
index 90dcc3f4fc042..c489eab54c59b 100755
--- a/clang/www/hacking.html
+++ b/clang/www/hacking.html
@@ -207,56 +207,53 @@ <h3 id="testingCommands">Testing on the Command Line</h3>
<!--=====================================================================-->
<p>If you want more control over how the tests are run, it may
- be convenient to run the test harness on the command-line directly. Before
- running tests from the command line, you will need to ensure that
- <tt>lit.site.cfg</tt> files have been created for your build. You can do
- this by running the tests as described in the previous sections. Once the
- tests have started running, you can stop them with control+C, as the
- files are generated before running any tests.</p>
+ be convenient to run the test harness on the command-line directly. Running
+ the <tt>check-clang</tt> build target will result in the
+ <a href="https://llvm.org/docs/CommandGuide/lit.html">LLVM Integrated
+ Tester</a> (<tt>lit</tt>) generating a startup script to run tests for your
+ current configuration. Once the tests have started running, you can stop
+ them with <tt>control+C</tt>, as the files are generated before running any
+ tests.</p>
- <p>Once that is done, to run all the tests from the command line,
- execute a command like the following:</p>
+ <p>Once that is done, all the tests can be executed from the command line
+ by running the generated <tt>llvm-lit.cmd</tt> script as follows:</p>
<pre>
- python (path to llvm)\llvm\utils\lit\lit.py -sv
- --param=build_mode=Win32 --param=build_config=Debug
- --param=clang_site_config=(build dir)\tools\clang\test\lit.site.cfg
- (path to llvm)\llvm\tools\clang\test
-</pre>
-
- <p>For CMake builds e.g. on Windows with Visual Studio, you will need
- to specify your build configuration (Debug, Release, etc.) via
- <tt>--param=build_config=(build config)</tt>. You may also need to specify
- the build mode (Win32, etc) via <tt>--param=build_mode=(build mode)</tt>.</p>
-
- <p>Additionally, you will need to specify the lit site configuration which
- lives in (build dir)\tools\clang\test, via
- <tt>--param=clang_site_config=(build dir)\tools\clang\test\lit.site.cfg</tt>.
- </p>
-
- <p>To run a single test:</p>
+ (build dir)\bin\llvm-lit.cmd (path to llvm)\clang\test
+ </pre>
+ For a Visual Studio Debug build in the <tt>llvm-project\build</tt> directory
+ lit start command to execute from the <tt>llvm-project</tt> folder would be:
<pre>
- python (path to llvm)\llvm\utils\lit\lit.py -sv
- --param=build_mode=Win32 --param=build_config=Debug
- --param=clang_site_config=(build dir)\tools\clang\test\lit.site.cfg
- (path to llvm)\llvm\tools\clang\test\(dir)\(test)
-</pre>
+ build\Debug\bin\llvm-lit.cmd clang\test
+ </pre>
- <p>For example:</p>
+ If you have a Ninja build in the <tt>llvm-project\build_ninja</tt> directory,
+ the command to execute from the <tt>llvm-project</tt> folder would be:
+ <pre>
+ build_ninja\bin\llvm-lit.cmd clang\test
+ </pre>
+ The LLVM Integrated Testser also generates a <tt>llvm-lit.py</tt> script
+ alongside the <tt>llvm-lit.cmd</tt> script so that it can also be started
+ using python directly in the event that you are not using a CMD prompt:
<pre>
- python C:\Tools\llvm\utils\lit\lit.py -sv
- --param=build_mode=Win32 --param=build_config=Debug
- --param=clang_site_config=C:\Tools\build\tools\clang\test\lit.site.cfg
- C:\Tools\llvm\tools\clang\test\Sema\wchar.c
-</pre>
+ python.exe (path to build)\bin\llvm-lit.py (path to llvm-project)\clang\test
+ </pre>
- <p>The -sv option above tells the runner to show the test output if
- any tests failed, to help you determine the cause of failure.</p>
+ <p>You can also run a single test or all tests in a specific folder by
+ providing the target test or folder to your favorite <tt>lit</tt> start
+ command. For example, we can run the <tt>wchar.c</tt> test:</p>
+ <pre>
+ build_ninja\bin\llvm-lit.cmd clang\test\Sema\wchar.c
+ </pre>
+ <p>or all tests in the <tt>Sema</tt> folder:</p>
+ <pre>
+ build_ninja\bin\llvm-lit.cmd clang\test\Sema
+ </pre>
- <p>You can also pass in the --no-progress-bar option if you wish to disable
- progress indications while the tests are running.</p>
+ <p>Pass in the <tt>--no-progress-bar</tt> option if you wish to disable progress
+ indications while the tests are running.</p>
<p>Your output might look something like this:</p>
>From b49ec7a794f35867d2715bbbcfacb29ff9fe6002 Mon Sep 17 00:00:00 2001
From: Henry Kleynhans <henry.kleynhans at gmail.com>
Date: Tue, 27 Jan 2026 17:47:58 +0000
Subject: [PATCH 2/2] Focus on cross-platform python script
---
clang/www/hacking.html | 39 ++++++++++++++++++---------------------
1 file changed, 18 insertions(+), 21 deletions(-)
diff --git a/clang/www/hacking.html b/clang/www/hacking.html
index c489eab54c59b..b9573a4fdf97a 100755
--- a/clang/www/hacking.html
+++ b/clang/www/hacking.html
@@ -208,48 +208,45 @@ <h3 id="testingCommands">Testing on the Command Line</h3>
<p>If you want more control over how the tests are run, it may
be convenient to run the test harness on the command-line directly. Running
- the <tt>check-clang</tt> build target will result in the
+ the <tt>check-clang</tt> build target will generate a script to start the
<a href="https://llvm.org/docs/CommandGuide/lit.html">LLVM Integrated
- Tester</a> (<tt>lit</tt>) generating a startup script to run tests for your
+ Tester</a> (<tt>lit</tt>) that can be used to run tests for your
current configuration. Once the tests have started running, you can stop
them with <tt>control+C</tt>, as the files are generated before running any
tests.</p>
<p>Once that is done, all the tests can be executed from the command line
- by running the generated <tt>llvm-lit.cmd</tt> script as follows:</p>
+ by running the generated <tt>llvm-lit.py</tt> script as follows:</p>
<pre>
- (build dir)\bin\llvm-lit.cmd (path to llvm)\clang\test
+ python (build dir)\bin\llvm-lit.py (path to llvm)\clang\test
</pre>
- For a Visual Studio Debug build in the <tt>llvm-project\build</tt> directory
- lit start command to execute from the <tt>llvm-project</tt> folder would be:
+ For example; if you have a Ninja build in the
+ <tt>llvm-project\build_ninja</tt> directory, the command to execute from the
+ <tt>llvm-project</tt> directory would be:
<pre>
- build\Debug\bin\llvm-lit.cmd clang\test
+ python build_ninja\bin\llvm-lit.py clang\test
</pre>
- If you have a Ninja build in the <tt>llvm-project\build_ninja</tt> directory,
- the command to execute from the <tt>llvm-project</tt> folder would be:
- <pre>
- build_ninja\bin\llvm-lit.cmd clang\test
- </pre>
- The LLVM Integrated Testser also generates a <tt>llvm-lit.py</tt> script
- alongside the <tt>llvm-lit.cmd</tt> script so that it can also be started
- using python directly in the event that you are not using a CMD prompt:
+ On Windows there is also a convenience CMD file <tt>llvm-lit.cmd</tt>
+ generated. Thus, if you have a Visual Studio Debug build in the
+ <tt>llvm-project\build</tt> directory, the lit start command to execute from
+ the <tt>llvm-project</tt> directory would be:
<pre>
- python.exe (path to build)\bin\llvm-lit.py (path to llvm-project)\clang\test
+ build\Debug\bin\llvm-lit.cmd clang\test
</pre>
- <p>You can also run a single test or all tests in a specific folder by
- providing the target test or folder to your favorite <tt>lit</tt> start
- command. For example, we can run the <tt>wchar.c</tt> test:</p>
+ <p>You can run a single test or all tests in a specific folder by providing
+ the target test or folder to <tt>lit</tt>. For example, we can run the
+ <tt>wchar.c</tt> test:</p>
<pre>
- build_ninja\bin\llvm-lit.cmd clang\test\Sema\wchar.c
+ python build_ninja\bin\llvm-lit.py clang\test\Sema\wchar.c
</pre>
<p>or all tests in the <tt>Sema</tt> folder:</p>
<pre>
- build_ninja\bin\llvm-lit.cmd clang\test\Sema
+ python build_ninja\bin\llvm-lit.py clang\test\Sema
</pre>
<p>Pass in the <tt>--no-progress-bar</tt> option if you wish to disable progress
More information about the cfe-commits
mailing list