Gitiles
Code Review Sign In
gerrit-public.fairphone.software / toolchain / llvm-project / eb37ec87e48ea58c2a5555faeafc7968be5738bb / . / libcxx / www / lit_usage.html
blob: 2fcb2d0a5f97944f5e18f1021a52f08d8d20aace [file] [log] [blame]
Eric Fiselier19c07162014-12-22 20:49:45 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
4<html>
5<head>
6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7 <title>Testing libc++ using LIT</title>
8 <link type="text/css" rel="stylesheet" href="menu.css">
9 <link type="text/css" rel="stylesheet" href="content.css">
10 <style>
11 .lit-option {
12 padding-top: 0.5em;
13 margin-bottom: 0.0em;
14 font-size: medium;
15 color: #2d58b7
16 }
17 .lit-option-desc {
18 display: block;
19 margin-top: 0em;
20 margin-bottom: 0em;
21 margin-left: 20px;
22 margin-right: 20px;
23 }
24 </style>
25</head>
26
27<body>
28<div id="menu">
29 <div>
30 <a href="http://llvm.org/">LLVM Home</a>
31 </div>
32
33 <div class="submenu">
34 <label>libc++ Info</label>
35 <a href="/index.html">About</a>
36 </div>
37
38 <div class="submenu">
39 <label>Quick Links</label>
Tanya Lattner29f6af32015-08-05 03:59:14 +0000[diff] [blame]40 <a href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a>
41 <a href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a>
Eric Fiselier19c07162014-12-22 20:49:45 +0000[diff] [blame]42 <a href="http://llvm.org/bugs/">Bug Reports</a>
43 <a href="http://llvm.org/svn/llvm-project/libcxx/trunk/">Browse SVN</a>
44 <a href="http://llvm.org/viewvc/llvm-project/libcxx/trunk/">Browse ViewVC</a>
45 </div>
46</div>
47
48<div id="content">
49<!--*********************************************************************-->
50 <h1>Testing libc++ using LIT</h1>
51<!--*********************************************************************-->
52<p>
53libc++ uses LIT to configure and run its tests. The primary way to run the
54libc++ tests is by using <code>make check-libcxx</code>. However since libc++
55can be used in any number of possible configurations it is important to
56customize the way LIT builds and runs the tests. This guide provides
57information on how to use LIT directly to test libc++.
58</p>
59<p>
60Documentation for LIT can be found
61<a href="http://llvm.org/docs/CommandGuide/lit.html">here</a>.
62</p>
63
64<!--*********************************************************************-->
65 <h2>Getting Started</h2>
66<!--*********************************************************************-->
67<p>
68After building libc++ use the following commands before you start using LIT to
69test.
70</p>
71<ul>
72 <li><code>alias lit='python path/to/llvm/utils/lit/lit.py'</code></li>
73 <li><code>export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg</code></li>
74</ul>
75<p>
76You can now run the libc++ tests by running:
77</p>
78<ul>
79 <li><code>cd path/to/libcxx</code></li>
80 <li><code>lit -sv ./test</code></li>
81</ul>
82<p>
83To only run a subsection of the tests use:
84<ul>
85 <li><code>lit -sv test/std/numerics # Run only the numeric tests</code></li>
86</ul>
87
88<!--*********************************************************************-->
89 <h2>Customization Options</h2>
90<!--*********************************************************************-->
91<p>
92libc++'s testsuite provides multiple options to configure the way the tests
93are build and run. To use these options you pass them on the LIT command line
94as <code>--param NAME</code> or <code>--param NAME=VALUE</code>. Some options
95have default values specified during CMake's configuration. Passing the option
96on the command line will override the default.
97</p>
98
99
100<p>
101<h3 class="lit-option">libcxx_site_config=&lt;path/to/lit.site.cfg&gt;</h3>
102<blockquote class="lit-option-desc">
103Specify the site configuration to use when running the tests. This option
104overrides the enviroment variable <code>LIBCXX_SITE_CONFIG</code>
105</blockquote>
106</p>
107
108<p>
109<h3 class="lit-option">libcxx_headers=&lt;path/to/headers&gt;</h3>
110<blockquote class="lit-option-desc">
111Specify the libc++ headers that are tested. By default the headers in the source
112tree are used.
113</blockquote>
114</p>
115
116<p>
117<h3 class="lit-option">libcxx_library=&lt;path/to/libc++.so&gt;</h3>
118<blockquote class="lit-option-desc">
119Specify the libc++ library that is tested. By default the library in the build
120directory is used. This option cannot be used when <code>use_system_lib</code>
121is provided.
122</blockquote>
123</p>
124
125<p>
126<h3 class="lit-option">use_system_lib=&lt;bool&gt;</h3>
127<blockquote class="lit-option-desc">
128<b>Default: </b><code>False</code></br>
129Enable or disable testing against the installed version of libc++ library.
130Note: This does not use the installed headers.
131</blockquote>
132</p>
133
134<p>
Eric Fiselier74e82fa2015-01-22 18:05:58 +0000[diff] [blame]135<h3 class="lit-option">use_lit_shell=&lt;bool&gt;</h3>
136<blockquote class="lit-option-desc">
137Enable or disable the use of LIT's internal shell in ShTests. If the enviroment
138variable <code>LIT_USE_INTERNAL_SHELL</code> is present then that is used as the
139default value. Otherwise the default value is <code>True</code> on Windows and
140<code>False</code> on every other platform.
141</blockquote>
142</p>
143
144<p>
Eric Fiseliera7454652015-01-16 21:22:08 +0000[diff] [blame]145<h3 class="lit-option">no_default_flags=&lt;bool&gt;</h3>
146<blockquote class="lit-option-desc">
147<b>Default: </b><code>False</code></br>
148Disable all default compile and link flags from being added. When this option is
149used only flags specified using the <code>compile_flags</code> and
150<code>link_flags</code> will be used.
151</blockquote>
152</p>
153
154<p>
Eric Fiselier19c07162014-12-22 20:49:45 +0000[diff] [blame]155<h3 class="lit-option">compile_flags="&lt;list-of-args&gt;"</h3>
156<blockquote class="lit-option-desc">
157Specify additional compile flags as a space delimited string.
158Note: This options should not be used to change the standard version used.
159</blockquote>
160</p>
161
162<p>
163<h3 class="lit-option">link_flags="&lt;list-of-args&gt;"</h3>
164<blockquote class="lit-option-desc">
165Specify additional link flags as a space delimited string.
166</blockquote>
167</p>
168
169<p>
170<h3 class="lit-option">std=&lt;standard version&gt;</h3>
171<blockquote class="lit-option-desc">
172<b>Values: </b><code>c++98, c++03, c++11, c++14, c++1z</code></br>
173Change the standard version used when building the tests.
174</blockquote>
175</p>
176
177<p>
Eric Fiselier938d9572015-02-18 17:00:31 +0000[diff] [blame]178<h3 class="lit-option">debug_level=&lt;level&gt;</h3>
179<blockquote class="lit-option-desc">
180<b>Values: </b><code>0, 1</code></br>
181Enable the use of debug mode. Level 0 enables assertions and level 1 enables
182assertions and debugging of iterator misuse.
183</blockquote>
184</p>
185
186<p>
Eric Fiselier19c07162014-12-22 20:49:45 +0000[diff] [blame]187<h3 class="lit-option">use_sanitizer=&lt;sanitizer name&gt;</h3>
188<blockquote class="lit-option-desc">
189<b>Values: </b><code>Memory, MemoryWithOrigins, Address, Undefined</code></br>
190Run the tests using the given sanitizer. If <code>LLVM_USE_SANITIZER</code>
191was given when building libc++ then that sanitizer will be used by default.
192</blockquote>
193</p>
194
Eric Fiselierda52c552015-02-18 17:39:45 +0000[diff] [blame]195<p>
196<h3 class="lit-option">color_diagnostics</h3>
197<blockquote class="lit-option-desc">
198Enable the use of colorized compile diagnostics. If the
199<code>color_diagnostics</code> option is specified or the enviroment variable
200<code>LIBCXX_COLOR_DIAGNOSTICS</code> is present then color diagnostics will be
201enabled.
202</blockquote>
203</p>
204
Eric Fiselier19c07162014-12-22 20:49:45 +0000[diff] [blame]205</div>
206</body>
207</html>